Build a real-time app with Event Streaming

This reference application show how you can use Fauna Event Streaming to build real-time apps. You can use it as a starting point for your apps.

The complete source code can be found on GitHub.

Prerequisites

  • Knowledge of Javascript, React, and Next.js

  • A Fauna account

  • Knowledge of FQL

Learning Objectives

  • How to use Event Streaming

Overview of Event Streaming

Fauna’s Event Streaming feature can manage real-time data processing in your applications. You can create and subscribe to streams for collections, indexes, or a single document.

To create a stream, write a query defining the documents to watch and convert it to a stream using toStream() or changesOn(). The following example creates a stream on a collection:

Product.all().toStream()

In the example you are you subscribing to a collection called Product. When a new document is added, updated or deleted in the Product collection, the stream emits an event.

Note: Streams are handled differently in the Fauna JavaScript driver than in the Fauna shell, dashboard or HTTP API. In the Dashboard and API, toStream() and changesOn return a stream token. The stream does not start until you subscribe to it by passing the stream token to the Stream API.

The following is another example of creating a stream using the .changesOn() method:

Product.all().changesOn(.price)

.changesOn() only creates an event when changes are made to the defined fields. In the example, it is watching for changes to the price field in the Products collection.

You can also subscribe to a single document:

let product = Product.where(.name == "cups").first()
Set.single(product).toStream()

Set up the sample application

  1. Clone the repository from GitHub:

    git clone https://github.com/fauna-labs/chat-app-streaming

  2. Install the dependencies:

    $ cd chat-app-streaming
$ npm install

  3. Next configure Fauna database. Login to your Fauna CLI with the following command:

    $ fauna cloud-login

  4. Use the Fauna CLI to create a new database:

    $ fauna create-database chat-app

  5. Migrate the schema:

    $ fauna schema push

  6. Open a shell session to run queries on your chat-app database:

    $ fauna shell chat-app

  7. Create a new key for the UnAuthenticatedRole:

    Key.create({ role: 'UnAuthenticatedRole' })
    # Output
{
  id: "395112986085163081",
  coll: Key,
  ts: Time("2024-04-14T04:12:36.920Z"),
  secret: "fnA....",
  role: "UnAuthenticatedRole"
}

  8. Create an .env file in the root directory of your project and save the generated key

    NEXT_PUBLIC_FAUNA_UNAUTHENTICATED_SECRET=<your-key>

  9. Run the application:

    $ npm run dev

  10. Open the app in your browser at http://localhost:3000

Review the application code

Viewing rooms in real time

The application is built using Next.js. In the home page /src/app/page.js, users can create chat rooms and join existing conversations.

The code uses Event Streaming to subscribe to real-time changes to the Room collection:

// ... Rest of the component's code

const response = await client.query(fql`Room.all().toStream()`);
const streamToken = response.data;

if (!streamRef.current) {
  streamRef.current = await client.stream(streamToken);
  for await (const event of streamRef.current) {
    switch (event.type) {
      case "start":
        console.log("Stream start", event);
        break;
      case "update":
      case "add":
        setExistingRooms(prevRooms => {
          const existingRoom = prevRooms.find(room => room.id ===
          event?.data.id);
          return existingRoom ? prevRooms : [...prevRooms,
          event?.data];
        });
        break;
      case "remove":
        console.log("Stream remove:", event);
        // Handles removal of rooms
        break;
      case "error":
        console.log("Stream error:", event);
        // Handles errors
        break;
    }
  }

  // Close the stream when the component unmounts
  return () => {
    streamRef.current.close();
  };
}

Real-Time Messaging

The core of a real-time chat application is its messaging functionality. You can find the code for chat functionality in the file:

const startMessageStream = async () => {
   try {
     const response = await streamClient.query(fql`
       let roomRef = Room.byId(${id})
       Message.byRoomRef(roomRef).toStream()
     `);
      const streamToken = response.data;
     if (!messageStream.current) {
       messageStream.current = await streamClient.stream(streamToken)
       .on("start", event => {
         console.log("Stream start", event);
         getExistingMessages();
       })
       .on("add", event => {
         console.log("Stream add", event);
         setMessages(prevMessages => {
          const existingMessage =
            prevMessages.find(msg => msg.id === event?.data.id);
          return existingMessage ?
            prevMessages : [...prevMessages, event?.data];
         });
       })
       .on('error', event => {
         console.log("Stream error:", event);
       });
       messageStream.current.start();
     }
   } catch (error) {
     console.error("Error fetching data:", error);
   }
 };

The code snippet demonstrates the core functionality of setting up a stream to monitor changes in the Message collection for a room with the given id.

User authentication

The sample app uses Fauna ABAC for user authentication. If you cloned the application from GitHub and ran the setup steps, you already have authentication set up. To learn more about Fauna authentication, follow the Build a user authentication system guide.

You can find the app’s authentication logic in src/app/authenticationform/page.js file:

const handleAuth = async (e) => {
  e.preventDefault();

  if (isLoginView) {
    try {
      const result = await client.query(fql`
        Login(${username}, ${password})
      `)

      const userInfo = {
        username: result?.data.user.username,
        id: result?.data.user.id,
        key: result?.data.cred.secret,
      };
      setCookieWithTTL("chat-loggedin",
      JSON.stringify(userInfo), 1440 * 60 * 1000);
      router.push('/');
    } catch (error) {
      console.log(error)
    }
  } else {
      try {
        const result = await client.query(fql`
          let user = User.byUsername(${username}).isEmpty()
          if(user == true) {
          Signup(${username}, ${password})
          } else {
          let message = "This username is already taken, select another"
            message
          }
        `)

        if (result.data == "This username is already taken, select another") {
          alert("This username is already taken, select another");
          setUsername('')
        } else {
          setIsLoginView(true);
          setUsername('');
          setPassword('');
          alert('Account created, please login now')
        }
      } catch (error) {
        console.log(error)
      }
    }
};

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!