DEV Community: Georgi Todorov

Improve child to parent communication with xState 5

Georgi Todorov — Fri, 11 Jul 2025 14:09:08 +0000

TL;DR

If you just want to see the code, it is here. And this is the PR with the latest changes that are discussed in the post.

Background

This post drifts a bit from the series, but it’s something I had been postponing for a while after switching from v4 to v5. I didn't find it that important at the time, but I've finally started deprecating the sendParent action.

Pros and cons

As stated in the xState documentation, the sendParent is no longer the preferred way to implement the child to parent communication in your machines.

There are couple of things that stopped me from doing this earlier with the adoption of v5.

I've had enough codebase to refactor and the still working sendParent didn’t feel like a priority.

Passing the parent as input and keeping it in the context felt like too much boilerplate.

At the time, I also had a mental barrier around how the parent is typed in the child machine. I expected to be able to reuse the already existing type of the parent machine, but this led to TypeScript errors beyond my knowledge and expertise. After a discussion in the XState Discord channel, this solution surfaced, though at the time, it felt hacky to me:

type ParentActor = ActorRef<Snapshot<unknown>, ParentEvents>;

However, I kept encountering bugs due to the poor TypeScript support of sendParent.

Eventually, this example was added to the XState documentation — and it finally gave me the confidence to switch:

type ChildEvent = {
  type: 'tellParentSomething';
  data?: string;
};
type ParentActor = ActorRef<Snapshot<unknown>, ChildEvent>;

const childMachine = setup({
  types: {
    context: {} as {
      parentRef: ParentActor;
    },
    input: {} as {
      parentRef: ParentActor;
    },
  },
}).createMachine({
  context: ({ input: { parentRef } }) => ({ parentRef }),
  entry: sendTo(({ context }) => context.parentRef, {
    type: 'tellParentSomething',
    data: 'Hi parent!',
  }),
});

export const parent = setup({
  actors: { child: childMachine },
}).createMachine({
  invoke: {
    src: 'child',
    input: ({ self }) => ({
      parentRef: self,
    }),
  },
  on: {
    tellParentSomething: {
      actions: log(({ event: { data } }) => `Child actor says "${data}"`),
    },
  },
});

Mapping this approach to my codebase looks like this:

// This is the parent

export type Events =
  | { type: "START_APP" }
  | { type: "SIGN_IN"; username: string }
  | { type: "SIGN_OUT" }
  | { type: "GET_USER" };

export const appMachine = setup({
  types: {
    events: {} as Events,
    context: {} as {
      refAuthenticated: AuthenticatedMachineActor | undefined;
    },
  },
  actors: {
    authenticatedMachine,
  },
  actions: {
    setRefAuthenticated: assign({
      refAuthenticated: ({ spawn, self }) => {
        return spawn("authenticatedMachine", {
          id: "authenticatedMachine",
          input: { parent: self },
        });
      },
    }),
    stopRefAuthenticated: assign({ refAuthenticated: undefined }),
  },
}).createMachine({
  id: "application",
  initial: "initializing",
  context: {
    refAuthenticated: undefined,
  },
  states: {
    // ...
    authenticated: {
      entry: ["setRefAuthenticated"],
      on: { SIGN_OUT: { target: "signingOut" } },
      exit: [stopChild("authenticatedMachine"), "stopRefAuthenticated"],
    },
    // ...
  },
});

export const AppContext = createActorContext(appMachine);

// This is the child

import { Events as ParentEvents } from "../contexts/useApp";

type ParentActor = ActorRef<Snapshot<unknown>, ParentEvents>;

export type AuthenticatedMachineActor = ActorRefFrom<
  typeof authenticatedMachine
>;

export const authenticatedMachine = setup({
  types: {
    input: {} as { parent: ParentActor },
    context: {} as {
      refParent: ParentActor;
    },
    events: {} as
      // ...
      | { type: "SIGN_OUT" },
  },
  actions: {
    sendParentSignOut({ context }) {
      context.refParent.send({ type: "SIGN_OUT" });
    },
  },
}).createMachine({
  context: ({ input }) => {
    return { refParent: input.parent, refHome: undefined, refList: undefined };
  },
  id: "authenticatedNavigator",
  // ...
  on: {
    // ...
    SIGN_OUT: { actions: ["sendParentSignOut"] },
  },
  states: {
    // ...
  },
});

One subtle difference from the documentation is that instead of using the sendTo action, I directly call context.refParent.send(...).

Also, in order to keep my codebase consistent, I try to always keep the the event types in the same file as the machine and export them as Events. Later, when needed in the child machine, I alias them as desired (ParentEvents, RootEvents, etc.)

Conclusion

I'm still not excited about passing and storing parent references in the context, but the improved typing significantly enhances the developer experience (DX).

React Native onboarding wizard with xState v5

Georgi Todorov — Mon, 24 Mar 2025 18:31:39 +0000

TL;DR

If you just want to see the code, it is here. And this is the PR with the latest changes that are discussed in the post.

Background

In a previous post, we implemented the authentication. Now, we need to gather additional user information through an onboarding flow. After authentication, users will go through a registration/onboarding process to complete their profiles.

Disclaimer

To align with the Firebase API, I've added a few methods to api.ts and improved existing ones to better simulate a real user session. There are two storages: one represents the auth table, and the other stores authenticated user details.

readFromDb - Reads data from the database, similar to Firestore document and collection queries.
onboard - Simulates a cloud function that stores newly onboarded users in the database.

New navigator

To support the onboarding flow, a new onboarding state is introduced in the appMachine. A key change is the introduction of a transitional gettingUser state, which determines whether a user proceeds directly to the app or needs onboarding.

initializing: {
  on: { START_APP: { target: "authenticating" } },
  always: [
    {
      guard: "isUserAuthenticated",
      target: "gettingUser",
    },
    { target: "authenticating" },
  ],
},
authenticating: {
  entry: ["setRefAuthenticating"],
  on: {
    SIGN_IN: {
      target: "gettingUser",
    },
  },
  exit: [stopChild("authenticatingMachine"), "stopRefAuthenticating"],
}
/* ... */
gettingUser: {
  invoke: {
    src: "getUser",
    onDone: [
      {
        guard: {
          type: "isUserOnboarded",
          params: ({ event }) => {
            return { user: event.output.user };
          },
        },
        actions: [
          {
            type: "setUser",
            params: ({ event }) => {
              return { user: event.output.user as User };
            },
          },
        ],
        target: "authenticated",
      },
      {
        target: "onboarding",
      },
    ],
  },
},

It is important to note again (following Firebase principles) that the authentication and the onboarded user concepts are distinct. The auth table stores all authenticated users, while onboarding creates a separate collection to store onboarded users linked to their auth IDs. This ensures the correct user data retrieval.

getUser: fromPromise(async () => {
  const currentUser = getCurrentUser();
  const user = await readFromDb(`users/${currentUser?.uid}`);

  return { user };
}),
signOut: fromPromise(async () => {
  await signOut();
}),

Onboarding machine

The onboarding machine itself is not too complicated. It follows a structure similar to the authenticated machine. It consists of three steps, each represented by a separate screen and child machine. These machines are spawned, stored in the context, and handled via the navigationSubscriber actor.
On the other hand, it introduces two new concepts:

Caching the step machines ensures state persistence when navigating between screens.

setRefStepOne: assign({
  refStepOne: ({ spawn, context }) => {
    return (
      context.refStepOne ??
      spawn("onboardingStepOneMachine", {
        id: "onboardingStepOneMachine",
        input: { persistedContext: context.persistedContext?.stepOne },
      })
    );
  },
})

The machine is parallel, maintaining separate steps and onboarding states to keep step screens linked to their states even during async operations.

Persistency

To enhance the user experience, we need to ensure that onboarding resumes from the exact step where the user left off, even if the app is closed or moved to the background. While xState offers deep persistency improvements with version v5, its built-in solution does not perfectly align with our app architecture.
In order to take advantage of the .getPersistedSnapshot() method, we need to store the entire application state at the root level using createActorContext. Instead, we take another approach and manually store the whole onboarding state in the local storage and reconstruct the step machines when needed.
We rely on react-native-mmkv for local storage due to its synchronous operations, making state retrieval efficient. At the end of each wizard step, we save:

The user's input from the step.
The identifier of the next step.

The stored data follows this structure:

export interface PersistedOnboardingState {
  currentStep: keyof OnboardingParamList;
  stepOne?: StepOneContext;
  stepTwo?: StepTwoContext;
  stepThree?: StepThreeContext;
}

When the app reopens, the onboarding state is retrieved from local storage and applied to the onboardingNavigator machine:

context: () => {
  const persistedOnboardingState = getOnboardingState();

  return {
    refStepOne: undefined,
    refStepTwo: undefined,
    refStepThree: undefined,
    persistedOnboardingState,
  };
},

The currentStep is passed to the OnboardingNavigator as initialRouteName:

<Stack.Navigator
initialRouteName={
  state?.context.persistedOnboardingState?.currentStep ?? "StepOne"
}
screenOptions={{
  header: (props) => {
    return (
      <OnboardingBar
        {...props}
        onGoBackPress={() => {
          actorRef?.send({ type: "GO_BACK" });
        }}
        onLogoutPress={() => {
          actorRef?.send({ type: "SIGN_OUT" });
        }}
      />
    );
  },
}}
>

TopBar

Since the onboarding process consists of multiple steps, we need an intuitive way to navigate back and forth. To handle the navigation for the onboarding wizard, we need to extend the AppBar component with custom logic.

export function OnboardingBar({
  route,
  onLogoutPress,
  onGoBackPress,
}: OnboardingBarProps) {
  return (
    <Appbar.Header>
      {route.name !== "StepOne" ? (
        <Appbar.BackAction onPress={onGoBackPress} />
      ) : null}
      <Appbar.Content title={"Onboarding"} />
      <Appbar.Action
        icon="logout"
        onPress={() => {
          onLogoutPress();
        }}
      />
    </Appbar.Header>
  );
}

The back button is only shown when the user is not on the first step.
The onGoBackPress callback sends a GO_BACK event to the onboardingNavigator machine.

Each onboarding step handles GO_BACK individually, deciding what data to persist and which screen to navigate to next.

GO_BACK: {
  actions: [
    {
      type: "persistOnboardingStep",
      params: () => {
        return { screen: "StepOne" };
      },
    },
    {
      type: "navigateToOnboardingStep",
      params: () => {
        return { screen: "StepOne" };
      },
    },
  ],
}

Result

Conclusion

I've started these series with the idea to experiment with the back then new version of xState, so that I can easily upgrade my existing codebase. Several months later I'm so used to xState v5, that I'm taking the new API for granted. Still, if I have to highlight a feature, it will be the input data mechanism and how easy to make it work with the context.

In the following post, I'm planning to work on the input validation

I started this series as an experiment with the then-new version of xState, aiming to upgrade my existing codebase smoothly. Several months later, I now take xState v5 improvements for granted.

If I had to highlight one standout feature from this functionality, it would be the input data mechanism and how seamlessly it integrates with the context. This has significantly streamlined the state management.

In the next post, I'll dive into input validation.

Real-time data with xState 5, Firebase and Next.js App Router

Georgi Todorov — Sat, 25 Jan 2025 22:27:47 +0000

TL;DR

If you just want to see the code, it is here. You can also have a look at the xState 4 implementation here.

Background

After successfully implementing the authentication flow with Firebase, my next focus for the web app is real-time updates, which I intend to achieve using Cloud Firestore.

Use case

Building upon our existing codebase, we will add functionalities for logged-in users. This includes creating a mechanism for writing and reading messages from the database, with real-time updates.

Disclaimer

For simplicity, the message text will be hardcoded. Form input and validation will be covered in a future blog post. After fetching the messages list, we will only display the number of messages.

Setting data in Firestore

The messages will consist of two properties: text and sender. The more interesting property is sender, which will hold the uid of the authenticated Firebase user who created the message.

interface Message {
  sender: string;
  text: string;
}

In the userSubscriber actor, we will extract the uid from the user parameter and pass it to the GO_TO_AUTHENTICATED event. After adding this transition, we can introduce a setUid action that reads it from the event object and sets it in the machine's context.

const appMachine = setup({
  /* ... */
  actions: {
    setUid: assign({
      uid: ({ event }) => {
        assertEvent(event, "GO_TO_AUTHENTICATED");
        return event.uid;
      },
    }),
    /* ... */
  },
  actors: {
    userSubscriber: fromCallback(({ sendBack }) => {
      const unsubscribe = onAuthStateChanged(auth, (user) => {
        if (user) {
          sendBack({ type: "GO_TO_AUTHENTICATED", uid: user.uid });
        } else {
          sendBack({ type: "GO_TO_UNAUTHENTICATED" });
        }
      });
      return () => unsubscribe();
    }),
    /* ... */
  },
}).createMachine({
  context: { uid: ""},
  invoke: { src: "userSubscriber" },
  on: {
    GO_TO_AUTHENTICATED: {
      actions: ["setUid"],
      target: ".authenticated",
    },
    /* ... */
  },
  initial: "loading",
  states: {
    loading: { tags: "loading" },
    authenticated: {
      /* ... */
    },
    /* ... */
  },
});

Now, we can proceed with creating the actual message. First, we need UI elements that trigger the event. In the root page, we add a button that initiates the process:

<button
  className="button"
  onClick={() => {
    actorRef.send({ type: "ADD_MESSAGE" });
  }}
>```
{% endraw %}


We need to implement the {% raw %}`ADD_MESSAGE`{% endraw %} event within the {% raw %}`authenticated`{% endraw %} state to ensure it's available only to existing users. This event targets the {% raw %}`.addingMessage`{% endraw %} substate, which, in turn, invokes the {% raw %}`addMessage`{% endraw %} actor.

We use the {% raw %}`setDoc`{% endraw %} Firestore method and we want our newly created messages to be organized in a messages collection. Each message will be a document with its id based on the current time in milliseconds. However, it's important to note that this approach is not recommended for production as there is still a technical chance of duplicating IDs. The message itself consists of a {% raw %}`text`{% endraw %} value (currently hardcoded) and a {% raw %}`sender`{% endraw %} that reads the authenticated user's ID from the context.

Don't forget to set your database access permissions.
{% raw %}


```typescript
import firebaseApp from "@/firebase";

/* ... */
const firestore = getFirestore(firebaseApp);

const appMachine = setup({
  /* ... */
  actors: {
    /* ... */
    addMessage: fromPromise(async ({ input }: { input: { uid: string } }) => {
      await setDoc(doc(firestore, "messages", `${Date.now()}`), {
        sender: input.uid,
        text: "Lorem Ipsumm",
      });
    }),
    /* ... */
  },
}).createMachine({
  /* ... */
  initial: "loading",
  states: {
    loading: { tags: "loading" },
    authenticated: {
      /* ... */
      on: {
        ADD_MESSAGE: { target: ".addingMessage" },
        /* ... */
      },
      initial: "idle",
      states: {
        idle: {},
        /* ... */
        addingMessage: {
          invoke: {
            src: "addMessage",
            input: ({ context }) => {
              return { uid: context.uid };
            },
            onDone: { target: "idle" },
            onError: {
              actions: ["logError"],
            },
          },
        },
      },
    },
    /* ... */
  },
});

Reading data from Firestore

With messages now being written to the database, we can proceed to demonstrate the power of Firestore in real-time updates.

To do this, we use the onSnapshot method, which attaches listeners to the parts of the database we need to monitor for changes and returns the newly updated data.

Similar to the onAuthStateChanged listener, we utilize the onSnapshot method in a actor callback. From there, we can set the retrieved messages in the context by triggering the SET_MESSAGES. This allows us to easily subscribe to the messages collection and provide the latest information to all authenticated users.

const appMachine = setup({
  /* ... */
  actions: {
    /* ... */
    setMessages: assign({
      messages: ({ event }) => {
        assertEvent(event, "SET_MESSAGES");
        return event.messages;
      },
    }),
    /* ... */
  },
  actors: {
    /* ... */
    messagesSubscriber: fromCallback(({ sendBack }) => {
      const unsubscribe = onSnapshot(
        query(collection(firestore, "messages")),
        (querySnapshot) => {
          const messages: Message[] = [];
          querySnapshot.forEach((doc) => {
            messages.push(doc.data() as Message);
          });

          sendBack({ type: "SET_MESSAGES", messages });
        }
      );

      return () => unsubscribe();
    }),
    /* ... */
  },
}).createMachine({
  context: { messages: [] },
  /* ... */
  initial: "loading",
  states: {
    loading: { tags: "loading" },
    authenticated: {
      invoke: { src: "messagesSubscriber" },
      on: {
        SET_MESSAGES: { actions: ["setMessages"] },
        /* ... */
      },
      initial: "idle",
      states: {
        idle: {},
        /* ... */
      },
    },
    /* ... */
  },
});

From this point, you can display your messages in a way that suits your application. In our case, we choose to display only the number of messages in the collection next to the Add message button.

const [state, send] = AppContext.useActor();

<span>{state.context.messages.length}</span>

Conclusion

Overall, this example sets the foundation for building real-time applications that react to dynamic data changes. From what I've experienced, the possibilities for expanding and refining this setup are extensive, making it a solid choice for developing interactive web applications.

Authentication with xState 5, Firebase and Next.js App Router

Georgi Todorov — Wed, 22 Jan 2025 12:16:18 +0000

TL;DR

If you just want to see the code, it is here. You can also have a look at the xState 4 implementation here.

Background

In our team, we've been using xState and Firebase for a couple of years to develop a mobile app, and we are naturally continuing with the same stack for the web app. I’ve already started sharing my experience with React Native and I’m planning to do the same with Next.js. To start with the authentication seems like the obvious choice.

Use case

To experiment with the authentication capabilities of the stack, we will build a simple website with two pages: a Sign In screen and a Dashboard page accessible only to authenticated users.

Disclaimers

Integrating Firebase in Next.js is quite straightforward and covered in enough online materials, so we won't discuss it in this post. The focus will be on integrating both technologies with xState. Just for clarity, here's the Firebase config file:

import { initializeApp, getApps } from "firebase/app";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_firebaseApp_ID,
};

let firebaseApp =
  getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];

export default firebaseApp;

Also, to simplify things further, we will use the signInAnonymously method, which works the same way as authenticating with email/password or phone but doesn't require user input.

Implementation

xState machine

Usually, when working with xState and React, I reach a point where I need a globally accessible machine. That's why I start by creating an appMachine and pass it to the createActorContext method so that it can be used from the React context. This way, we can keep the authentication logic in a single place and send events to/from any page.

Key parts of the machine are the root GO_TO_AUTHENTICATED and GO_TO_UNAUTHENTICATED events. They lead the user to the correct state and, respectively, to the correct screen.

The userSubscriber actor (which will be explained in a bit) plays the role of an orchestrator, which is in charge of listening for the user object from Firebase and targeting the appropriate state with the one of the already mentioned events.

The machine consists of three main states. loading is the initial state that is active until we know the user's status. After that, we transition to one of the other two states - authenticated or unauthenticated. They both have substates and are idle initially. When the user is authenticated, they can call the SIGN_OUT event to transition to the signingOut substate, which is in charge of invoking the signOut method. The unauthenticated structure is similar, with the difference that instead of signing out, it contains the signing-in logic.

import React, { PropsWithChildren } from "react";
import { setup } from "xstate";
import { createActorContext } from "@xstate/react";

const appMachine = setup(
  {
  // machine options
  },
}).createMachine({
  invoke: { src: "userSubscriber" },
  on: {
    GO_TO_AUTHENTICATED: { target: ".authenticated" },
    GO_TO_UNAUTHENTICATED: { target: ".unauthenticated" },
  },
  initial: "loading",
  states: {
    loading: { tags: "loading" },
    authenticated: {
      on: { SIGN_OUT: { target: ".signingOut" } },
      initial: "idle",
      states: {
        idle: {},
        signingOut: {
          invoke: { src: "signOut" },
          onDone: { target: "idle" },
        },
      },
    },
    unauthenticated: {
      on: { SIGN_IN: { target: ".signingIn" } },
      initial: "idle",
      states: {
        idle: {},
        signingIn: { invoke: { src: "signIn" }, onDone: { target: "idle" } },
      },
    },
  },
});

export const AppContext = createActorContext(appMachine);

export function AppProvider({ children }: PropsWithChildren<{}>) {
  return <AppContext.Provider>{children}</AppContext.Provider>;
}

Firebase

In order to retrieve the current user, Firebase recommends using the onAuthStateChanged observer, which is a perfect fit for a callback actor. In the callback, we just have to check the user value. If it is null, the user is unauthenticated; otherwise, we trigger the GO_TO_AUTHENTICATED event.

For the signIn actor, as mentioned before, we go with the signInAnonymously method, and for the signOut actor, we resolve the auth.signOut() promise. Both of these will reflect on the user that is being observed in the userSubscriber service.

import { fromCallback, fromPromise, setup } from "xstate";
import { onAuthStateChanged, getAuth, signInAnonymously } from "firebase/auth";

import firebaseApp from "@/firebase";

const auth = getAuth(firebaseApp);

const appMachine = setup({
  types: {
    events: {} as
      | { type: "GO_TO_AUTHENTICATED" }
      | { type: "GO_TO_UNAUTHENTICATED" }
      | { type: "SIGN_IN" }
      | { type: "SIGN_OUT" },
  },
  actors: {
    userSubscriber: fromCallback(({ sendBack }) => {
      const unsubscribe = onAuthStateChanged(auth, (user) => {
        if (user) {
          sendBack({ type: "GO_TO_AUTHENTICATED" });
        } else {
          sendBack({ type: "GO_TO_UNAUTHENTICATED" });
        }
      });
      return () => unsubscribe();
    }),
    signIn: fromPromise(async () => {
      await signInAnonymously(auth);
    }),
    signOut: fromPromise(async () => {
      await auth.signOut();
    }),
  },
}).createMachine(
  {
  // machine definition
  },
});

Next.js

From here, we can continue by consuming the context. Wrapping the children with AppProvider in the RootLayout gives access to the global machine from all layouts and pages.

import { AppProvider } from "@/contexts/app";
import { Loader } from "@/components/Loader";
import { StateRouter } from "@/components/StateRouter";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <AppProvider>
          <Loader>{children}</Loader>
          <StateRouter />
        </AppProvider>
      </body>
    </html>
  );
}

The purpose of the <Loader> component is to prevent pages from rendering before the user data is loaded. The AppContext.useSelector() hook always updates on state changes, and when the state is loading, we just display a placeholder screen.

"use client";

import { PropsWithChildren } from "react";
import { AppContext } from "@/contexts/app";

export function Loader({ children }: PropsWithChildren<{}>) {
  const state = AppContext.useSelector((snapshot) => {
    return snapshot;
  });

  return state.matches("loading") ? (
    <main>
      <div>Loading...</div>
    </main>
  ) : (
    children
  );
}

We handle the actual navigation in the StateRouter component. It is inspired from the router events example in the Next.js documentation. We listen for changes in the app machine state and once one of the authenticated or unauthenticated states is active, the corresponding page will be loaded. If the user already exists, they will be navigated to the dashboard, which is located at the root - /. Otherwise, they should be redirected to the /sign-in page.

"use client";

import { useEffect } from "react";
import { useRouter } from "next/navigation";
import { AppContext } from "@/contexts/app";

export function StateRouter() {
  const router = useRouter();
  const state = AppContext.useSelector((snapshot) => {
    return snapshot;
  });

  useEffect(() => {
    if (state.matches("unauthenticated")) {
      router.push("/sign-in");
    } else if (state.matches("authenticated")) {
      router.push("/");
    }
  }, [state.value]);

  return null;
}

In my experience, integrating xState with the navigation lifecycle of another framework is one of the most challenging aspects when setting up the initial application architecture. While this approach may not be the most scalable solution, it works well in terms of code separation.

Conclusion

From the little that I tried out, I'm satisfied with the results so far, but I still have concerns about how the application will grow when adding more pages and interactions with Firebase.

React Native authentication with xState v5

Georgi Todorov — Sat, 16 Nov 2024 22:19:45 +0000

TL;DR

If you just want to see the code, it is here. And this is the PR with the latest changes that are discussed in the post.

Background

This topic wasn’t my original plan for continuing the series. However, to keep the example aligned with a real-world application, I felt it was necessary to improve the authentication mechanism in terms of usability and persistence.

Disclaimer

My experience with mobile authentication is primarily focused on Firebase. To ensure consistency with its API, I’ve added a few methods to our example that mimic the lifecycle of a user session:

onAuthStateChanged - An observer that accepts a function. When a user logs in, their object is returned to the callback.
getCurrentUser - A synchronous method that returns the user object if there’s an active session; otherwise, it returns null.
signInWithPhone - This method accepts a phone number as an argument and initiates a user session on the backend.
signOut - Pretty self-explanatory. Ends the user session.

You can find their naive implementation in the api.ts file.

To ensure the data persistency, I've used react-native-mmkv.
Its synchronous methods provide a great developer experience, and the addOnValueChangedListener helped me greatly with the user session logic.

Sign in

Firstly, we start with enhancing the Authenticating screen with <TextInput/> for the user to enter their phone number. This is used as a controlled input, with the phone number value stored in the authenticating machine's context.

// ...
<TextInput
  mode="outlined"
  label="Phone number"
  value={phoneNumber}
  keyboardType="phone-pad"
  onChangeText={(value) => {
    setPhoneNumber(value);
  }}
  style={{ marginBottom: 16, width: "100%" }}
/>
<Button
  mode="contained"
  loading={isLoading}
  onPress={() => {
    onSignInPress();
  }}
>
  Sign In
</Button>
// ...

Once we click the Sign In button, we invoke the signInWithPhone method with the stores phone number, which triggers the onAuthStateChanged listener.

Since we are dealing with a listener, it’s convenient to use a callback actor. We place the actor at the root level of the authenticatingMachine to ensure it listens for changes throughout the machine’s lifespan.
When the callback actor receives user data, it knows a user session is active. At this point, the SIGN_IN event is sent to the parent machine (appMachine). Then the machine transitions to the authenticated state, which renders the stack.

At this stage, the application displays the home screen.

export const authenticatingMachine = setup({
  types: {
    context: {} as { phoneNumber: string },
    events: {} as
      | { type: "SIGN_IN" }
      | { type: "SET_SIGNED_IN_USER"; user: User }
      | { type: "NAVIGATE"; screen: keyof AuthenticatingParamList }
      | { type: "SET_PHONE_NUMBER"; phoneNumber: string },
  },
  actors: {
    signIn: fromPromise(
      async ({ input }: { input: { phoneNumber: string } }) => {
        const result = await signInWithPhone(input.phoneNumber);
        return result as { status: string; user: User };
      },
    ),
    userSubscriber: fromCallback(({ sendBack }) => {
      const subscriber = onAuthStateChanged((user) => {
        if (user) {
          sendBack({ type: "SET_SIGNED_IN_USER", user });
        }
      });

      return subscriber.remove;
    }),
  },
  actions: {
    sendParentSignIn: sendParent(
      (_, { user: { phoneNumber } }: { user: User }) => {
        return {
          type: "SIGN_IN",
          username: phoneNumber,
        };
      },
    ),
    setPhoneNumber: assign({
      phoneNumber: (_, params: { phoneNumber: string }) => {
        return params.phoneNumber;
      },
    }),
  },
}).createMachine({
  id: "authenticating",
  initial: "idle",
  context: { phoneNumber: "" },
  invoke: {
    src: "userSubscriber",
  },
  on: {
    SET_SIGNED_IN_USER: {
      actions: [
        {
          type: "sendParentSignIn",
          params: ({ event }) => {
            return { user: event.user };
          },
        },
      ],
    },
  },
  states: {
    idle: {
      on: {
        SIGN_IN: {
          target: "signingIn",
        },
        SET_PHONE_NUMBER: {
          actions: [
            {
              type: "setPhoneNumber",
              params: ({ event }) => {
                return { phoneNumber: event.phoneNumber };
              },
            },
          ],
        },
      },
    },
    signingIn: {
      invoke: {
        src: "signIn",
        input: ({ context }) => {
          return { phoneNumber: context.phoneNumber };
        },
        onDone: {
          target: "idle",
        },
      },
    },
  },
});

Persistency

The updated authentication paradigm introduces the ability to persist user credentials. Using the getCurrentUser method, we can check for user availability every time the app launches. If an active user is returned, the app navigates directly to the home screen.

In the context of xState, this is implemented with a guard and an eventless (always) transition.

//...
guards: {
  isUserAuthenticated() {
    return getCurrentUser() !== null;
  },
},
//...
initializing: {
  entry: "setRefNotificationCenter",
  on: { START_APP: { target: "authenticating" } },
  always: [
    {
      guard: "isUserAuthenticated",
      target: "authenticated",
      actions: [
        {
          type: "setUsername",
          params: () => {
            return { username: getCurrentUser()?.phoneNumber ?? "" };
          },
        },
      ],
    },
    { target: "authenticating" },
  ],
}
//...

Sign out

To allow users to log out, we add a logout button in the <Appbar.Header/> of the authenticated.navigator. This ensures it’s visible only to registered users.

<Stack.Navigator
  initialRouteName="Home"
  screenOptions={{
    header: (props) => {
      return (
        <Appbar.Header>
          {props.back ? (
            <Appbar.BackAction onPress={props.navigation.goBack} />
          ) : null}
          <Appbar.Content title={props.route.name} />
          <Appbar.Action
            icon="logout"
            onPress={() => {
              actorRef.send({ type: "SIGN_OUT" });
            }}
          />
        </Appbar.Header>
      );
    },
  }}
>

Clicking the button sends the SIGN_OUT event to the appMachine, which calls the signOut method to end the session. When the method is done, the machine transitions to the authenticating state, conditionally rendering the corresponding navigator and ensuring protected screens are no longer accessible.

Conclusion

As mentioned in previous posts, I enjoy using callback actors with Firebase/Firestore. With XState 5, actor reusability has become even more straightforward.
I’ve planned a few more posts for the coming months, but feel free to reach out if there’s something specific you’d like me to cover.

React Native notification center with xState v5

Georgi Todorov — Tue, 06 Aug 2024 12:19:16 +0000

TL;DR

If you just want to see the code, it is here. And this is the PR with the latest changes that are discussed in the post.

Disclaimer

For this example we will be using React Native Paper. It greatly helps with design and saves development time. It might take you some extra steps to integrate, but it is easy and intuitive to use.

Background

After setting the basics of the app architecture, we can now continue with the introduction of other important functionalities. In this post we will have a look at how we handle any sort of in-app notifications/messages that we want to display to the user.

While working on our application, we observed that the ways of providng the user with proper visual feedback grow. To manage all our snackbars/modals/dialogs/banners, we decided to move their orchestration in a separate machine.

Notification Center

The notificationCenter machine is spawned on project initilization. Its reference is kept at root level so that it is be available for all spawned children to communicate with.
For this example we are only handling two types of notification feedbacks but it is easily extendable.



export const notificationCenterMachine = setup({
  types: {
    context: {} as {
      snackbar: {
        type: Extract<NotificationType, "snackbar">;
        message: string;
        severity: NotificationSeverity;
      };
      modal: {
        type: Extract<NotificationType, "modal">;
        title: string;
        message: string;
      };
    },
    events: {} as
      | {
          type: "NOTIFY";
          notification: Notification;
        }
      | { type: "OPEN_SNACKBAR" }
      | { type: "OPEN_MODAL" }
      | { type: "CLOSE" },
  },
}).createMachine({
  context: {
    snackbar: {
      type: "snackbar",
      message: "",
      severity: "error",
    },
    modal: { type: "modal", message: "", title: "" },
  },
  id: "notification",
  initial: "idle",
  on: {
    NOTIFY: {
      actions: enqueueActions(({ event, enqueue }) => {
        if (event.notification.type === "snackbar") {
          enqueue.assign({ snackbar: event.notification });
          enqueue.raise({ type: "OPEN_SNACKBAR" });
        }

        if (event.notification.type === "modal") {
          enqueue.assign({ modal: event.notification });
          enqueue.raise({ type: "OPEN_MODAL" });
        }
      }),
    },
    OPEN_SNACKBAR: {
      target: ".snackbar.open",
    },
    OPEN_MODAL: {
      target: ".modal.open",
    },
  },
  type: "parallel",
  states: {
    idle: {},
    snackbar: {
      initial: "closed",
      states: { open: { on: { CLOSE: { target: "closed" } } }, closed: {} },
    },
    modal: {
      initial: "closed",
      states: { open: { on: { CLOSE: { target: "closed" } } }, closed: {} },
    },
  },
});

The machine listens for the NOTIFY event, which based on the type of notification it receives, keeps the latest notification in the context. The notification is then read and displayed/closed by the corresponding component.

Feedback

There are two components that are subscribed to the notificationCenter reference - NotificationSnackbar and NotificationModal. They expect the refNotificationCenter as prop and based on the state decide whether to show the notification. The components are rendered outside of the so that they are available to all application screens.



export function Navigation() {
  const { send, state } = useApp();

  return (
    <NavigationContainer
      onReady={() => {
        send({ type: "START_APP" });
      }}
      ref={navigationRef}
    >
      <RootNavigator />
      {state.context.refNotificationCenter && (
        <>
          <NotificationSnackbar actor={state.context.refNotificationCenter} />
          <NotificationModal actor={state.context.refNotificationCenter} />
        </>
      )}
    </NavigationContainer>
  );
}

Communication

The issue with this approach in xState v4 was that we couldn't predict how deep our actor tree would grow. Sending events between siblings and grandparents in was not straightforward. In case we needed to send an event through several levels of hierarchy, each actor should act as a middleman and resend the event to its parent until the final goal is reached.

The new actor system makes it a lot easier with the receptionist pattern. XState creates implicitly a system, which now gives us a chance to reach out the notification center by sending single event from any child machine.



sendToNotificationCenter: sendTo(
  ({ system }) => {
    return system.get("notificationCenter");
  },
  (_, params: { notification: Notification }) => {
    return {
      type: "NOTIFY",
      notification: params.notification,
    };
  },
)

Unfortunately, similarly to sendParent, we loose our type-safety. As a workaround, I'm using a simple util to guarantee that the notification is in the right format:



export function getNotificationCenterEvent(
  {},
  params: { notification: Notification },
) {
  return {
    type: "NOTIFY",
    notification: params.notification,
  };
}



sendToNotificationCenter: sendTo(({ system }) => {
  return system.get("notificationCenter");
}, getNotificationCenterEvent)

After having the action registered with the setup method, we can simply call it with:



{
  type: "sendToNotificationCenter",
  params: ({ event }) => {
    return {
      notification: {
        type: "snackbar",
        severity: "success",
        message: `You've added an item with id ${event.output.item.id}.`,
      },
    };
  },
}

You can check the end results by opening the List screen and play around with the new functionalities.

Conclusion

Leaving all the advantages aside, I was expecting better type-safety with the sendTo action in combination with the system.get() method. Currently, the situation is similar to what we can achieve with sendParent. However, the flexibility in communication provided by the receptionist pattern enhances the developer experience.
Secondly, this is the first time I've experimented with enqueueActions() and I'm beginning to see its potential. It is different from what I've been used to, but it can greatly simplify state machines.
Next, I plan to implement a registration wizard/funnel.

Improve React Navigation with xState v5

Georgi Todorov — Thu, 20 Jun 2024 13:14:09 +0000

TL;DR

If you just want to see the code, it is here. And this is the PR with the latest changes that are discussed in the post.

Introduction

This is a short follow up post that focuses on fine tuning the navigation integration. For full context refer to the previous part. The change was inspired by a discussion in the Stately discord channel, which I recommend joining.

Improvement

As I previously stated, I use xState as the backbone of the application. The end goal is to leave all the business logic and state orchestration to the machines and use the views/screens (in this case React Native ones) for the sole purpose of displaying the correct data in a fancy way. This not only makes the application framework agnostic, but also prepares it for proper model based testing.

That's why I had concerns with how the routing logic was tightly coupled with React via the useNavigator hook. When I started using React Navigation, I thought that utilising the navigation object through props is the only way to operate with the methods that it offers and a hook seemed as the obvious choice to synchronise machines and navigation. Slowly, the application evolved to rely solely on navigationRef, which left space for improvement.

Now we can move the navigation listener from the useNavigator hook into a fromCallback actor. Invoking the actor at the root level of the machine that is in charge of the navigation provides the same functionality without the need to go through the react-specific hooks.

actors: {
  homeMachine,
  listMachine,
  navigationSubscriber: fromCallback(({ sendBack }) => {
    const unsubscribe = navigationRef.addListener("state", (_event) => {
      const screenRoute = getCurrentRouteName();

      if (screenRoute) {
        sendBack({ type: "NAVIGATE", screen: screenRoute });
      }
    });

    return unsubscribe;
  }),
},

As an extra step we can abstract the actor and reuse it for other machines in charge of navigation. In my case I export it from machines/shared/actors.ts

The last thing that's worth mentioning from this PR is a small change in the naming convention. Each machine that is tied with a <Stack.Navigator> and supports the NAVIGATE event will be renamed to machineName.navigator.ts. Since all machines share the same folder, and only few of them are serving this special role, I think we can give them a visual distinguisher in the folder tree.

Conclusion

Since we have the base set up, the upcoming posts will focus on Registration Wizard and Notification System.

React Native with xState v5

Georgi Todorov — Thu, 09 May 2024 16:08:42 +0000

TL;DR

If you just want to see the code, it is here.

Disclamer

This not an introduction tutorial for xState nor React Native. It requires some basic knowledge of the libraries and won't be explaining the example code line by line. You can consider it as an opinionated guide on how to structure your application.

Background

In our team we recently released a React Native application that heavily relies on xState. As xState v5 is advancing, we decided that the time for migration from v4 has come. Since, we are already in production, we want to design it properly and use the chance to introduce some improvements along with the upgrade.
As I'm in charge of the migration, I'm planning to use this post/series as both playground and documentation. More features will be added eventually, until most of our xState cases are mimicked with version 5. I'm not going to make a comparison between v4 and v5, but instead I will set a brand new project with the latest version. Hopefully, sharing some of our key principles when working together with React Native and xState, will bring constructive feedback.

State orchestration

Working with xState and React Native, I usually build my app by integrating my view library in xState, instead of the other way round. This might feel as an overkill but I like the control it gives me over the application and how business logic organically finds its proper place in the machines, leaving the screens/components stateless.

I like to form the app around a treelike machine structure by using the actor model that xState adapts. The root is our appMachine. Its states form the flow of the application. Each state has a dedicated spawned actor that is assigned in the machine context. These actors, along with the appMachine, form the tree with its first branches.

In the appMachine's context, except the actor references, we can also keep data that is considered global for the application (profile data, languages settings, etc.).
Once having it there, we can pass it to the spawned actor children via the input prop.

On the other hand we might need the global data just for visual purposes as displaying profile settings, which makes passing it around the spawned children useless. That's why, along with the appMachine and the appProvider is introduced:

export const AppContext = createActorContext(appMachine);

export function AppProvider({ children }: React.PropsWithChildren<unknown>) {
  return <AppContext.Provider>{children}</AppContext.Provider>;
}

export function useApp() {
  const actorRef = AppContext.useActorRef();
  const state = useSelector(actorRef, (snapshot) => {
    return snapshot;
  });

  return {
    state,
    send: actorRef.send,
  };
}

And then we can consume the data from a react view:

export default React.memo(function Home({}: Props) {
  const { state } = useApp();

  return (
    <View>
      <Text>Welcome, {state.context.username}</Text>
    </View>
  );
});

It's worth mentioning that there is another approach for dealing with global state.

Navigation

In order to give meaning to our application flow, we need to visualize what our tree represents. We can achieve this by introducing a navigation instrument and my weapon of choice is React Navigation.

I found this part to be the hardest to implement but the solution has proven with time.

Following the diagram, I'll try to explain how the actor system is working with the navigation.

I've already mentioned that appMachine carries a special role when integrating with React Native and the same is valid for React Navigation.

First, we set our navigationRef. Despite it not the recommended way of navigating through screens, it might be convenient. It is really useful when you want to navigate from your machine after asynchronous actor has finished. Also, the navigationRef has different build-in methods than the standard navigation object.

export function Navigation() {
  const { send } = useApp();

  return (
    <NavigationContainer
      onReady={() => {
        send({ type: "START_APP" });
      }}
      ref={navigationRef}
    >
      <RootNavigator />
    </NavigationContainer>
  );
}

We use the onReady listener to initialize the appMachine. This way we are sure that we already have the navigationRef setup, which we will be using in a bit.

Following what we have so far, we set our appMachine to be consumed by our RootNavigator. As mentioned earlier, each root state has an actor reference that is spawned when entering the state and stopped when exiting the state. These actors become our navigator machines. They will respectively be passed as props to their own <Stack.Navigator/>. The important bit from here is that only one <Stack.Navigator/> can exist at a time, depending on the root machine state, which works great for protecting routes.

export function RootNavigator() {
  const { state } = useApp();

  const isAuthenticating = state.matches("authenticating");
  const isAuthenticated = state.matches("authenticated");

  return (
    <Stack.Navigator screenOptions={{ headerShown: false }}>
      {isAuthenticating && (
        <Stack.Screen name="Authenticating">
          {(props) => {
            return state.context.refAuthenticating ? (
              <AuthenticatingNavigator
                actorRef={state.context.refAuthenticating}
                {...props}
              />
            ) : null;
          }}
        </Stack.Screen>
      )}
      {isAuthenticated && (
        <Stack.Screen name="Authenticated">
          {(props) => {
            return state.context.refAuthenticated ? (
              <AuthenticatedNavigator
                actorRef={state.context.refAuthenticated}
                {...props}
              />
            ) : null;
          }}
        </Stack.Screen>
      )}
    </Stack.Navigator>
  );
}

When integrating xState with React Navigation, I see two possible approaches:

xState driven navigation
React Navigation driven navigation

Most of the examples/tutorials I've encountered, go with the first approach. Listening for changes in the machine state and then navigating to the corresponding page. Possibly, is the expected path when you build your app around xState. Here is a great example.

Despite that, after some experimentation, I found that this approach might lead to issues. With breaking the React Navigation declarative approach, we might loose some built in functionalities like goBack. Also, components like Bottom Tabs Navigator tend to encapsulate the event handling, which means that extra development would be required in order to work properly with the paradigm. This led me thinking that this might not be the right direction.

On the other hand, listening for changes in the navigation state and updating your machine state accordingly, leaves all the heavy lifting for React Navigation.

The implementation is not straightforward but can be gathered in several steps.

First, we need a method that gives us the current route, and again navigationRef comes to the rescue.

import { createNavigationContainerRef } from "@react-navigation/native";

export const navigationRef = createNavigationContainerRef();

export function getCurrentRouteName() {
  if (navigationRef.isReady()) {
    return navigationRef.getCurrentRoute()?.name;
  } else {
    return undefined;
  }
}

Now we can prepare our hook that will be listening for the route changes.

export function useNavigator<T>(
  callback: (route: keyof T) => void,
  initialRoute?: keyof T,
) {
  const prevRoute = useRef<string | undefined>();

  useEffect(() => {
    const unsubscribe = navigationRef.addListener("state", (_event) => {
      const screenRoute = getCurrentRouteName();

      if (screenRoute && prevRoute.current !== screenRoute) {
        prevRoute.current = screenRoute;
        callback(screenRoute as keyof T);
      } else if (!screenRoute && initialRoute) {
        callback(initialRoute);
      }
    });

    return unsubscribe;
  }, []);
}

The hook is supposed to be used only in <Stack.Navigator/>s. Each navigator's machine has a root event that handles the machine state change after the dispatched navigate. This way we synchronise the focused screen and the machine state.

export function AuthenticatedNavigator({ actorRef }: Props) {
  const state = useSelector(actorRef, (snapshot) => {
    return snapshot;
  });

  useNavigator<AuthenticatedParamList>((route) => {
    actorRef.send({ type: "NAVIGATE", screen: route });
  });

  return (
    <Stack.Navigator initialRouteName="Home">
      <Stack.Screen name="Home">
        {(props) => {
          return <HomeScreen actorRef={state.context.refHome} {...props} />;
        }}
      </Stack.Screen>
      <Stack.Screen name="List">
        {(props) => {
          return <ListScreen actorRef={state.context.refList} {...props} />;
        }}
      </Stack.Screen>
    </Stack.Navigator>
  );
}

/* ... */
NAVIGATE: [
  {
    guard: {
      type: "isHomeScreen",
      params: ({ event }) => {
        return {
          screen: event.screen,
        };
      },
    },
    target: ".homeScreen",
  },
  {
    guard: {
      type: "isListScreen",
      params: ({ event }) => {
        return {
          screen: event.screen,
        };
      },
    },
    target: ".listScreen",
  },
],
/* ... */

In a similar manner as the navigator actors, each screen might have (or not) a dedicated actor reference which will be passed as prop to the screen component and used with useSelector from there.

const state = useSelector(actorRef, (snapshot) => snapshot);

Conclusion

Instead of praising how good xState is, I would like to leave couple of words what my first impressions are after I've started writing production code with v5.
As almost in the beginning of the project, I had a transition from createModel to typegen, I ensure you that I wasn't really keen on rewriting even larger codebase with new typing approach.
To be honest, though I feel the power of the dynamic params in v5, I still have mixed feeling about ditching typegen. Despite it introduces CI complexity, I feel like it was more of a helper than a burden.
On the other hand, typing actors/actions outside of the machine is something that I'm exited about.

Real-time data with xState, Firebase and Next.js

Georgi Todorov — Mon, 16 Oct 2023 13:48:57 +0000

TL;DR

If you just want to see the code, it is here.

Background

After successfully implementing the authentication flow with Firebase, my next focus for the web app is real-time updates, which I intend to achieve using Cloud Firestore.

Use case

Building upon our existing codebase, we will add functionalities for logged-in users. This includes creating a mechanism for writing and reading messages from the database, with real-time updates.

Disclaimer

For simplicity, the message text will be hardcoded. Form input and validation will be covered in a future blog post. After fetching the messages list, we will only display the number of messages.

Setting data in Firestore

The messages will consist of two properties: text and sender. The more interesting property is sender, which will hold the uid of the authenticated Firebase user who created the message.

interface Message {
  sender: string;
  text: string;
}

In the userSubscriber service, we will extract the uid from the user parameter and pass it to the GO_TO_AUTHENTICATED event. After adding this transition, we can introduce a "setUid" action that reads it from the event object and sets it in the machine's context.

const appMachine = createMachine(
  {
    context: { uid: "" },
    /* ... */
    invoke: { src: "userSubscriber" },
    on: {
      GO_TO_AUTHENTICATED: {
        actions: ["setUid"],
        target: "authenticated",
        internal: true,
      },
    },
    /* ... */
    initial: "loading",
    states: {
      loading: { tags: "loading" },
      authenticated: {
        /* ... */
      },
      /* ... */
    },
  },
  {
    actions: {
      setUid: assign({
        uid: (context, event) => {
          return event.uid;
        },
      }),
      /* ... */
    },
    services: {
      userSubscriber() {
        return (sendBack) => {
          const unsubscribe = onAuthStateChanged(auth, (user) => {
            if (user) {
              sendBack({ type: "GO_TO_AUTHENTICATED", uid: user.uid });
            } else {
              sendBack({ type: "GO_TO_UNAUTHENTICATED" });
            }
          });
          return () => unsubscribe();
        };
      },
      /* ... */
    },
  }
);

Now, we can proceed with creating the actual message. First, we need UI elements that trigger the event. In the root page, we add a button that initiates the process:

<button
  onClick={() => {
    send({ type: "ADD_MESSAGE" });
  }}
>
  "Add message"
</button>

We need to implement the ADD_MESSAGE event within the authenticated state to ensure it's available only to existing users. This event targets the .addingMessage substate, which, in turn, invokes the addMessage service.

We use the setDoc Firestore method and we want our newly created messages to be organized in a messages collection. Each message will be a document with its id based on the current time in milliseconds. However, it's important to note that this approach is not recommended for production as there is still a technical chance of duplicating IDs. The message itself consists of a text value (currently hardcoded) and a sender that reads the authenticated user's ID from the context.

Don't forget to set your database access permissions.

import firebaseApp from "@/firebase";

/* ... */
const firestore = getFirestore(firebaseApp);

const appMachine = createMachine(
  {
    /* ... */
    initial: "loading",
    states: {
      loading: { tags: "loading" },
      authenticated: {
        invoke: { src: "messagesSubscriber" },
        on: {
          ADD_MESSAGE: { target: ".addingMessage" },
        },
        initial: "idle",
        states: {
          idle: {},
          signingOut: {
            invoke: { src: "signOut", onDone: { target: "idle" } },
          },
          addingMessage: {
            invoke: {
              src: "addMessage",
              onDone: { target: "idle" },
              onError: {
                actions: ["logError"],
              },
            },
          },
        },
      },
      /* ... */
    },
  },
  {
    /* ... */
    services: {
      /* ... */
      async addMessage(context, event) {
        await setDoc(doc(firestore, "messages", `${Date.now()}`), {
          sender: context.uid,
          text: "Lorem Ipsumm",
        });
      },
    },
  }
);

Reading data from Firestore

With messages now being written to the database, we can proceed to demonstrate the power of Firestore in real-time updates.

To do this, we use the onSnapshot method, which attaches listeners to the parts of the database we need to monitor for changes and returns the newly updated data.

Similar to the onAuthStateChanged listener, we utilize the onSnapshot method in a service callback. From there, we can set the retrieved messages in the context by triggering the SET_MESSAGES. This allows us to easily subscribe to the messages collection and provide the latest information to all authenticated users.

const appMachine = createMachine(
  {
    context: { messages: [] },
    /* ... */
    initial: "loading",
    states: {
      loading: { tags: "loading" },
      authenticated: {
        invoke: { src: "messagesSubscriber" },
        on: {
          /* ... */
          SET_MESSAGES: { actions: ["setMessages"] },
        },
        initial: "idle",
        states: {
          idle: {},
          /* ... */
        },
      },
      /* ... */
    },
  },
  {
    actions: {
      /* ... */
      setMessages: assign({
        messages: (context, event) => {
          return event.messages;
        },
      }),
    },
    services: {
      /* ... */
      messagesSubscriber() {
        return (sendBack) => {
          const unsubscribe = onSnapshot(
            query(collection(firestore, "messages")),
            (querySnapshot) => {
              const messages: Message[] = [];
              querySnapshot.forEach((doc) => {
                messages.push(doc.data().text);
              });

              sendBack({ type: "SET_MESSAGES", messages });
            }
          );

          return () => unsubscribe();
        };
      },
      /* ... */
    },
  }
);

From this point, you can display your messages in a way that suits your application. In our case, we choose to display only the number of messages in the collection next to the "Add message" button.

const [state, send] = AppContext.useActor();

<span>{state.context.messages.length}</span>

Conclusion

Authentication with xState, Firebase and Next.js

Georgi Todorov — Fri, 29 Sep 2023 16:47:03 +0000

TL;DR

If you just want to see the code, it is here.

Background

In our team, we've been using xState and Firebase for the past year for the development of a React Native application, and the time for a web version is drawing closer. Although we haven't officially settled on a framework yet, Next.js 13 is definitely on the table, and I decided that it's worth spending some time experimenting with the basic techniques and workflows so that we can make an informed decision. To start with the authentication seems like the obvious choice.

Use case

To experiment with the authentication capabilities of the stack, we will build a simple website with two pages: a Sign In screen and a Dashboard page accessible only to authenticated users.

Disclaimers

import { initializeApp, getApps } from "firebase/app";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_firebaseApp_ID,
};

let firebaseApp =
  getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];

export default firebaseApp;

Also, to simplify things further, we will use the signInAnonymously method, which works the same way as authenticating with email/password or phone but doesn't require user input.

Implementation

xState machine

Key parts of the machine are the root GO_TO_AUTHENTICATED and GO_TO_UNAUTHENTICATED events. They lead the user to the correct state and, respectively, to the correct screen. They are intentionally flagged as internal to prevent infinite loops.

The userSubscriber service (which will be explained in a bit) plays the role of an orchestrator, which is in charge of listening for the user object from Firebase and targeting the appropriate state with the one of the already mentioned events.

import React, { PropsWithChildren } from "react";
import { createMachine } from "xstate";
import { createActorContext } from "@xstate/react";

const appMachine = createMachine({
  invoke: { src: "userSubscriber" },
  on: {
    GO_TO_AUTHENTICATED: { target: "authenticated", internal: true },
    GO_TO_UNAUTHENTICATED: { target: "unauthenticated", internal: true },
  },
  initial: "loading",
  states: {
    loading: { tags: "loading" },
    authenticated: {
      on: { SIGN_OUT: { target: ".signingOut" } },
      initial: "idle",
      states: {
        idle: {},
        signingOut: {
          invoke: { src: "signOut" },
          onDone: { target: "idle" },
        },
      },
    },
    unauthenticated: {
      on: { SIGN_IN: { target: ".signingIn" } },
      initial: "idle",
      states: {
        idle: {},
        signingIn: { invoke: { src: "signIn" }, onDone: { target: "idle" } },
      },
    },
  },
  {
  /* machine options */
  }
});

export const AppContext = createActorContext(appMachine);

export function AppProvider({ children }: PropsWithChildren<{}>) {
  return <AppContext.Provider>{children}</AppContext.Provider>;
}

Firebase

In order to retrieve the current user, Firebase recommends using the onAuthStateChanged observer, which is a perfect fit for a callback service. That simplifies our work drastically. In the callback, we just have to check the user value. If it is null, the user is unauthenticated; otherwise, we trigger the GO_TO_AUTHENTICATED event.

For the signIn service, as mentioned before, we go with the signInAnonymously method, and for the signOut service, we resolve the auth.signOut() promise. Both of these will reflect on the user that is being observed in the userSubscriber service.

import { onAuthStateChanged, getAuth, signInAnonymously } from "firebase/auth";
import firebaseApp from "@/firebase";

const auth = getAuth(firebaseApp);

const appMachine = createMachine(
  {
  /* machine definition */
  },
  {
    services: {
      userSubscriber() {
        return (sendBack) => {
          const unsubscribe = onAuthStateChanged(auth, (user) => {
            if (user) {
              sendBack({ type: "GO_TO_AUTHENTICATED" });
            } else {
              sendBack({ type: "GO_TO_UNAUTHENTICATED" });
            }
          });
          return () => unsubscribe();
        };
      },
      async signIn() {
        await signInAnonymously(auth);
      },
      async signOut() {
        await auth.signOut();
      },
    },
  }
);

Next.js

From here, we can continue by consuming the context. Wrapping the children with AppProvider in the RootLayout gives access to the global machine from all layouts and pages.

import { AppProvider } from "@/contexts/app";
import { Loader } from "@/components/Loader";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <AppProvider>
          <Loader>{children}</Loader>
        </AppProvider>
      </body>
    </html>
  );
}

The purpose of the <Loader> component is to prevent pages from rendering before the user data is loaded. The AppContext.useActor() hook always updates on state changes, and when the state is loading, we just display a placeholder screen.

"use client";

import { PropsWithChildren } from "react";
import { AppContext } from "@/contexts/app";

export function Loader({ children }: PropsWithChildren<{}>) {
  const [state] = AppContext.useActor();

  return state.matches("loading") ? (
    <main>
      <div>Loading...</div>
    </main>
  ) : (
    children
  );
}

Once one of the authenticated or unauthenticated states is active, the corresponding page will be loaded. If the user already exists, they will be navigated to the dashboard, which is located at the root - /. Otherwise, they should be redirected to the /sign-in page.

From my past experience, mixing xState with the navigation lifecycle of another framework is one of the most troublesome parts when setting the initial application architecture.

I had a couple of ideas for different compositions before settling on the current implementation, but I found that I have minimal control when navigating with useRouter() in the new App Router architecture.

I wanted to trigger an event when the router.push() method is done, but it turned out that it no longer returns a promise. Also, the alternative of using the router.events didn't provide the fine control that I expected, so there was again flickering when navigating between pages.

Despite my efforts to abstract the routing in a single component or context, I ended up using protected routes. They never scale well for me, but I think they are sufficient in this scenario.

In order to prevent premature loading of the screen, we assume with the isRedirecting flag that the user is on the wrong page until proven wrong. We listen for state.value changes and redirect the user to the sign-in url if the state is unauthenticated.

In order to prevent premature loading of the screen, we assume with the isRedirecting flag that the user is on the wrong page until proven otherwise. We listen for state.value changes and redirect the user with the sign-in href if the state is unauthenticated.

export default function Home() {
  const [state, send] = AppContext.useActor();
  const router = useRouter();
  const [isRedirecting, setIsRedirecting] = useState(true);

  useEffect(() => {
    if (state.matches("unauthenticated")) {
      router.push("/sign-in");
    } else if (state.matches("authenticated")) {
      setIsRedirecting(false);
    }
  }, [state.value]);

  if (isRedirecting) {
    return null;
  }

  return (
    <main>
      <h3>Dashboard:</h3>
      <button
        onClick={() => {
          send({ type: "SIGN_OUT" });
        }}
      >
        {state.matches("authenticated.signingOut") ? "...loading" : "sign out"}
      </button>
    </main>
  );
}

Conclusion

From the little that I tried out, I'm satisfied with the results so far, but I still have concerns about how the application will grow when adding more pages and interactions with Firebase.

Sustainable xState5 machines

Georgi Todorov — Mon, 24 Jul 2023 13:37:10 +0000

TLDR

If you are curious about the full-working example, it is here.

Background

With the upcoming release of xState5, I've decided that it is time to experiment with the released beta and rethink the way I organize my machines. Rewriting this example with the new version felt like a good starting point.

Use case

Following the case from the previous part, in this one, I just want to focus on the possible improvements that come with xState5. There is a great post from Stately's blog that describes the major changes.

Spawn

With the new unified arguments object and making actors first-class citizens, spawning an actor reference feels more organic.

This is what we had so far:

import { spawn } from "xstate";

export function toggleMachineCreate({ initial = "off" }): {
  machine: ReturnType<typeof toggleMachine>;
  spawn: () => ToggleMachineActor;
} {
  const machine = toggleMachine({ initial });

  return {
    machine,
    spawn: () => spawn(machine, { name: "toggleMachine" }),
  };
}

/* ... */
assignToggleRef: assign({
  toggleRef: (context, event) => {
    return toggleMachineCreate({ initial: "on" }).spawn();
  },
/* ... */

And now we are getting the spawn method directly from the assign action:

export function toggleMachineCreate({ initial = "off" }): {
  machine: ReturnType<typeof toggleMachine>;
  spawn: () => ToggleMachineActor;
} {
  const machine = toggleMachine({ initial });

  return {
    machine,
  };
}

/* ... */
assignToggleRef: assign({
  toggleRef: ({ spawn }) => {
    return spawn(toggleMachineCreate({ initial: "on" }).machine);
  },
/* ... */

Input

The new input data paradigm is a game-changer for the way I write and use the machines. It comes in the place of the withContext method, which makes the function abstraction (toggleMachineCreate) useless.
We no longer need to create a new machine to pass the entire context but can pass our input data directly when spawning.

Instead of:

export function toggleMachineCreate({ initial = "off" }): {
  machine: ReturnType<typeof toggleMachine>;
  spawn: () => ToggleMachineActor;
} {
  const machine = toggleMachine({ initial }).withContext(...);

  return {
    machine,
  };
}

now is possible eliminate the need for the toggleMachineCreate:

/* ... */
assignToggleRef: assign({
  toggleRef: ({ spawn }) => {
    return spawn(toggleMachine({ initial: "on" }), {input: {...}});
  },
/* ... */

Function factory

With using the new beta methods, the last place where I need the factory machine function is for setting dynamic initial state, which now feels like unnecessary boilerplate code after the cleanup. After some more reading, it turned out that another approach (and the recommended one) of setting initial state is with an eventless transition:

states: {
  initializing: {
    always: [{ guard: "isChecked", target: "on" }, { target: "off" }],
  },
  off: {
    on: {
      TOGGLE: {
        target: "on",
      },
    },
  },
  on: {
    on: {
      TOGGLE: {
        target: "off",
      },
    },
  },
}

And using the machine is as simple as:

  const [state, send] = useActor(toggleMachine, {
    input: { isInitiallyChecked: true },
  });

assignToggleRef: assign({
  toggleRef: ({ spawn }) => {
    return spawn(toggleMachine, {
      input: { isInitiallyChecked: true },
    });
  },
}),

Conclusion:

From the brief encounter I had with xState5, it seems to provide a far better developer experience than its previous version. There is much more to learn during the process of upgrading my projects, but what I've already encountered looks promising.

Persistent global state with xState and Next.js

Georgi Todorov — Tue, 20 Jun 2023 12:34:24 +0000

TLDR

If you are curious about the full-working example, it is here.

Background

I recently started experimenting with Next.js 13 and thought it would be a good idea to explore some basic web application paradigms specific to the framework. One topic that always comes up is global state and its persistence, especially in combination with xState.

There is a great resource on the topic here. However, I encountered a few issues while following it, so I decided to document and share my findings.

I used the npx create-next-app@latest util to scaffold the application.

createActorContext

Recently, xState introduced a useful utility for integrating state machines with React context called createActorContext. Its implementation is straightforward. The createActorContext(machine) method takes a machine argument and returns an object that contains a Provider.

export const appMachine = createMachine({
  id: "app",
  schema: {
    events: {} as { type: "GO_TO_STATE_1" } | { type: "GO_TO_STATE_2" },
  },
  on: {
    GO_TO_STATE_1: { target: `state1`, internal: false },
    GO_TO_STATE_2: { target: `state2`, internal: false },
  },
  states: {
    state1: {},
    state2: {},
  },
});

export const AppContext = createActorContext(appMachine);

This creates a globally accessible machine that allows us to switch between different states.

As mentioned in the Next.js documentation, we cannot directly use the AppContext.Provider in the root layout without changing it to a client component with the use client directive. To address this, we can add the directive to the file containing our AppContext and prepare a wrapper for the provider that will be used in the RootLayout.

"use client";

/* ... */

export function AppProvider({ children }: PropsWithChildren<{}>) {
  return <AppContext.Provider>{children}</AppContext.Provider>;
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <AppProvider>{children}</AppProvider>
      </body>
    </html>
  );
}

Now we can consume our context from any page component and take advantage of the useActorRef and useSelector hooks provided by the createActorContext method. We can use the actor reference to send events to the appMachine, and with the useSelector hook, we can interpret the machine and reduce the number of re-renders if needed.

"use client";

import { AppContext } from "@/contexts/app";
import styles from "./page.module.css";

export default function Home() {
  const actor = AppContext.useActorRef();
  const stateValue = AppContext.useSelector((state) => state.value);

  return (
    <main className={styles.main}>
      <button
        className={`${styles.button} ${
          stateValue === "state2" ? styles.selected : ""
        }`}
        onClick={() => {
          actor.send({ type: "GO_TO_STATE_2" });
        }}
      >
        STATE 2
      </button>
      <button
        className={`${styles.button} ${
          stateValue === "state1" ? styles.selected : ""
        }`}
        onClick={() => {
          actor.send({ type: "GO_TO_STATE_1" });
        }}
      >
        STATE 1
      </button>
    </main>
  );
}

Currently, the button border of the selected state is painted in red, but we lose this styling after the browser is refreshed.

Persist and rehydrate

Before rehydrating our state, we need to store it somewhere. Since we're working on the web, the localStorage interface is a perfect choice.

To ensure that we always have the latest state in storage, we can use the third argument of the createActorContext method, which is an observer that returns the newest state of the machine on every change.

export const AppContext = createActorContext(appMachine, {}, (state) => {
  localStorage.setItem(LOCAL_STORAGE_KEY, JSON.stringify(state));
});

Now we can pass the rehydrated state to our context. The AppContext.Provider has an options prop, and for our convenience, the type of the state property in the options object is the same as the one we stored.

You can read more about why the typeof window !== "undefined" condition is needed here

function getPersistentAppState() {
  if (typeof window !== "undefined") {
    return (
      JSON.parse(localStorage?.getItem(LOCAL_STORAGE_KEY) ?? "false") ||
      appMachine.initialState
    );
  }
}

export function AppProvider({ children }: PropsWithChildren<{}>) {
  return (
    <AppContext.Provider options={{ state: getPersistentAppState() }}>
      {children}
    </AppContext.Provider>
  );
}

Finally, after selecting your desired state, you can be sure that it won't be lost.

Conclusion

I still can't fully envision xState's place in the SSR-first world, but it has once again proven itself as one of the best framework-agnostic libraries.