DEV Community: David Asaolu

Build a Google Docs-Style Editor with NextJS and Quill

David Asaolu — Thu, 13 Nov 2025 10:00:00 +0000

Real-time collaboration has become the standard for modern productivity tools, transforming how we work and interact. In this tutorial, you’ll learn how to build a Google Docs–style collaborative editor that lets multiple users create, edit, and share documents in real time.

We’ll use QuillJS to integrate a rich WYSIWYG editor, Next.js for full-stack development, and the Stream Chat SDK to synchronize live changes across users.

By the end of this tutorial, you’ll have a fully functional collaborative editor that allows teams to work together on the same document, just like in Google Docs.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We will use the following tools:

Stream React Chat SDK - Enables real-time chat communication in your application.
Stream Chat Firebase Extension - A Firebase extension that automatically connects your Firebase users to Stream.
Quill - A powerful, rich-text editor for creating and formatting documents.
Firebase - A backend-as-a-service platform developed by Google to enable us to add authentication, database, real-time communication, file storage, cloud functions, and many others within software applications.
Shadcn UI - A UI component library that provides customizable, beautifully designed, and accessible UI components for your applications.

Create a Next.js project by running the following code snippet:

npx create-next-app google-docs

Install the package dependencies for the project:

npm install firebase stream-chat stream-chat-react

To install the Shadcn UI library, follow the installation guide and add the Dialog component to the package.

Now, let's start building! 🚀

Configure Stream Chat SDK in Next.js

In this section, you will learn how to set up the Stream Chat SDK, integrate it with your Next.js application, and set up the backend functionality required to create channels using the Stream Chat SDK.

Create a free Stream account and a new organization to manage your apps.

Add a new app to the organization and copy the Stream API and Secret key into the .env.local file.

NEXT_PUBLIC_STREAM_API_KEY=<paste_from_Stream_app_dashboard>
STREAM_SECRET_KEY=<paste_from_Stream_app_dashboard>

Create an actions folder containing a stream.ts file at the root of the Next.js project.

cd google-docs && mkdir actions && \
cd actions && touch stream.ts

Copy the following code snippet into the stream.ts file:

"use server";
import { StreamChat } from "stream-chat";

const STREAM_API_KEY = process.env.NEXT_PUBLIC_STREAM_API_KEY!;
const STREAM_API_SECRET = process.env.STREAM_SECRET_KEY!;

// 👇🏻 -- For Stream Chat  --
const serverClient = StreamChat.getInstance(STREAM_API_KEY, STREAM_API_SECRET);

export async function createToken(userID: string): Promise<string> {
    if (!userID) throw new Error("User is not authenticated");
    return serverClient.createToken(userID);
}

The code snippet above initializes the Stream Chat server client using your API key and secret. Then, the createToken function is defined to generate a user authentication token for the given user's ID.

How will the Stream Chat SDK handle document changes in real time?

We’ll achieve this by leveraging Stream Channels and assigning each document to its own channel. As users modify the document, changes are sent and received within that channel, ensuring real-time synchronization across all collaborators.

Add the following code snippet to the file:

export const createChannel = async ({
    name,
    uid,
}: {
    name: string;
    uid: string;
}) => {
    try {
        //👇🏻 declare channel type
        const channel = serverClient.channel(
            "messaging",
            `${crypto.randomUUID()}`,
 {
                name: name || "Unknown",
                image: `https://api.dicebear.com/9.x/pixel-art/svg?seed=${name}`,
                members: [uid],
                created_by_id: uid,
 }
 );
        //👇🏻 create a channel
        await channel.create();
        return { success: true, error: null, id: channel.id };
 } catch (err) {
        return {
            success: false,
            error: err instanceof Error ? err.message : "Failed to create channel",
            id: null,
 };
 }
};

The createChannel function accepts a user’s name and ID, creates a unique channel for that document, and assigns the user as its creator and member. This function runs whenever a new document is created, ensuring that every document is automatically tied to a dedicated Stream channel.

Next, copy the following code snippet into the stream.ts file:

export const deleteChannel = async (id: string) => {
    try {
        const channel = serverClient.channel("messaging", id);
        await channel.delete();
        return { success: true, error: null };
 } catch (err) {
        return {
            success: false,
            error: err instanceof Error ? err.message : "Failed to delete channel",
 };
 }
};

export const getChannelById = async (id: string) => {
    try {
        const channels = await serverClient.queryChannels({ id });
        const channel = channels[0];

        if (!channel) {
            return { success: false, error: "Channel not found", id: null };
 }

        return { success: true, error: null, id: channel.id };
 } catch (err) {
        return {
            success: false,
            error: err instanceof Error ? err.message : "Failed to get channel",
            id: null,
 };
 }
};

The deleteChannel function removes a channel using its ID, and the getChannelById function retrieves a channel by its ID. You call these functions when deleting or fetching a document.

Since each document has a dedicated channel, you must delete its channel when you delete the document from the database to keep both the database and existing channels in sync.

Finally, update the Stream Chat roles and permissions as shown below:

The image above ensures that any authenticated user can view a channel (document), and all changes made to the document are propagated to other users reading the document, regardless of who created the document (channel).

Setting Up Firebase Authentication and Firestore

Firebase is a cloud platform that enables you to build full-stack software applications without worrying about managing your database or server infrastructure. It provides features like authentication, real-time database, cloud functions, file storage, and more.

In this section, you'll learn how to install Firebase and configure the Firestore Database and Firebase authentication in your Next.js application.

Install the Firebase Node.js package by running the code snippet below:

npm install firebase

Open the Firebase Console in your browser and create a new Firebase project.

Within the project dashboard, click the web icon </> to add a Firebase app to the project.

Create a lib/firebase.ts file within the Next.js src folder and paste the following code snippet into the file:

// Import the functions you need from the SDKs you need
import { initializeApp, getApps } from "firebase/app";
import { getFirestore } from "firebase/firestore";
import { GoogleAuthProvider } from "firebase/auth";
import { getAuth } from "firebase/auth";

const firebaseConfig = {
    // 👉🏻 paste your Firebase config
};

// Initialize Firebase
const app =
    getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];
const provider = new GoogleAuthProvider();
const db = getFirestore(app);
const auth = getAuth(app);

export { provider, auth };
export default db;

The code snippet above initializes the Firestore database and sets up Firebase's Google authentication provider, allowing your application to interact with the database and handle user authentication.

Next, select Authentication and Firestore Database from the sidebar menu and add them to the project.

Congratulations! You can now start interacting with these Firebase features in your Next.js project.

Installing the Stream Chat Firebase Extension

The Authenticate with Stream Chat extension automatically connects your Firebase users to Stream Chat, making it easy for Stream to access and manage your users.

Visit the Stream Chat Firebase Extension page and select the Firebase project where you want to install the extension.

Note: Upgrade your Firebase project to the Blaze (pay-as-you-go) plan before installing the extension.

During installation, enable Artifact Registry, Cloud Functions, and Secret Manager. These permissions allow Stream to access and manage your Firebase users.

Finally, enter your Stream API key and secret in the configuration fields, then click the Install Extension button.

The extension will be installed within a few minutes. Once setup is complete, every new Firebase user will automatically be added to Stream.

Building the Application Pages

In this section, you will learn how to build the application pages, which are:

Home Page: Displays a button that allows users to sign in with their Google account.
Dashboard Page: Shows all documents created by the user.
Document Page: Displays the WYSIWYG editor, allowing users to create and collaborate on a document in real-time.

Before we proceed, create a lib/server.ts file and add the following code snippet to the file:

import { signInWithPopup } from "firebase/auth";
import { FirebaseError } from "firebase/app";
import { provider, auth } from "./firebase";

//👇🏻 sign in with Google
export const signInWithGoogle = async () => {
    try {
        const { user } = await signInWithPopup(auth, provider);
        if (!user) {
            throw new Error("No user returned");
        }
        return { user, message: "User signed in successfully" };
    } catch (error) {
        const errorMessage =
            error instanceof FirebaseError ? error.message : "Error signing in";
        return { user: null, message: errorMessage };
    }
};

//👇🏻 handle log out
export const logoutUser = async () => {
    try {
        await auth.signOut();
        return { success: true, message: "User logged out successfully" };
    } catch (error) {
        console.error("Error logging out:", error);
        return { success: false, message: "Error logging out" };
    }
};

The signInWithGoogle function triggers a Google sign-in pop-up, allowing users to log into the application using their Gmail accounts. When executed, the logoutUser function signs the user out of the application.

The Home Page

Copy the following code snippet into the app/page.tsx file:

"use client";
import { signInWithGoogle } from "@/lib/server";

export default function Home() {
    const router = useRouter();

    //👇🏻 handles user sign in
    const handleSubmit = async () => {
        const { user, message } = await signInWithGoogle();
        if (user) {
            console.log("User signed in:", user);
            router.push("/dashboard");
        } else {
            console.error("Sign in failed:", message);
        }
    };

    return (
        <section>
            <h1>Collaborative Documents, Made Simple</h1>
            <p>
                Create, edit, and share documents with your team in real time — from
                anywhere.
            </p>
            <p>
                No installs, no hassle. Just open, write, and collaborate instantly.
            </p>

            <div className='flex items-center justify-center mt-8'>
                <button onClick={handleSubmit}>Log in to start</button>
            </div>
        </section>
    );
}

The code snippet above defines the application home page, which renders a sign-in button that allows users to log in using their Gmail account.

The Dashboard Page

First, create a dashboard folder containing a page.tsx file in the Next.js app folder.

cd app && \
mkdir dashboard && cd dashboard && \
touch page.tsx

Copy the following code snippet into the dashboard/page.tsx file:

"use client";
//👇🏻 type declaration for document
interface DocumentState {
    created_by: {
        name: string;
        id: string;
        date: string;
    };
    last_modified: {
        id: string;
        name: string;
        date: string;
    };
    content: string;
    title: string;
    slug: string;
}
//👇🏻 custom component
import DocBox from "../components/DocBox";

export default function DashboardPage() {
    const [documents, setDocuments] = useState<DocumentState[]>([]);

    const handleLogout = async () => {
        const { success } = await logoutUser();
        if (success) {
            router.push("/");
        }
    };

    const handleCreateDocument = async () => {
        //👉🏻 create document
    };

    return (
        <main>
            <nav>
                <h1 className='font-bold text-2xl'>Dashboard</h1>

                <div>
                    <button onClick={handleCreateDocument}>New Document</button>
                    <button onClick={handleLogout}>Log Out</button>
                </div>
            </nav>
            <section>
                {documents.map((doc) => (
                    <DocBox
                        key={doc.created_by.date}
                        title={doc.title || "Untitled Document"}
                        author={doc.created_by.name}
                        slug={doc.slug}
                    />
                ))}

                {documents.length === 0 && <p>No existing documents found</p>}
            </section>
        </main>
    );
}

From the code snippet above:

The DocumentState interface defines the data structure for each document, including the created_by and last_modified objects and the content, title, and slug values.
The DashboardPage component renders the documents array by mapping it to a DocBox component, which receives the title, author, and slug as props.

Create the DocBox component as follows:

"use client";
import { Dialog, DialogTrigger } from "@/components/ui/dialog";
import { ExternalLink, Trash2 } from "lucide-react";
import { truncateString } from "@/lib/utils";
import DeleteModal from "./DeleteModal";
import { useState } from "react";
import Link from "next/link";

export default function DocBox({
    title,
    author,
    slug,
}: {
    title: string;
    author: string;
    slug: string;
}) {
    const [deleteModalOpen, setDeleteModalOpen] = useState<boolean>(false);

    return (
        <div>
            <h3>{title}</h3>

            <p>By {author}</p>

            <div>
                <Link href={`/${slug}`} target='_blank'>
                    <ExternalLink size={24} />
                </Link>
                <Dialog open={deleteModalOpen} onOpenChange={setDeleteModalOpen}>
                    <DialogTrigger asChild>
                        <Trash2 size={24} />
                    </DialogTrigger>
                    <DeleteModal id={slug} />
                </Dialog>
            </div>
        </div>
    );
}

The DocBox component displays each document’s title and author and uses the slug to:

Generate a link that opens the document’s page in a new tab, and
Identify the document when a user wants to delete it.

Finally, add the DeleteModal component to the components folder:

import {
    DialogContent,
    DialogDescription,
    DialogHeader,
    DialogTitle,
} from "@/components/ui/dialog";

export default function DeleteModal({ id }: { id: string }) {
    const handleDelete = async () => {
        //👉🏻 trigger delete function
    };

    return (
        <DialogContent className='sm:max-w-4xl'>
            <DialogHeader>
                <DialogTitle className='text-2xl text-blue-700'>
                    Delete Document
                </DialogTitle>
                <DialogDescription>
                    Are you sure you want to delete this document?
                </DialogDescription>
            </DialogHeader>

            <div className='flex justify-end'>
                <button onClick={handleDelete}>Delete</button>
            </div>
        </DialogContent>
    );
}

Configure the WYSIWYG Editor with Quill and Stream

In this section, you’ll set up QuillJS and integrate its fully customizable WYSIWYG editor so users can create and edit documents in real time. You’ll also configure the editor to broadcast content updates to all users viewing the document.

Before we proceed, install the following Quill packages.

npm install quill quill-delta

Next, create a QuillEditor.tsx file and copy the following code snippet into the file:

"use client";
import React, {
    forwardRef,
    useEffect,
    useLayoutEffect,
    useRef,
    RefObject,
} from "react";
import Quill, { EmitterSource, QuillOptions, Range } from "quill";

// Define props interface
interface EditorProps {
    readOnly?: boolean;
    defaultValue?: string | object;
    onTextChange?: (
        delta: object,
        oldContents: object,
        source: EmitterSource
    ) => void;
    onSelectionChange?: (
        range: Range | null,
        oldRange: Range | null,
        source: EmitterSource
    ) => void;
}

The EditorProps interface defines the prop types for the Quill editor component. It specifies optional values such as readOnly, defaultValue and callback functions like onTextChange and onSelectionChange, which handle text updates and selection changes inside the editor.

Declare the QuillEditor component as shown below:

const QuillEditor = forwardRef<Quill | null, EditorProps>(
    ({ readOnly, defaultValue, onTextChange, onSelectionChange }, ref) => {
        const containerRef = useRef<HTMLDivElement | null>(null);
        const defaultValueRef = useRef<EditorProps["defaultValue"]>(defaultValue);
        const onTextChangeRef = useRef<EditorProps["onTextChange"]>(onTextChange);
        const onSelectionChangeRef =
            useRef<EditorProps["onSelectionChange"]>(onSelectionChange);

        // Keep callbacks in sync
        useLayoutEffect(() => {
            onTextChangeRef.current = onTextChange;
            onSelectionChangeRef.current = onSelectionChange;
        }, [onTextChange, onSelectionChange]);

        // Enable/disable editor when readOnly changes
        useEffect(() => {
            if ((ref as RefObject<Quill | null>)?.current) {
                (ref as RefObject<Quill | null>).current?.enable(!readOnly);
            }
        }, [ref, readOnly]);

        return <div ref={containerRef}></div>;
    }
);

QuillEditor.displayName = "QuillEditor";

export default QuillEditor;

Add the following useEffect function with the QuillEditor component to listen for changes when the user updates the editor’s content:

// Initialize Quill
useEffect(() => {
    const container = containerRef.current;
    if (!container) return;

    const editorContainer = container.ownerDocument.createElement("div");
    container.appendChild(editorContainer);

    const quill = new Quill(editorContainer, {
        theme: "snow",
    } as QuillOptions);

    // Attach quill to forwarded ref
    if (typeof ref === "function") {
        ref(quill);
    } else if (ref) {
        (ref as RefObject<Quill | null>).current = quill;
    }

    // Set default value if provided
    if (defaultValueRef.current) {
        if (typeof defaultValueRef.current === "string") {
            quill.clipboard.dangerouslyPasteHTML(defaultValueRef.current);
        } else {
            // eslint-disable-next-line @typescript-eslint/no-explicit-any
            quill.setContents(defaultValueRef.current as any);
        }
    }

    // Event listeners
    quill.on(
        "text-change",
        (delta: object, oldContents: object, source: EmitterSource) => {
            onTextChangeRef.current?.(delta, oldContents, source);
        }
    );

    quill.on(
        "selection-change",
        (range: Range | null, oldRange: Range | null, source: EmitterSource) => {
            onSelectionChangeRef.current?.(range, oldRange, source);
        }
    );

    // Cleanup
    return () => {
        if (typeof ref === "function") {
            ref(null);
        } else if (ref) {
            (ref as RefObject<Quill | null>).current = null;
        }
        container.innerHTML = "";
    };
}, [ref]);

From the code snippet above, the quill.on("text-change") event listener tracks every change made inside the editor and allows us to run custom functions whenever the document updates. We’ll use this event to broadcast changes in real-time, ensuring that all users viewing the same document stay in sync.

After declaring the QuillEditor component, the next step is integrating it into the application. Create an Editor component by copying this content into the file, and include the corresponding CSS styles in globals.css to ensure the editor is properly styled.

If you encounter any issues while setting up Quill in React applications, you can explore the official Quill React code playground.

Sending and Listening to Real-Time Events with Stream Chat SDK

Events can only be sent or received within Stream channels. This means you need to create a channel when creating a document, then wrap the Channel provider component around the Editor component to listen to updates when the user types or performs various actions within the text editor.

First, create a custom useGetStreamClient hook as follows:

import { useCreateChatClient } from "stream-chat-react";
import { createToken } from "../../../actions/stream";
import { User } from "firebase/auth";
import { useCallback } from "react";

export const useGetStreamClient = (user: User) => {
    const tokenProvider = useCallback(async () => {
        return await createToken(user.uid);
    }, [user]);

    const client = useCreateChatClient({
        apiKey: process.env.NEXT_PUBLIC_STREAM_API_KEY!,
        tokenOrProvider: tokenProvider,
        userData: {
            id: user.uid,
            name: user.displayName,
            image: `https://api.dicebear.com/9.x/pixel-art/svg?seed=${user.displayName}`,
        },
    });

    if (!client) return { client: null };

    return { client };
};

The useGetStreamClient hook generates a token for the current user and creates a chat client using the user's credentials from the user object. It then returns the chat client, which can be used to perform client-side Stream operations.

Then, create a [slug] folder containing a page.tsx file and add the following code snippet into the file:

export default function Page() {
    // get Stream client
    const { client } = useGetStreamClient(user);
    const { slug } = useParams<{ slug: string }>();
    const [channel, setChannel] = useState<ChannelType | null>(null);
    const [document, setDocument] = useState<DocumentState | null>(null);
    const [loading, setLoading] = useState<boolean>(true);

    const router = useRouter();

    const getChannel = useCallback(async () => {
        if (!slug || !client) return;
        try {
            const { id } = await getChannelById(slug);
            const { document } = await getDocumentById(slug);
            if (id && document) {
                const channels = await client.queryChannels({ id });
                const channel = channels[0];
                if (!channel) return;
                setChannel(channel);
                setDocument(document as DocumentState);
                setLoading(false);
            } else {
                router.replace("/dashboard");
            }
        } catch (error) {
            console.error("Error fetching channel:", error);
        }
    }, [slug, router, client]);

    useEffect(() => {
        getChannel();
    }, [getChannel]);

    if (loading || !client || !channel || !document)
        return (
            <div>
                <Loader2 size={30} />
            </div>
        );

    return (
        <Chat client={client} theme='messaging light'>
            <Channel channel={channel}>
                <PageComponent documentData={document} />
            </Channel>
        </Chat>
    );
}

From the code snippet above:

The Page component is responsible for rendering each document page.
The slug parameter (extracted from the URL) fetches both the document metadata and its corresponding Stream channel.
The getChannel function queries the Stream client for the channel that matches the document’s ID. If either the channel or the document does not exist after querying, the user is redirected to the dashboard. If both exist, they are stored in the local state.
While waiting for the channel, client, or document to load, a loader icon indicates progress.
Once everything is ready, the document is wrapped inside the Chat and Channel providers. This setup enables the PageComponent to send and receive real-time events in the document editor.

Render the Editor component within the PageComponent as shown below:

const PageComponent = ({ documentData }: { documentData: DocumentState }) => {
    return (
        <div>
            <Header documentData={documentData} />
            <div id='quill-container'>
                <Editor dbContent={documentData.content} />

                <div>
                    <div>
                        <h3>Document History</h3>
                        <p>Created by: {documentData?.created_by?.name}</p>
                        <p>
                            Date Created:
                            {new Date(documentData?.created_by?.date).toLocaleString()}
                        </p>
                    </div>
                </div>
            </div>
        </div>
    );
};

The code snippet above renders the WYSIWYG editor and the document’s metadata on the page.

Within the Editor component, you can send events using the useEffect hook as shown below:

import { useChannelStateContext } from "stream-chat-react";
import DeltaQuill from "quill-delta";
import Quill from "quill";

export default function Editor({ dbContent }: { dbContent: string }) {
    const { channel } = useChannelStateContext();
    const quillRef = useRef<Quill | null>(null);

    useEffect(() => {
        const quill = quillRef.current;
        if (!quill) return;

        const handleLocalChange = (
            delta: DeltaQuill,
            old: DeltaQuill,
            source: string
        ) => {
            //👇🏻 send event containing the current content
            channel.sendEvent({
                type: "text-change",
                payload: {
                    delta: quillRef.current.getContents(),
                    user_id: userIDRef.current,
                },
            });
        };
        //👇🏻execute the handleLocalChange function when text changes
        quill.on("text-change", handleLocalChange);

        return () => {
            quill.off("text-change", handleLocalChange);
        };
    }, []);
}

The useEffect hook sets up an event listener on the Quill editor to detect whenever a user changes the document. The handleLocalChange captures the editor’s content and uses the channel.sendEvent function to broadcast a custom event type to all users in real-time.

This event includes two key pieces of data:

delta: the current document content
user_id: the user's ID making the change.

You can listen for changes in the text editor using the following code snippet.

useEffect(() => {
    if (!channel) return;

    const handleDelta = (event: any) => {
        if (event.payload.user_id === userID) return;
        const incomingDelta = new DeltaQuill(event.payload.delta);
        quillRef.current?.updateContents(incomingDelta);
    };

    channel.on("text-change", handleDelta);

    return () => {
        channel.off("text-change", handleDelta);
    };
}, [channel, userID]);

The useEffect hook above listens for text-change events within the channel. When a new event arrives, it checks whether the event originated from the current user by comparing the user_id. If the event came from another user, it extracts the incoming delta and updates the Quill editor’s content using the updateContents function.

This ensures that all changes made by collaborators are reflected in the text editor in real time, while avoiding duplicate updates from the user who initially triggered the change.

Note: When a user types very quickly, the channel.sendEvent function can fire too often, sending many messages rapidly. This may exceed Stream’s rate limits. To prevent this, implement a slight delay (such as debouncing or throttling) that accumulates changes for a few seconds before sending them as a single event, as shown in the following code sample.

Saving Document Changes with Firebase Firestore

In this section, you will learn how to create functions that allow you to create a new Firebase document, update it, retrieve it by its ID, and delete it.

Execute the function below when users create a new document:

export const createDocument = async ({
    date_created,
    slug,
    created_by,
}: {
    date_created: string;
    slug: string;
    created_by: { id: string; name: string };
}) => {
    try {
        await setDoc(doc(db, "documents", slug), {
            created_by: {
                date: date_created,
                ...created_by,
            },
        });

        return { message: "Document created successfully", success: true };
    } catch (error) {
        return { success: false, message: "Error creating document" };
    }
};

The createDocument function runs concurrently with the previously declared createChannel function. It uses the channel’s ID (slug) as the document ID in Firestore and stores other metadata, ensuring that every new document has a matching Firestore record tied to its corresponding Stream channel.

Users can save changes made within the text editor when they click the Save button:

export const updateDocuments = async ({
    last_modified,
    content,
    slug,
    title,
}: {
    last_modified: {
        id: string;
        name: string;
        date: string;
    };
    content: string;
    slug: string;
    title: string;
}) => {
    try {
        await setDoc(
            doc(db, "documents", slug),
            {
                last_modified,
                content,
                title,
            },
            { merge: true }
        );
        return { message: "Document updated successfully", success: true };
    } catch (error) {
        return { success: false, message: "Error updating document" };
    }
};

The updateDocuments function accepts the document’s slug, title, content, and last_modified metadata (user ID, name, and timestamp) and merges these updates into the corresponding document record in the database.

On the dashboard page, you can retrieve all documents created by the current user with the following code snippet:

import { collection, onSnapshot, query, where } from "firebase/firestore";

useEffect(() => {
    if (!user) return;
    const q = query(
        collection(db, "documents"),
        where("created_by.id", "==", user.uid)
    );

    const unsubscribe = onSnapshot(q, (snapshot) => {
        const docs = snapshot.docs.map((doc) => ({
            slug: doc.id,
            ...doc.data(),
        })) as DocumentState[];
        setDocuments(docs);
    });

    return () => unsubscribe();
}, [user]);

To retrieve a specific document, you can query Firestore using its slug value as the document ID:

export const getDocumentById = async (slug: string) => {
    try {
        const docRef = doc(db, "documents", slug);
        const docSnap = await getDoc(docRef);
        if (docSnap.exists()) {
            return {
                document: { slug: docSnap.id, ...docSnap.data() },
                success: true,
            };
        } else {
            return { document: null, success: true, message: "Document not found" };
        }
    } catch (err) {
        return {
            document: null,
            success: false,
            message: "Error fetching document",
        };
    }
};

Lastly, execute the function below to delete a document:

export const deleteDocument = async (slug: string) => {
    try {
        await deleteDoc(doc(db, "documents", slug));
        return { success: true };
    } catch (error) {
        console.error("Error deleting document:", error);
        return { success: false, message: "Error deleting document" };
    }
};

Congratulations! You have completed this tutorial. The source code is available on GitHub.

What’s Next?

So far, you’ve learned how to integrate Stream into a Next.js application, use Firebase for authentication and database operations, and create, send, and listen to real-time events within Stream Chat channels. The application can be further enhanced by adding features such as permissions to give users read-only or editor access, as well as document sharing via invites.

Whether you’re creating a simple communication tool or a fully featured collaborative platform, Stream provides the building blocks to launch quickly, scale confidently, and operate efficiently.

Check out more tutorials on how to build powerful features and apps with Stream:

Thank you for reading! 🎉

Build a Snapchat Clone with Streaks Using Nextjs & Firebase

David Asaolu — Thu, 23 Oct 2025 10:00:00 +0000

Social messaging apps like Snapchat have unique ways of keeping users engaged daily while helping friends and loved ones stay connected. Features like real-time messaging and friendship streaks have become key elements of that experience.

In this tutorial, you’ll learn how to build a Snapchat-style app using Next.js, Firebase, and the Stream Chat SDK. We’ll cover user authentication with Firebase, real-time group messaging, and how to implement a custom streak tracking system that rewards users for staying in touch.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We will use the following tools:

Stream React Chat SDK - Enables real-time chat communication in your application.
Stream Chat Firebase Extension - A Firebase extension that automatically connects your Firebase users to Stream.
Firebase - A backend-as-a-service platform developed by Google to enable us to add authentication, database, real-time communication, file storage, cloud functions, and many others within software applications.
Date-Fns - A modern JavaScript date utility library for parsing, formatting, and manipulating dates.
Shadcn UI - A UI component library that provides customizable, beautifully designed, and accessible UI components for your applications.

Create a Next.js project by running the following code snippet:

npx create-next-app snapchat-clone

Install the package dependencies for the project:

npm install firebase stream-chat stream-chat-react date-fns

To install the Shadcn UI library, follow the installation guide and add the Dialog component to the package.

Now, let's start building! 🚀

Configure Stream Chat SDK in Next.js

In this section, you will learn how to set up the Stream Chat SDK, integrate it with your Next.js application, and set up the backend functionality required to create group channels using the Stream Chat SDK.

Create a free Stream account and a new organization to manage your apps.

Add a new app to the organization and copy the Stream API and Secret key into the .env.local file.

NEXT_PUBLIC_STREAM_API_KEY=<paste_from_Stream_app_dashboard>
STREAM_SECRET_KEY=<paste_from_Stream_app_dashboard>

# For generating user images
NEXT_PUBLIC_IMAGE_URL=https://api.dicebear.com/9.x/pixel-art/svg?seed=

Create an actions folder containing a stream.ts file at the root of the Next.js project.

cd snapchat-clone && mkdir actions && \
cd actions && touch stream.ts

Copy the following code snippet into the stream.ts file:

"use server";
import { StreamChat } from "stream-chat";

const STREAM_API_KEY = process.env.NEXT_PUBLIC_STREAM_API_KEY!;
const STREAM_API_SECRET = process.env.STREAM_SECRET_KEY!;

// 👇🏻 -- For Stream Chat  --
const serverClient = StreamChat.getInstance(STREAM_API_KEY, STREAM_API_SECRET);

export async function createToken(userID: string): Promise<string> {
    if (!userID) throw new Error("User is not authenticated");
    return serverClient.createToken(userID);
}

The code snippet above initializes the Stream Chat server client using your API key and secret. Then, the createToken function is defined to generate a user authentication token for the given user's ID.

Add the following function to the stream.ts file:

//👇🏻 generate channel ID
const generateChannelID = (channelName: string | null): string | null => {
    if (!channelName) return null;

    const sanitized = channelName.toLowerCase().replace(/\s+/g, "-");
    const randomSuffix = Math.random().toString(36).substring(2, 8);

    return `${sanitized}-${randomSuffix}`;
};

Finally, you need to define the function that allows users to create channels within this file. Copy the following code snippet:

//👇🏻 creates a Stream Channel
export const createStreamChannel = async (data: ChannelArgs) => {
    //👇🏻 accepts channel type, creator's ID, members, and group name
    const { type, userId, members, groupName } = data;

    try {
        if (type === "messaging") {
            const existingChannel = await serverClient.queryChannels(
                { type, created_by_id: userId, members },
                { last_updated: -1 },
                { limit: 1 }
            );

            // If the channel already exists, return an error
            if (existingChannel.length > 0) {
                return { success: false, error: "Channel already exists", id: null };
            }
        }
        //👇🏻 create Stream Chat channel
        const channel = serverClient.channel(
            type,
            generateChannelID(groupName!) ||
                `streak-${userId}-${Math.random().toString(36).substring(2, 8)}`,
            {
                members,
                name: groupName || `Streak with ${userId.slice(0, 6)}`,
                created_by_id: userId,
            }
        );

        await channel.create();
        return { success: true, error: null, id: channel.id };
    } catch (error) {
        return {
            success: false,
            error: error instanceof Error ? error.message : "Error creating channel",
            id: null,
        };
    }
};

From the code snippet above:

The generateChannelID function accepts the channel's name as a parameter, formats it accordingly, and merges a random 6-character string to create a unique string that can serve as the channel ID.
The createStreamChannel function accepts the channel details as parameters. If the channel type is "messaging", the function checks whether a channel with the same creator and members already exists. If it does, it returns an error.
If not, it creates a new Stream channel with the provided details and returns the channel ID.
For this tutorial, the channel type "messaging" is used for streak channels with two members only. Therefore, you can not create multiple streak channels with the same person.
The channel type "livestream" is used for group chats with multiple members.

Building the Application Pages

In this section, we will walk through the Snapchat clone's application pages and UI components.

The main pages include:

Register Page: This page displays a form that allows new users to create an account by entering a username, email, and password.
Login Page: Allows existing users to sign in to their accounts.
Chat Page: Provides a real-time chat interface where users can message, share images, and send files using the Stream Chat SDK.

The Authentication Pages: Login and Register

Add a (public) folder within the Next.js app directory. The public folder will contain the login and register page routes.

app/
└── (public)/
    ├── layout.tsx
    ├── login/
    │   └── page.tsx
    └── register/
        └── page.tsx

Copy the following code snippet into the login/page.tsx file:

"use client";
import { useRouter } from "next/navigation";
import { useState } from "react";
import Link from "next/link";

export default function Login() {
    const [buttonClicked, setButtonClicked] = useState<boolean>(false);
    const router = useRouter();

    //👇🏻 handle form submission
    const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        setButtonClicked(true);
        const form = e.currentTarget;
        const formData = new FormData(form);
        //👇🏻 logs form input to the console
        console.log("Form Data:", Object.fromEntries(formData.entries()));
    };

    return (
        <section>
            <h2>Sign into your account</h2>
            <form className='w-full' onSubmit={handleSubmit}>
                <label htmlFor='email'>Email Address</label>
                <input required type='email' id='email' name='email' />

                <label htmlFor='password'>Password</label>
                <input required type='password' id='password' name='password' />
                <button type='submit' disabled={buttonClicked}>
                    {buttonClicked ? "Signing in" : "Sign in"}
                </button>
                <p>
                    Don't have an account? <Link href='/register'>Create one</Link>
                </p>
            </form>
        </section>
    );
}

The Login component renders a form that accepts the user's email address and password and logs them to the console when the user submits the form.

Create a similar component within the register/page.tsx file. It renders a user registration form that accepts the user's name, email address, and password.

"use client";
import { useRouter } from "next/navigation";
import { useState } from "react";
import Link from "next/link";

export default function Register() {
    const router = useRouter();
    const [buttonClicked, setButtonClicked] = useState<boolean>(false);

    //👇🏻 handle form submission
    const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        setButtonClicked(true);
        const form = e.currentTarget;
        const formData = new FormData(form);
        //👇🏻 logs form input to the console
        console.log("Form Data:", Object.fromEntries(formData.entries()));
    };

    return (
        <section>
            <h2>Create your account</h2>
            <form className='w-full' onSubmit={handleSubmit}>
                <label htmlFor='username'>Username</label>
                <input required type='text' id='username' name='username' />
                <label htmlFor='email'>Email Address</label>
                <input required type='email' id='email' name='email' />

                <label htmlFor='password'>Password</label>
                <input required type='password' id='password' name='password' />

                <button type='submit' disabled={buttonClicked}>
                    {buttonClicked ? "Registering..." : "Sign up"}
                </button>
                <p>
                    Already have an account? <Link href='/login'>Sign in</Link>
                </p>
            </form>
        </section>
    );
}

Lastly, copy the following code snippet into the layout.tsx file:

import type { Metadata } from "next";
import Link from "next/link";
import { MoveRight } from "lucide-react";

export const metadata: Metadata = {
    title: "Authentication | Snapchat Clone",
    description: "Authenticate to access SnapWeb",
};

export default function AuthLayout({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    return (
        <main className='w-full min-h-screen flex items-start justify-between'>
            <nav className='w-1/4 h-screen md:block hidden'>
                <div className='w-1/4 bg-yellow-500 h-screen md:block hidden fixed top-0 z-10 p-8'>
                    <section className='absolute bottom-20 px-2 flex flex-col'>
                        <Link href='/' className='font-bold text-2xl text-gray-50'>
                            SnapWeb
                        </Link>
                        <p className='opacity-70 mt-2 text-sm'>
                            Snap and Share with friends{" "}
                            <MoveRight className='inline-block ml-1' />
                        </p>
                    </section>
                </div>
            </nav>

            {children}
        </main>
    );
}

The layout.tsx file defines page metadata (title and description) and sets up a shared layout for the authentication pages. In this example, it renders the yellow sidebar navigation on the login and register routes.

Chat Page Overview

The Chat page combines all the application’s messaging features, including group chats, streak chats with friends, and the ability to create chat channels using the Stream Chat SDK.

These features are displayed in pop-ups built with the Shadcn Dialog component. We’ll implement each of these shortly.

As shown in the video, the page is divided into two sections:

Streak chat – for one-on-one streaks between two users.
Group chat – for conversations involving multiple users.

Inside the Next.js app directory, create a components folder containing the following files:

cd app
mkdir components && cd components 
touch CreateGroupModal.tsx CreateStreakModal.tsx GroupChatPage.tsx StreakPage.tsx StreakReminderModal.tsx

The CreateGroupModal and CreateStreakModal render the forms that allow users to create a group chat or a streak channel. The GroupChatPage and StreakPage components render the chat UI elements for the group and streak chats.

The StreakReminderModal component notifies users when they need to send a message to maintain their daily streak.

Chat Page Code Walkthrough

Inside the app directory, create a chat folder, then add a page.tsx file inside it.

cd app && \ mkdir chat &&\
cd chat && touch page.tsx

Import the following components into the chat/page.tsx file:

"use client";
//👇🏻 Shadcn UI Dialog components
import { Dialog, DialogTrigger } from "@/components/ui/dialog";

//👇🏻 streak reminder pop-up
import StreakReminderModal from "../components/StreakReminderModal";

//👇🏻 group creation modals/pop-ups
import CreateStreakModal from "@/app/components/CreateStreakModal";
import CreateGroupModal from "@/app/components/CreateGroupModal";

//👇🏻 streaks and group chat UI elements
import GroupChatPage from "@/app/components/GroupChatPage";
import StreakPage from "@/app/components/StreakPage";

//👇🏻 UI elements and navigation bar component
import { Plus } from "lucide-react";
import { useState } from "react";

Add the following code snippets to the file:

export default function ChatPage() {
    //👇🏻 state toggle between streak/group chat UI
    const [showGroupChat, setShowGroupChat] = useState<boolean>(false);
    //👇🏻 state to open/close streak modal
    const [openStreakModal, setOpenStreakModal] = useState<boolean>(false);
    //👇🏻 state to open/close group modal
    const [openGroupModal, setOpenGroupModal] = useState<boolean>(false);
    //👇🏻 state to open/close streak reminder modal
    const [streakReminder, setStreakReminder] = useState<boolean>(false);
    //👇🏻 state for streak reminder message
    const [reminderMessage, setReminderMessage] = useState<string>("");

    return (
        <main>
            <div>
                <section>
                    {/** -- Streak Group section -- **/}
                    <div
                        className={` ${!showGroupChat ? "bg-yellow-100" : ""}`}
                        onClick={() => setShowGroupChat(false)}
                    >
                        <h3>Friends Streak</h3>
                        <Dialog open={openStreakModal} onOpenChange={setOpenStreakModal}>
                            <DialogTrigger asChild>
                                {!showGroupChat && (
                                    <span>
                                        <Plus size={20} />
                                    </span>
                                )}
                            </DialogTrigger>
                            {/** -- create Streak modal -- **/}
                            <CreateStreakModal setOpen={setOpenStreakModal} />
                        </Dialog>
                    </div>
                    {/** -- Group Chat section -- **/}
                    <div
                        className={`${showGroupChat ? "bg-yellow-100" : ""}`}
                        onClick={() => setShowGroupChat(true)}
                    >
                        <h3>Group Chats</h3>
                        <Dialog open={openGroupModal} onOpenChange={setOpenGroupModal}>
                            <DialogTrigger asChild>
                                {showGroupChat && (
                                    <span>
                                        <Plus size={20} />
                                    </span>
                                )}
                            </DialogTrigger>
                            {/** -- create group chat modal -- **/}
                            <CreateGroupModal setOpen={setOpenGroupModal} />
                        </Dialog>
                    </div>
                </section>

                {/** -- Switch page contents -- **/}
                <section>
                    {showGroupChat ? (
                        <GroupChatPage />
                    ) : (
                        <StreakPage
                            setReminderMessage={setReminderMessage}
                            setStreakReminder={setStreakReminder}
                        />
                    )}
                </section>
            </div>

            {/** -- Streak Reminder component -- **/}
            <Dialog open={streakReminder} onOpenChange={setStreakReminder}>
                <StreakReminderModal reminderMessage={reminderMessage} />
            </Dialog>
        </main>
    );
}

From the code snippet above:

setShowGroupChat – Toggles between the streak chat and group chat interfaces.
setOpenStreakModal and setOpenGroupModal – Control the open/close state of the streak and group channel creation pop-ups.
reminderMessage – Stores the text displayed in the streak reminder modal.
setStreakReminder – Opens or closes the streak reminder pop-up.

This setup allows users to switch between group and streak chats, create new channels, and receive streak reminders without leaving the chat page.

Copy the following code snippet into the StreakReminderModal.tsx file:

import {
    DialogHeader,
    DialogContent,
    DialogTitle,
    DialogDescription,
} from "@/components/ui/dialog";

export default function StreakReminderModal({
    reminderMessage,
}: {
    reminderMessage: string;
}) {
    return (
        <DialogContent className='sm:max-w-4xl bg-red-600'>
            <DialogHeader>
                <DialogTitle className='text-2xl text-gray-50 text-center'>
                    Streak Reminder 🔥
                </DialogTitle>
                <DialogDescription className='text-red-200 text-center'>
                    Keep streaks! Message friends daily to maintain your streak.
                </DialogDescription>
            </DialogHeader>
            <div className='flex flex-col items-center justify-center space-y-4'>
                <p className='font-bold text-gray-50'>{reminderMessage}</p>
            </div>
        </DialogContent>
    );
}

The code snippet accepts the streak reminder message as a prop and displays it to the user when they are missing a streak or haven't exchanged messages for the day.

Next, you can create the CreateGroupModal and CreateStreakModal components.

Copy the following code snippet into the CreateGroupModal.tsx file:

"use client";
import {
    DialogContent,
    DialogDescription,
    DialogHeader,
    DialogTitle,
} from "@/components/ui/dialog";
import { Dispatch, useContext, useState } from "react";

export default function CreateGroupModal({
    setOpen,
}: {
    setOpen: Dispatch<React.SetStateAction<boolean>>;
}) {
    const [isLoading, setIsLoading] = useState<boolean>(false);

    const handleCreateGroup = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        setIsLoading(true);
        const formData = new FormData(e.currentTarget);
        console.log("Form Data:", Object.fromEntries(formData.entries()));
    };

    return (
        <DialogContent className='sm:max-w-4xl'>
            <DialogHeader>
                <DialogTitle>Group Chat</DialogTitle>
                <DialogDescription>
                    Create a group chat with loved ones and stay connected!
                </DialogDescription>
            </DialogHeader>

            <form onSubmit={handleCreateGroup}>
                <input
                    type='text'
                    name='groupName'
                    placeholder='Group Name'
                    id='groupName'
                    required
                />

                <input
                    type='text'
                    name='members'
                    placeholder="Members' Username (comma separated)"
                    id='members'
                    required
                />
                <button type='submit' disabled={isLoading}>
                    {isLoading ? "Creating..." : "Create Group"}
                </button>
            </form>
        </DialogContent>
    );
}

The code snippet above renders a form that accepts the name and members for the group chat.

Finally, copy the following code snippet into the CreateStreakModal.tsx file:

"use client";
import {
    DialogContent,
    DialogDescription,
    DialogHeader,
    DialogTitle,
} from "@/components/ui/dialog";
import { Dispatch, useContext, useState } from "react";

export default function CreateStreakModal({
    setOpen,
}: {
    setOpen: Dispatch<React.SetStateAction<boolean>>;
}) {
    const [isLoading, setIsLoading] = useState<boolean>(false);

    const createStreakGroup = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        if (!user || !user.displayName) return;
        setIsLoading(true);
        const formData = new FormData(e.currentTarget);
        console.log("Form Data:", Object.fromEntries(formData.entries()));
    };

    return (
        <DialogContent>
            <DialogHeader>
                <DialogTitle>Streak with Friends</DialogTitle>
                <DialogDescription>
                    Keep streaks! Message friends daily to maintain your streak.
                </DialogDescription>
            </DialogHeader>

            <form onSubmit={createStreakGroup}>
                <input
                    type='text'
                    name='username'
                    placeholder="Friend's Username"
                    id='username'
                    required
                />

                <button type='submit' disabled={isLoading}>
                    {isLoading ? "Creating..." : "Create Streak"}
                </button>
            </form>
        </DialogContent>
    );
}

The CreateStreakModal component also renders the form that accepts the username of the other member of the streak chat group.

Setting Up Firebase Authentication and Firestore

In this section, you'll learn how to install Firebase and configure the Firestore Database and Firebase authentication in your Next.js application.

Install the Firebase Node.js package by running the code snippet below:

npm install firebase

Open the Firebase Console in your browser and create a new Firebase project.

Within the project dashboard, click the web icon </> to add a Firebase app to the project.

Create a lib/firebase.ts file within the Next.js src folder and paste the following code snippet into the file:

import { initializeApp, getApps } from "firebase/app";
import { getFirestore } from "firebase/firestore";
import { EmailAuthProvider } from "firebase/auth";
import { getAuth } from "firebase/auth";

const firebaseConfig = {
    // 👉🏻 paste your Firebase config
};

//👇🏻 Initialize Firebase
const app =
    getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];
const provider = new EmailAuthProvider();
const db = getFirestore(app);
const auth = getAuth(app);

//👇🏻 Export modules
export { provider, auth };
export default db;

The code snippet above initializes the Firestore database and sets up Firebase's email/password authentication provider, allowing your application to interact with the database and handle user authentication.

Next, select "Authentication" and "Firestore Database" from the sidebar menu and add them to the project.

Congratulations! You can now start interacting with these Firebase features in your Next.js project.

Installing the Stream Chat Firebase Extension

The Authenticate with Stream Chat extension automatically connects your Firebase users to Stream Chat, making it easy for Stream to access and manage your users.

Visit the Stream Chat Firebase Extension page and select the Firebase project where you want to install the extension.

Note: Upgrade your Firebase project to the Blaze (pay-as-you-go) plan before installing the extension.

During installation, enable Artifact Registry, Cloud Functions, and Secret Manager. These permissions allow Stream to access and manage your Firebase users.

Finally, enter your Stream API key and secret in the configuration fields, then click the Install Extension button.

The extension will be installed within a few minutes. Once setup is complete, every new Firebase user will automatically be added to Stream.

Implement Authentication and Database Operations in Firebase

In this section, you will learn how to authenticate users with Firebase and create the database function that updates the users' chat streaks.

Create a server.ts within the lib folder and copy the following code snippet into the file:

import {
    createUserWithEmailAndPassword,
    signInWithEmailAndPassword,
    updateProfile,
} from "firebase/auth";

import {
    doc,
    getDoc,
    runTransaction,
    serverTimestamp,
} from "firebase/firestore";
import db, { auth } from "./firebase";

Next, add a registerUser function that accepts the new user's email, password, and username from the form and creates a new account for the user.

export const registerUser = async (form: FormData) => {
    //👇🏻 get form inputs
    const email = form.get("email") as string;
    const password = form.get("password") as string;
    const usernameRaw = form.get("username") as string;
    //👇🏻 make username lowercase
    const username = usernameRaw.trim().toLowerCase();
    //👇🏻 creates a db reference for username
    const userRef = doc(db, "users", username);

    /**
 1.  ensures that no user has the same username
 2.  creates an account using the user details
 3.  update profile details, such as displayName and photoURL
 4.  add the user details to the Firestore users collection
 **/
};

Update the registerUser function as follows:

export const registerUser = async (form: FormData) => {
    const email = form.get("email") as string;
    const password = form.get("password") as string;
    const usernameRaw = form.get("username") as string;
    const username = usernameRaw.trim().toLowerCase();
    const userRef = doc(db, "users", username);

    try {
        //👇🏻 Check if the username already exists
        await runTransaction(db, async (transaction) => {
            const userDoc = await transaction.get(userRef);
            if (userDoc.exists()) {
                throw new Error("Username already exists");
            }

            //👇🏻 Create user in Firebase Auth
            const { user } = await createUserWithEmailAndPassword(
                auth,
                email,
                password
            );

            //👇🏻 Set displayName and photoURL
            await updateProfile(user, {
                displayName: username,
                photoURL: `${process.env.NEXT_PUBLIC_IMAGE_URL}${username}`,
            });
            //👇🏻 Save user profile in Firestore
            transaction.set(userRef, {
                uid: user.uid,
                email: user.email,
                username,
                photoURL: `${process.env.NEXT_PUBLIC_IMAGE_URL}${username}`,
                createdAt: serverTimestamp(),
            });
        });

        return {
            code: "auth/success",
            status: 200,
            user: auth.currentUser,
            message: "Account created successfully! 🎉",
        };
    } catch (err: any) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: err.message,
            error: err,
        };
    }
};

The registerUser function first checks whether the chosen username already exists in the database. If the username is available, it creates a new account for the user, updates the user’s display name and photo URL, and then saves the user’s details in the Firestore users collection.

Add the user login function to the server.ts file:

export const loginUser = async (form: FormData) => {
    const email = form.get("email") as string;
    const password = form.get("password") as string;
    try {
        const { user } = await signInWithEmailAndPassword(auth, email, password);

        return {
            code: "auth/success",
            status: 200,
            user,
            message: "Logged in successfully! 🎉",
        };
    } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to login user",
            error: err,
        };
    }
};

The code snippet above accepts the user's email address and password from the form and signs users into the application.

To log users out of the application, add the following code snippet to the server.ts file:

export const logoutUser = async () => {
    try {
        await auth.signOut();
        return {
            code: "auth/success",
            status: 200,
            user: null,
            message: "Logged out successfully! 🎉",
 };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to logout user",
            error: err,
 };
 }
};

To prevent unauthenticated users from accessing the chat page, we’ll wrap an authentication context around it.

Create a new file called AuthContext.tsx and add the following code:

"use client";
import { createContext, useState, useEffect } from "react";
import { onAuthStateChanged, User } from "firebase/auth";
import { useRouter } from "next/navigation";
import { auth } from "@/lib/firebase";
import { Loader2 } from "lucide-react";

const AuthContext = createContext<{
    user: User | null;
    loading: boolean;
}>({
    user: null,
    loading: true,
});

export function AuthProvider({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    const [user, setUser] = useState<User | null>(null);
    const [loading, setLoading] = useState(true);
    const router = useRouter();

    useEffect(() => {
        const unsubscribe = onAuthStateChanged(auth, async (user) => {
            if (user?.uid) {
                setUser(user);
                setLoading(false);
            } else {
                return router.push("/login");
            }
        });

        return () => unsubscribe();
    }, [router]);

    return (
        <>
            {user ? (
                <AuthContext.Provider value={{ loading, user }}>
                    {children}
                </AuthContext.Provider>
            ) : (
                <main className='flex items-center justify-center h-screen'>
                    <Loader2 />
                </main>
            )}
        </>
    );
}

export default AuthContext;

The AuthContext provider retrieves the current Firebase user. If a user is authenticated, it returns the user object and sets the loading state to false. If no user is found, it returns null and redirects the user to the login page.

Wrap the chat/layout.tsx file with the <AuthProvider/> component as shown below:

import { AuthProvider } from "../(components)/AuthContext";
import type { Metadata } from "next";

export const metadata: Metadata = {
    title: "Streaks & Group Chats | Snapchat Clone",
    description:
        "Discover and connect with friends through streaks and group chats.",
};

export default function AuthLayout({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    return (
 <AuthProvider>
 <main>{children}</main>
 </AuthProvider>
 );
}

Finally, add the following utility functions to the file:

//👇🏻 get user IDs via usernames
export const getUserIDsByUsernames = async (
    usernames: string[]
): Promise<string[]> => {
    const memberIDs: string[] = [];

    for (const name of usernames) {
        const userRef = doc(db, "users", name.trim().toLowerCase());
        const userDoc = await getDoc(userRef);

        if (userDoc.exists()) {
            const uid = userDoc.data().uid as string;
            memberIDs.push(uid);
        }
    }

    return memberIDs;
};

//👇🏻 get username by ID
export const getUsernameById = (
    members: Record<string, ChannelMemberResponse>,
    userId: string
): string | null => {
    for (const key in members) {
        const member = members[key];
        if (member.user_id === userId) {
            return member.user?.name ?? null; // adjust to `.displayName` if needed
        }
    }
    return null;
};

The getUserIDsByUsernames function accepts the array of usernames provided when creating a group chat. It then looks up each username in the Firestore users collection, retrieves the corresponding uid and returns an array of all the user IDs.

The getUsernameById function accepts a list of chat members and a specific user ID, loops through the members list, then finds and returns the corresponding username.

Create Chat Channels with the Stream Chat SDK

In this section, you’ll learn how to create new channels and build a chat interface using the customizable UI components provided by the Stream Chat SDK.

Before we proceed, recall that we added a createStreamChannel function to the stream.ts file. This function accepts the channel type, creator’s ID, group members, and group name as parameters and creates a Stream channel.

Inside CreateGroupModal.tsx, execute the function below when a user submits the form containing the group name and list of members:

//👇🏻 gets current user object from the Auth context
const { user } = useContext(AuthContext);

const handleCreateGroup = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);

    //👇🏻 group name and members
    const groupName = formData.get("groupName") as string;
    const rawMembers = formData.get("members") as string;

    //👇🏻 formatting the group members' names
    const members = rawMembers
        .split(",")
        .map((member) => member.trim() && member.trim().toLowerCase())
        .filter(Boolean);

    //👇🏻 retrieves their id
    const memberIDs = await getUserIDsByUsernames(members);

    // 👇🏻 returns an error if usernames are invalid
    if (!memberIDs || memberIDs.length == 0) {
        setIsLoading(false);
        return;
    }

    //👇🏻 creates the group using the data provided
    const { success } = await createStreamChannel({
        type: "livestream",
        userId: user.uid,
        members: [user.uid, ...memberIDs],
        groupName,
    });
    //👇🏻 close modal
    if (success) {
        setOpen(false);
    }
};

From the code snippet above:

The handleCreateGroup function runs when the user submits the form to create a group channel for multiple participants. It retrieves the group name and list of members.
The members list is cleaned (trimmed and converted to lowercase) and passed as an argument to the getUserIDsByUsernames function to fetch their corresponding user IDs.
Finally, the members' IDs, current user IDs, group names, and channel types are provided to the createStreamChannel function, which creates the new group channel.

To create the streak chat group, execute the following function when a user submits the form within the CreateStreakModal component:

const createStreakGroup = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const username = formData.get("username") as string;

    //👇🏻 get user ID
    const memberIDs = await getUserIDsByUsernames([username]);

    //👇🏻 returns an error if username is invalid
    if (!memberIDs || memberIDs.length === 0) {
        setIsLoading(false);
        return;
    }

    //👇🏻 creates a group channel
    const { success } = await createStreamChannel({
        type: "messaging",
        userId: user.uid,
        members: [user.uid, ...memberIDs],
    });

    //👇🏻 returns the corresponding message/result
    if (success) {
        setOpen(false);
    }
};

From the code snippet above:

The createStreakGroup function is triggered when a user creates a one-on-one streak chat channel with a friend. It retrieves the friend’s username from the form input.
The friend’s username is passed into the getUserIDsByUsernames function to retrieve their corresponding user ID. If the username is invalid, an error is displayed.
The channel type (messaging), current user ID, and member IDs array are then passed into the createStreamChannel function to create the streak chat channel.

Stream Chat UI Components

The Stream Chat SDK provides various UI components that simplify the process of building a fully functional and customizable chat interface. These components enable users to send messages, attach files, and view recent messages in a channel.

To begin, create a useGetStreamClient.ts file that returns a Stream Chat client capable of querying channel messages within the app components.

import { useCreateChatClient } from "stream-chat-react";
import { createToken } from "../../../actions/stream";
import { useCallback } from "react";
import { User } from "firebase/auth";

export const useGetStreamClient = (user: User) => {
    const tokenProvider = useCallback(async () => {
        return await createToken(user.uid);
    }, [user]);

    const client = useCreateChatClient({
        apiKey: process.env.NEXT_PUBLIC_STREAM_API_KEY!,
        tokenOrProvider: tokenProvider,
        userData: {
            id: user.uid,
            name: user.displayName!,
            image: user.photoURL || "",
        },
    });

    if (!client) return { client: null };

    return { client };
};

The useGetStreamClient hook generates a token for the current user and creates a chat client using the user's credentials from the user object. It then returns the chat client, which can be used to perform client-side Stream operations.

Update the GroupChatPage component to render the chat UI, enabling users to send messages and also view recent messages.

"use client";
import {
    Chat,
    Channel,
    ChannelList,
    Window,
    ChannelHeader,
    MessageList,
    MessageInput,
} from "stream-chat-react";
import { useContext } from "react";
import { Loader2 } from "lucide-react";
import AuthContext from "./AuthContext";
import { useGetStreamClient } from "../hooks/useGetStreamClient";

export default function GroupChatPage() {
    //👇🏻 current user
    const { user, loading } = useContext(AuthContext);
    //👇🏻 stream client
    const { client } = useGetStreamClient(user!);
    //👇🏻 filters for fetching the messages
    const filters = { members: { $in: [user?.uid] }, type: "livestream" };
    const options = { presence: true, state: true };

    if (!client || loading) {
        return (
            <div>
                <Loader2 className='animate-spin h-6 w-6 text-gray-500' />
            </div>
        );
    }

    return {
        /***
        ---------------
        UI Components 
        --------------- 
        ***/
    };
}

The code snippet above demonstrates how to set up the necessary Stream Chat UI components to display group chat channels and messages.

The useGetStreamClient hook initializes the Stream Chat client for the authenticated user.
The filters object ensures only channels of type livestream where the current user is a member are retrieved.
The options enable real-time presence and state synchronization.

If the client is not yet ready or the authentication is still loading, a spinner is displayed.

Return the following Stream UI components from GroupChatPage:

return (
    <Chat client={client}>
        <div className='chat-container'>
            {/* -- Channel List -- */}
            <div className='channel-list'>
                <ChannelList
                    sort={{ last_message_at: -1 }}
                    filters={filters}
                    options={options}
                />
            </div>

            {/* -- Messages Panel -- */}
            <div className='chat-panel'>
                <Channel>
                    <Window>
                        <ChannelHeader />
                        <MessageList />
                        <MessageInput />
                    </Window>
                </Channel>
            </div>
        </div>
    </Chat>
);

From the code snippet above:

Chat component initializes the Stream Chat client and wraps the entire Chat page.
ChannelList shows available chat channels.
Channel sets up an active chat session.
Window contains the message display and input areas.
ChannelHeader, MessageList, and MessageInput provide a fully functional chat interface.

Do the same to the StreakPage component since they both render chat messages, but of different channel types (messaging):

"use client";
import { Chat, Channel, ChannelList } from "stream-chat-react";
import { useGetStreamClient } from "../hooks/useGetStreamClient";
import { Dispatch, SetStateAction, useContext } from "react";
import { ChannelContent } from "./ChannelContent";
import AuthContext from "./AuthContext";
import { Loader2 } from "lucide-react";

export default function StreakPage({
    setReminderMessage,
    setStreakReminder,
}: {
    setReminderMessage: Dispatch<SetStateAction<string>>;
    setStreakReminder: Dispatch<SetStateAction<boolean>>;
}) {
    const { user, loading } = useContext(AuthContext);
    const { client } = useGetStreamClient(user!);
    //👇🏻 filter = channel type - messaging
    const filters = { members: { $in: [user?.uid] }, type: "messaging" };
    const options = { presence: true, state: true };

    if (!client || loading || !user) {
        return (
            <div>
                <Loader2 className='animate-spin h-6 w-6 text-gray-500' />
            </div>
        );
    }

    return (
        <Chat client={client}>
            <div className='chat-container'>
                {/* -- Channel List -- */}
                <div className='channel-list'>
                    <ChannelList
                        sort={{ last_message_at: -1 }}
                        filters={filters}
                        options={options}
                    />
                </div>
                {/* -- Messages Panel -- */}
                <div className='chat-panel'>
                    <Channel>
                        {/** --- 👇🏻 Difference from GroupChatPage component 👇🏻 --- **/}
                        <ChannelContent
                            user={user}
                            setReminderMessage={setReminderMessage}
                            setStreakReminder={setStreakReminder}
                        />
                    </Channel>
                </div>
            </div>
        </Chat>
    );
}

From the code snippet above:

The StreakPage component tracks streaks based on the messages sent within the channel.
It accepts two state functions, setReminderMessage and setStreakReminder, which update the reminder message to be displayed to the user and control the visibility of the reminder pop-up.
The filters object retrieves channels where the current user is a member and the channel type is messaging (streak channels).
Inside the Stream Channel component, a custom ChannelContent component is rendered. This component receives the current user object along with the setReminderMessage and setStreakReminder functions. The next section will cover more details on this custom component.

Implement the Chat Streak Functionality With Stream Chat SDK

In this section, you will learn how to build a Snapchat-style chat streak feature that tracks daily conversations between users, updates their streak count, and sends reminders when a streak is at risk of ending.

To implement chat streaks, we will:

Fetch recent messages in the channel using useChannelStateContext.
Compare message dates to determine whether both users have sent messages to each other on the same day.
Notify the user if no messages have been exchanged today.
Update the streak count by one if both users have chatted today and the streak continued from the previous day.
Start a new streak if today is the first day of interaction.

This logic will run each time a new message is sent, ensuring the streak count and reminders are always up to date.

Add the following functions to the lib/server.ts file to handle chat streak updates.

import { MessageListProps } from "stream-chat-react";
import { parseISO, differenceInCalendarDays } from "date-fns";

//👇🏻 compares the message date with the current date
export const isSameUTCDate = (date: Date, today: Date) => {
    return (
        date.getUTCFullYear() === today.getUTCFullYear() &&
        date.getUTCMonth() === today.getUTCMonth() &&
        date.getUTCDate() === today.getUTCDate()
    );
};

//👇🏻 updates the chat streak
export async function updateChatStreak(
    channelId: string,
    today: Date
): Promise<void> {
    const todayString = today.toISOString().split("T")[0];
    const streakRef = doc(db, "channels", channelId);
    const streakSnap = await getDoc(streakRef);

    //👇🏻 gets the current streak and last streak date if available
    const { currentStreak = 0, lastStreakDate = null } = streakSnap.exists()
        ? streakSnap.data()
        : {};
    //👇🏻 declares a new streak number
    let newStreak: number;
    //👇🏻 if there is a last streak date value
    if (lastStreakDate) {
        //👇🏻 gets the days difference

        const dayDiff = differenceInCalendarDays(today, parseISO(lastStreakDate));

        if (dayDiff === 0) return; //👉🏻 Already counted today
        newStreak = dayDiff === 1 ? currentStreak + 1 : 1; //👉🏻 updates the streak or restarts
    } else {
        newStreak = 1; //👉🏻 First streak day
    }
    //👇🏻 updates the Firebase document
    await setDoc(streakRef, {
        currentStreak: newStreak,
        lastStreakDate: todayString,
        updatedAt: new Date().toISOString(),
    });
}

The isSameUTCDate function checks if two dates fall on the same day in UTC, while updateChatStreak accepts the channel ID and today’s date, retrieves the current streak data from Firebase, and:

Keeps the streak unchanged if today has already been counted
Increments the streak if the last streak was yesterday
Resets the streak to 1 if otherwise
Saves the updated streak and date back to Firebase

Next, implement the updateChatStreak logic inside the ChannelContent UI component.

Begin by adding these imports to the ChannelContent.tsx file:

"use client";
import { Dispatch, SetStateAction, useEffect, useMemo, useState } from "react";

//👇🏻 Firebase methods
import { doc, onSnapshot } from "firebase/firestore";
import { User } from "firebase/auth";
import db from "@/lib/firebase";

//👇🏻 custom functions
import { getUsernameById, isSameUTCDate, updateChatStreak } from "@/lib/server";
import { showToast } from "@/lib/utils";

//👇🏻 Stream chat UI components
import {
    ChannelHeader,
    MessageInput,
    MessageList,
    useChannelStateContext,
    Window,
} from "stream-chat-react";

Copy the following code snippet into the ChannelContent.tsx file:

export const ChannelContent = ({
    user,
    setReminderMessage,
    setStreakReminder,
}: {
    user: User;
    setReminderMessage: Dispatch<SetStateAction<string>>;
    setStreakReminder: Dispatch<SetStateAction<boolean>>;
}) => {
    const { messages, members, channel } = useChannelStateContext();
    const [currentStreak, setCurrentStreak] = useState<number>(0);
    //👇🏻 get membersID from the members array
    const membersID = useMemo(
        () => (members ? Object.keys(members) : []),
        [members]
    );
    //👇🏻 channel ID
    const channelID = channel?.id;

    /***
 ------
 👉🏻 useEffect functions for updating states 👈🏼
 ------
 ***/

    return (
        <Window>
            <ChannelHeader />
            <MessageList />
            <MessageInput />
        </Window>
    );
};

The component above defines the key states and variables used in ChannelContent. It retrieves the messages, members, and channel data from Stream’s useChannelStateContext hook.

The membersID variable stores an array of the members’ IDs, channelID stores the channel’s ID, and currentStreak tracks the user’s current streak count.

Add a useEffect hook to keep the user’s streak count in sync with Firestore.

useEffect(() => {
    if (!channelID) return;
    const streakRef = doc(db, "channels", channelID);
    const unsubscribe = onSnapshot(streakRef, (snapshot) => {
        if (snapshot.exists()) {
            const data = snapshot.data();
            setCurrentStreak(data.currentStreak ?? 0);
        } else {
            setCurrentStreak(0);
        }
    });

    return () => unsubscribe();
}, [channelID]);

It listens to changes on the current channel document in the channels collection and updates currentStreak whenever the value changes. If the document doesn’t exist, the streak count defaults to 0.

Finally, add the useEffect, which notifies users when they haven’t reached their daily chat goal. This useEffect checks whether both users in the streak group have sent messages to each other today. If they have, the updateChatStreak function is called. If not, the StreakReminderModal pop-up appears to remind them to chat.

useEffect(() => {
    if (!channelID || !membersID.length || !messages) return;
    //👇🏻 separates the members into two variables
    const [userA, userB] = membersID;

    //👇🏻 today's date
    const today = new Date();

    //👇🏻 check if both users have sent messages today
    const userAMessagesToday = messages.some(
        (msg) => msg.user?.id === userA && isSameUTCDate(msg.created_at, today)
    );
    const userBMessagesToday = messages.some(
        (msg) => msg.user?.id === userB && isSameUTCDate(msg.created_at, today)
    );

    //👇🏻 gets the members' name
    const memberAName = getUsernameById(members!, userA);
    const memberBName = getUsernameById(members!, userB);

    // declares the notification function
    const checkAndNotify = async () => {
        // ✅ Both sent messages → update streak
        if (userAMessagesToday && userBMessagesToday) {
            await updateChatStreak(channelID, today);
            if (currentStreak > 0) {
                showToast("success", `Streak Updated: ${currentStreak} day(s)! 🔥`);
            }
            return;
        }

        // 🚨 Streak Reminders
        let message: string | null = null;

        if (!userAMessagesToday && !userBMessagesToday) {
            message = `Streak Pending: Both ${memberAName} and ${memberBName} need to send messages today!`;
        } else if (user.uid === userA && !userAMessagesToday) {
            message = `Streak Pending: Send a message to ${memberBName}`;
        } else if (user.uid === userB && !userBMessagesToday) {
            message = `Streak Pending: Send a message to ${memberAName}`;
        } else if (user.uid === userA && !userBMessagesToday) {
            message = `Streak Pending: Waiting for ${memberBName}`;
        } else if (user.uid === userB && !userAMessagesToday) {
            message = `Streak Pending: Waiting for ${memberAName}`;
        }
        //👇🏻 displays the pop-up and sets its corresponding message
        if (message) {
            setStreakReminder(true);
            setReminderMessage(message);
        }
    };
    //👇🏻 executes the function

    checkAndNotify();
}, [
    //👇🏻 dependencies
    channelID,
    membersID,
    messages,
    user,
    currentStreak,
    members,
    setReminderMessage,
    setStreakReminder,
]);

How the useEffect works:

Identify participants and date: The two members in the streak group are split into separate variables, and today’s date is recorded.
Check daily activity: It verifies whether each member has sent a message to the channel today.
Update streak if complete: If both members have messaged today, it calls updateChatStreak to increment the streak.
Send reminders if pending: If one or both members haven’t sent a message, it determines the appropriate reminder text and triggers the StreakReminderModal pop-up to encourage them to chat and maintain the streak.

Congratulations! You have completed this tutorial. The source code is available on GitHub.

Next Steps

So far, you’ve learned how to integrate Stream into a Next.js application, use Firebase for authentication and database operations, create chat channels, build the chat UI, retrieve channel messages, and implement streak functionality using the Stream Chat SDK.

Whether you’re creating a simple communication tool or a fully featured collaborative platform, Stream gives you the building blocks to launch quickly and scale confidently and easily.

Try building these next:

Thank you for following along! 🎉

[Boost]

David Asaolu — Thu, 24 Jul 2025 16:27:19 +0000

David Asaolu for Stream

Jul 24 '25

Build a Gaming App with Next.js and Firebase

#react #javascript #programming #webdev

Comments 4

24 min read

Build a Gaming App with Next.js and Firebase

David Asaolu — Thu, 24 Jul 2025 14:28:42 +0000

Online multiplayer games bring people together to compete, collaborate, and connect in real-time. In this tutorial, you'll learn how to build a fully functional gaming application that supports two classic games: Tic Tac Toe and Rock Paper Scissors. The app will enable users to invite friends, track scores, and chat with each other.

We will use Firebase for user authentication and recording scores, and implement a real-time chat feature using the Stream Chat SDK.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We will use the following tools:

Firebase - a Backend-as-a-service platform developed by Google to enable us to add authentication, database, real-time communication, file storage, cloud functions, and many others within software applications.
Stream Chat Firebase Extension - a Firebase extension that automatically connects your Firebase users to Stream.
Stream React Chat - enables real-time chat communication in your application.
Shadcn UI - a UI component library that provides customizable, beautifully designed, and accessible UI components for your applications.

Create a Next.js project by running the following code snippet:

npx create-next-app gaming-app

Install the package dependencies for the project:

npm install firebase stream-chat stream-chat-react react-copy-to-clipboard

To install the Shadcn UI library, follow the installation guide.

Once everything is set up, your Next.js project is ready.

Now, let's start building! 🚀

Building the Application Interface with Next.js

In this section, you'll learn how to build the main pages and components of the application and see how they work together. The app includes six key pages:

Home Page: Introduces the application with a brief description and provides buttons that direct users to the login and sign-up pages.
Sign-Up Page: Renders a form where new users can enter their email, username, and password to create an account.
Login Page: Renders a form for existing users to sign in using their email and password. Once logged in, users are redirected to the Games Channel page.
Games Channel Page: Acts as the dashboard. It shows group chats for each game and includes a link to create a new game request.
Game Request Page: Allows users to create a new game session by selecting an opponent and the game type. Once submitted, a unique shareable game link is generated.
Game Page: This is where the actual gameplay happens. Players can play multiple rounds of Tic Tac Toe or Rock Paper Scissors.

Home Page

The home page renders a description text and two links that direct users to the login and registration pages.

Copy the following code into app/page.tsx to create the Home page:

export default function Home() {
    return (
        <div className='w-full h-screen'>
            <nav className='w-full px-8 py-4 flex items-center justify-between h-[10vh] border-b-[1px] border-gray-300'>
                <Link href='/' className='font-bold text-2xl'>
                    StreamGame
                </Link>

                <button className='bg-blue-500 text-white px-4 py-2 rounded-md cursor-pointer'>
                    Source Code
                </button>
            </nav>
            <section className='h-[90vh] text-center w-full py-8 lg:px-[50px] px-4 flex flex-col items-center justify-center'>
                <h1 className='text-5xl lg:text-7xl font-extrabold text-blue-500 mb-5'>
                    2-in-1 Gaming Platform
                </h1>
                <p className='opacity-50 text-lg lg:text-2xl '>
                    Play games, join tournaments, and network with other gamers.
                </p>
                <p className='opacity-50 text-lg lg:text-2xl '>
                    Win games and earn points on the leaderboard.
                </p>

                <div className='flex items-center justify-center mt-8'>
                    <Link
                        href='/login'
                        className='bg-blue-500 text-white px-6 py-3 rounded-md cursor-pointer'
                    >
                        Log in
                    </Link>
                    <Link
                        href='/register'
                        className='bg-gray-200 text-gray-800 px-6 py-3 rounded-md cursor-pointer ml-5'
                    >
                        Create Account
                    </Link>
                </div>
            </section>
        </div>
    );
}

Authentication Pages: Log In and Sign Up

Set up the authentication routes by creating an (auth) folder inside the app directory. This folder will contain two subfolders: login and register. Each subfolder represents a separate page for user authentication.

app
├── (auth)
│   ├── login
│   │   └── page.tsx
│   └── register
│       └── page.tsx

Add a page.tsx file to each subfolder. The page.tsx file renders the UI elements for the pages.

cd login && touch page.tsx && \
cd register && touch page.tsx

Copy the following code snippet into the login/page.tsx file:

"use client";
import { useState } from "react";
import Link from "next/link";

export default function Login() {
    const [buttonClicked, setButtonClicked] = useState<boolean>(false);

    const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        setButtonClicked(true);
        // 👉🏻 authenticate user
    };

    return (
        <section className='mx-auto md:w-3/4 w-full h-screen flex flex-col justify-center md:px-8 px-6 items-center'>
            <h2 className='text-3xl font-bold mb-3 md:text-left text-center'>
                Log in
            </h2>
            <form className='w-full' onSubmit={handleSubmit}>
                <label htmlFor='email' className='mb-2 opacity-60'>
                    Email Address
                </label>
                <input
                    required
                    type='email'
                    id='email'
                    name='email'
                    className='w-full px-4 py-3 border-[1px] rounded-md mb-3'
                />

                <label htmlFor='password' className='mb-2 opacity-60'>
                    Password
                </label>
                <input
                    required
                    type='password'
                    id='password'
                    name='password'
                    className='w-full px-4 py-3 border-[1px] rounded-md mb-2'
                />

                <button
                    type='submit'
                    className='mt-6 mb-2 text-lg text-white rounded-md bg-blue-500 w-full px-8 py-4 cursor-pointer hover:bg-blue-600'
                    disabled={buttonClicked}
                >
                    {buttonClicked ? "Signing in" : "Sign in"}
                </button>
                <p className=' opacity-60 text-center'>
                    Don&apos;t have an account?{" "}
                    <Link href='/register' className='text-blue-800'>
                        Create one
                    </Link>
                </p>
            </form>
        </section>
    );
}

The code snippet above renders a form that collects the user's email and password. Once submitted, the credentials are authenticated before granting the user access to the application.

Finally, update the register/page.tsx file as shown below:

"use client";
import { useState } from "react";
import Link from "next/link";

export default function Register() {
    const [buttonClicked, setButtonClicked] = useState<boolean>(false);

    const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        setButtonClicked(true);
        // 👉🏻 create user
    };

    return (
        <section className='mx-auto md:w-3/4 h-screen w-full flex flex-col items-center justify-center md:px-8 px-6 py-8 '>
            <h2 className='text-3xl font-bold mb-3 text-center'>Register</h2>
            <form className='w-full' onSubmit={handleSubmit}>
                <label htmlFor='nickname' className='mb-2 opacity-60  '>
                    Nickname
                </label>
                <input
                    required
                    type='text'
                    id='nickname'
                    name='nickname'
                    className='w-full px-4 py-3 border-[1px] rounded-md mb-3'
                    placeholder='yournickname'
                />
                <label htmlFor='email' className='mb-2 opacity-60  '>
                    Email Address
                </label>
                <input
                    required
                    type='email'
                    id='email'
                    name='email'
                    className='  w-full px-4 py-3 border-[1px] rounded-md mb-3'
                    placeholder='cde@ab.com'
                />

                <label htmlFor='password' className='mb-2 opacity-60  '>
                    Password
                </label>
                <input
                    required
                    type='password'
                    id='password'
                    name='password'
                    minLength={8}
                    className='w-full px-4 py-3 border-[1px] rounded-md mb-2  '
                />

                <button
                    className='mt-2 mb-2 text-lg text-white rounded-md bg-blue-500 w-full px-8 py-4 cursor-pointer hover:bg-blue-600'
                    disabled={buttonClicked}
                >
                    {buttonClicked ? "Registering..." : "Register"}
                </button>
                <p className=' opacity-60 text-center'>
                    Already have an account?{" "}
                    <Link href='/login' className='text-blue-800'>
                        Sign in
                    </Link>
                </p>
            </form>
        </section>
    );
}

The code snippet above renders a form that collects the user's nickname, email, and password. These details are used to create an account and are validated before the user can sign in and access the application as a player.

The Games Channel Page

The Games Channel Page displays the group chat interface, an icon that opens the game leaderboard, and a button that directs users to the Game Request page.

Within the Next.js app directory, create a games folder. Inside the games folder, add two subfolders:

[id]: This will handle dynamic game sessions (e.g., /games/abc123).
requests: This will serve the Game Request page, where users can initiate new games.

app
├── games
│   ├── page.tsx         // Games Channel Page
│   ├── [id]
│   │   └── page.tsx     // Dynamic Game Page
│   └── requests
│       └── page.tsx     // Game Request Page

Copy the following code snippet into the games/page.tsx file:

"use client";
import { useCallback, useContext, useEffect, useState } from "react";
import { getLeaderboard, logoutUser } from "@/lib/serverfunctions";
import { Dialog, DialogTrigger } from "@/components/ui/dialog";
import ChatComponent from "../(components)/ChatComponent";
import LeaderBoard from "../(components)/Leaderboard";
import AuthContext from "../(context)/AuthContext";
import { Trophy } from "lucide-react";
import Link from "next/link";

interface Leaderboard {
    id: string;
    nickname: string;
    email: string;
    score: number;
}

export default function GamesPage() {
    const [leaderboard, setLeaderboard] = useState<Leaderboard[]>([]);
    const { user } = useContext(AuthContext);

    return (
        <div>
            <Navigation leaderboard={leaderboard} />

            <section className='px-4 py-4 border-[4px] rounded-lg border-gray-200'>
                <ChatComponent user={user!} />
            </section>
        </div>
    );
}

The GamesPage component renders two main parts: the Navigation bar and the ChatComponent.

The Navigation serves as the page’s navigation bar, while the ChatComponent includes the group chat components, which you will learn to implement later in this tutorial.

Add the following code snippet below the GamesPage component:

const Navigation = ({ leaderboard }: { leaderboard: Leaderboard[] }) => {
    return (
        <nav className='w-full md:px-8 px-2 py-4 flex items-center justify-between h-[10vh] border-b-[1px] border-gray-300'>
            <Link href='/' className='font-bold text-2xl'>
                StreamGame
            </Link>

            <div className='flex items-center gap-2'>
                <Dialog>
                    <DialogTrigger asChild>
                        <Trophy className='bg-white text-sm text-green-600 hover:underline rounded-md cursor-pointer hover:text-blue-500' />
                    </DialogTrigger>
                    <LeaderBoard leaderboard={leaderboard.slice(0, 7)} />
                </Dialog>

                <Link
                    href='/games/request'
                    className='bg-blue-500 text-sm text-white px-4 py-2 rounded-md cursor-pointer'
                >
                    Game Requests
                </Link>

                <button
                    className='bg-red-600 text-sm hover:bg-red-500 text-white px-4 py-2 rounded-md cursor-pointer'
                    onClick={logoutUser}
                >
                    Log Out
                </button>
            </div>
        </nav>
    );
};

The Navigation component renders an icon button that displays the leaderboard modal, the Games request page link, and the logout button.

Games Request Page

Copy the following code snippet into the file requests/pages.tsx file:

"use client";
import { useRouter } from "next/navigation";

export default function CreateGame() {
    const [copied, setCopied] = useState<boolean>(false);
    const [selectedGame, setSelectedGame] = useState<string>("");
    const [gameId, setGameId] = useState<string>(generateGameUrl());
    const [buttonClicked, setButtonClicked] = useState<boolean>(false);
    const [selectedPlayer, setSelectedPlayer] = useState<string>("");
    const [error, setError] = useState<boolean>(true);
    const router = useRouter();
    const handleCopy = () => setCopied(true);

    const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        setButtonClicked(true);
        // 👉🏻 create game request
    };

    return (
        <>
            <main>
                <h3>Create Game</h3>
                <p>Create a game request and play with your friends.</p>

                <form onSubmit={handleSubmit}>
                    <label htmlFor='player'>Opponent Email</label>
                    <input
                        type='email'
                        placeholder='Enter player email'
                        value={selectedPlayer}
                        onChange={(e) => {
                            setSelectedPlayer(e.target.value);
                            setError(!error);
                        }}
                        required
                        name='player'
                        id='player'
                    />
                    {!error ? (
                        <p>
                            Player found:{" "}
                            {users.find((user) => user.email === selectedPlayer)?.nickname}
                        </p>
                    ) : (
                        <p>Player not found. Please enter a valid email.</p>
                    )}

                    <select
                        name='game'
                        id='game'
                        required
                        value={selectedGame}
                        onChange={(e) => setSelectedGame(e.target.value)}
                    >
                        <option value=''>Select a game</option>
                        {games.map((game) => (
                            <option key={game.id} value={game.id}>
                                {game.name}
                            </option>
                        ))}
                    </select>

                    {selectedGame && (
                        <>
                            <CopyToClipboard
                                onCopy={handleCopy}
                                text={`${process.env.NEXT_PUBLIC_URL}/games/${gameId}`}
                            >
                                <div>
                                    <p>{`${process.env.NEXT_PUBLIC_URL}/games/${gameId}`}</p>

                                    <p>{copied ? "Copied!" : <Copy />}</p>
                                </div>
                            </CopyToClipboard>
                            <p>Ensure you copy the link before starting the game.</p>
                        </>
                    )}

                    <button type='submit' disabled={!copied || buttonClicked || error}>
                        {buttonClicked ? "Creating..." : "Create Game"}
                    </button>
                </form>
            </main>
        </>
    );
}

The form allows game hosts to enter their opponent’s email and select the type of game. It then automatically generates a game link to be shared to start playing.

Setting Up Stream Chat SDK for Group Messaging in Next.js

In this section, you will learn how to create group chat channels within the application using the Stream Chat SDK.

First, create a Stream account and a new organization to manage your apps.

Add a new app to the organization and copy the Stream API and Secret key into the .env.local file.

NEXT_PUBLIC_STREAM_API_KEY=<paste_from_Stream_app_dashboard>
STREAM_SECRET_KEY=<paste_from_Stream_app_dashboard>

Before we proceed, here is a brief overview of how we will configure the application:

When users sign in, they are automatically added to two existing game channels, Tic Tac Toe and Rock Paper Scissors, where they can interact with other players. To enable this, you need to create these channels and implement a function that adds new users to the channels upon sign-in.

Select Explorer from the Chat Messaging dropdown to create the new channels.

Create an actions folder containing a stream.action.ts within your Next.js project.

cd gaming-app && mkdir actions && \
cd actions && touch stream.action.ts

Copy the following code snippet into the stream.action.ts file:

"use server";
import { StreamChat } from "stream-chat";

const STREAM_API_KEY = process.env.NEXT_PUBLIC_STREAM_API_KEY!;
const STREAM_API_SECRET = process.env.STREAM_SECRET_KEY!;
const CREATOR_ID = process.env.CHANNELS_CREATOR_ID!;

// 👇🏻 -- For Stream Chat  --
const serverClient = StreamChat.getInstance(STREAM_API_KEY, STREAM_API_SECRET);

You can find your creator ID under the Users menu in the Stream app Explorer dashboard.

Modify the stream.action.ts file by adding the following functions to the file:

//👇🏻 creates a token for each user
export async function createToken(user: Leaderboard): Promise<string> {
    if (!user) throw new Error("User is not authenticated");
    return serverClient.createToken(user.id);
}

//👇🏻 retrieves the existing chat channels
export const getGameChannels = async (userId: string) => {
    try {
        const filter = { created_by_id: CREATOR_ID, type: "messaging" };
        const sort = [{ last_message_at: -1 }];

        const channels = await serverClient.queryChannels(filter, sort);
        const channelIds = channels.map((channel) => channel.id);

        if (!channelIds || channelIds.length === 0) {
            return {
                success: false,
                message: "No channels found",
                error: null,
 };
 }
        const result = await addUserToChannels(channelIds as string[], userId);
        return result;
 } catch (error) {
        console.error("Error fetching channels:", error);
        throw new Error("Failed to fetch channels");
 }
};

The createToken function generates a token for each user based on their ID. The getGameChannels function runs when the user signs into the application.

The getGameChannels function takes the user ID as a parameter, retrieves all existing channels created by you (the app creator), and then calls addUserToChannels to add the current user to those channels.

Finally, add the addUserToChannels function to the stream.action.ts file:

//👇🏻 gets the channels and add the user to each one of them
export async function addUserToChannels(channelIds: string[], userId: string) {
    try {
        // Step 1: Query all channels by IDs
        const filter = {
            id: { $in: channelIds },
            type: "messaging",
 };
        const sort = { last_message_at: -1 };
        const channels = await serverClient.queryChannels(filter, sort);

        // Step 2: Determine which channels the user is already a member of
        const alreadyMemberChannelIds = channels
 .filter((channel) => channel.state.members[userId])
 .map((channel) => channel.id);

        // Step 3: Identify channels where the user is not a member
        const channelsToAdd = channelIds.filter(
 (id) => !alreadyMemberChannelIds.includes(id)
 );
        console.log({ alreadyMemberChannelIds, channelsToAdd, userId });

        // Step 4: Add the user to the channels they're not a member of
        for (const channelId of channelsToAdd) {
            const channel = serverClient.channel("messaging", channelId);
            await channel.addMembers([userId]);
 }
        return {
            success: true,
            message: "User added to channels successfully",
            addedChannels: channelsToAdd,
            alreadyMemberChannels: alreadyMemberChannelIds,
            error: null,
 };
 } catch (error) {
        console.error("Error adding user to channels:", error);
        return {
            success: false,
            error: "Failed to add user to channels",
            addedChannels: [],
            alreadyMemberChannels: [],
            message: null,
 };
 }
}

The function first checks whether the user is already a member of the existing channels; if not, it adds the user to those channels.

How to Integrate Firebase Authentication and Firestore in Next.js

Firebase is a cloud platform that helps you build full-stack applications without managing servers or databases. It offers powerful features such as authentication, real-time database, cloud functions, file storage, and more.

In this section, you will learn how to set up Firebase Authentication and Firestore Database to enable you to authenticate users and interact with the database.

Install the Firebase Node.js package by running the code snippet below:

npm install firebase

Open the Firebase Console in your browser and create a new Firebase project.

Within the project dashboard, click the web icon </> to add a Firebase app to the project.

Next, create a lib/firebase.ts file within the Next.js src folder and paste the following code snippet into the file:

import { initializeApp, getApps } from "firebase/app";
import { getFirestore } from "firebase/firestore";
import { EmailAuthProvider } from "firebase/auth";
import { getAuth } from "firebase/auth";

// Your web app's Firebase configuration
const firebaseConfig = {
    // -- 👉🏻 your auto-generated config code 👈🏼 --
};

// Initialize Firebase
const app =
    getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];
const provider = new EmailAuthProvider();
const db = getFirestore(app);
const auth = getAuth(app);

export { provider, auth };
export default db;

The code snippet above initializes the Firestore database and the email authentication provider. This setup allows you to interact with a database and implement email/password authentication within the application.

Before interacting with Firebase features, you must set them up in your project dashboard.

Click Build in your dashboard's sidebar navigation. This will open a dropdown menu with various features you can enable for your project.

Select Authentication and Firestore Database from the drop-down and add them to the project.

Congratulations! You can now start interacting with these Firebase features in your Next.js project.

Stream Firebase Chat SDK Extension

The Authenticate with Stream Chat extension automatically connects your Firebase users to Stream Chat, making it easy for Stream to access and manage your users.

Visit the Stream Chat Firebase Extension page and select the Firebase project where you want to install the extension.

Note: Upgrade your Firebase project to the Blaze (pay-as-you-go) plan before installing the extension.

During installation, enable Artifact Registry, Cloud Functions, and Secret Manager. These permissions allow Stream to access and manage your Firebase users.

Finally, enter your Stream API key and secret in the configuration fields, then click the Install Extension button.

The extension will be installed within a few minutes. Once setup is complete, every new Firebase user will automatically be added to Stream.

Authenticating Users with Firebase

Here you will learn how to create functions that enable users to sign up, sign in, and log out of the application.

First, create a serverfunctions.ts file within the lib folder that contains all the Firebase authentication and database functions.

cd lib && touch serverfunctions.ts

To enable users to create an account, copy the following code snippet into the serverfunctions.ts file:

import { createUserWithEmailAndPassword } from "firebase/auth";
import { auth } from "./firebase";

export const registerUser = async (form: FormData) => {
    //👇🏻 form inputs
    const email = form.get("email") as string;
    const password = form.get("password") as string;
    const nickname = form.get("nickname") as string;

    try {
        const { user } = await createUserWithEmailAndPassword(
            auth,
            email,
            password
 );
        if (!user) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "Failed to create user",
 };
 }
        //👇🏻 save to leaderboard collection
        const docRef = doc(db, "leaderboard", user.uid);
        //👇🏻 add document to collection
        await setDoc(docRef, {
            email,
            nickname,
            score: 0,
 });

        return {
            code: "auth/success",
            status: 200,
            user,
            message: "Account created successfully! 🎉",
            streamUser,
 };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to create user",
            error: err,
 };
 }
};

The registerUser function accepts the form inputs, creates a new user in Firebase Authentication using the provided credentials, and stores the user's email, nickname, and an initial score of 0 in the Firestore leaderboard collection. This collection helps track player scores and enables real-time updates when players win games and earn points.

Execute the function below to log users into the application.

import { signInWithEmailAndPassword } from "firebase/auth";
import { auth } from "./firebase";

export const loginUser = async (form: FormData) => {
    const email = form.get("email") as string;
    const password = form.get("password") as string;
    try {
        const { user } = await signInWithEmailAndPassword(auth, email, password);
        if (!user) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "Failed to login user",
 };
 }
        //👇🏻 add users to existing channels
        await getGameChannels(user.uid);

        return {
            code: "auth/success",
            status: 200,
            user,
            message: "Logged in successfully! 🎉",
 };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to login user",
            error: err,
 };
 }
};

The loginUser function takes the user's email and password, authenticates them using Firebase, and then calls the getGameChannels function. This ensures the user is added to the existing game channels (such as Tic Tac Toe and Rock Paper Scissors) before granting access to the main application pages.

Users can log out of the application using the function below:

import { auth } from "./firebase";

export const logoutUser = async () => {
    try {
        await auth.signOut();
        return {
            code: "auth/success",
            status: 200,
            user: null,
            message: "Logged out successfully! 🎉",
 };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to logout user",
            error: err,
 };
 }
};

The logoutUser function signs the user out of the application and redirects them to the home page.

You must protect those pages to ensure that only authenticated users can access specific application parts. This is done by creating an authentication context that wraps around your application and checks if a user is logged in before granting access to protected data or routes.

To get started, create an AuthContext.tsx file and add the following imports at the top of the file:

"use client";
import { createContext, useState, useEffect, useCallback } from "react";
import { onAuthStateChanged, User } from "firebase/auth";
import type { Leaderboard } from "../../../types";
import { doc, getDoc } from "firebase/firestore";
import { useRouter } from "next/navigation";
import db, { auth } from "@/lib/firebase";
import { Loader2 } from "lucide-react";

//👇🏻 the auth context
const AuthContext = createContext<{
    user: Leaderboard | null;
    loading: boolean;
}>({
    user: null,
    loading: true,
});

Add the following code snippet to the file.

export function AuthProvider({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    //👇🏻 Auth states
    const [user, setUser] = useState<User | null>(null);
    const [loading, setLoading] = useState(true);
    const [userData, setUserData] = useState<Leaderboard | null>(null);
    const router = useRouter();

    //👇🏻 getting the current user
    useEffect(() => {
        const unsubscribe = onAuthStateChanged(auth, async (user) => {
            if (user?.uid) {
                setUser(user);
                setLoading(false);
            } else {
                return router.push("/login");
            }
        });

        return () => unsubscribe();
    }, [router]);

    //👇🏻 getting the user leaderboard data
    const getUser = useCallback(async () => {
        if (!user) return null;
        const docSnap = await getDoc(doc(db, "leaderboard", user.uid));
        if (docSnap.exists()) {
            setUserData({ id: user.uid, ...docSnap.data() } as Leaderboard);
        } else {
            return null;
        }
    }, [user]);

    useEffect(() => {
        getUser();
    }, [getUser]);

    return (
        <>
            {userData ? (
                <AuthContext.Provider value={{ loading, user: userData }}>
                    {children}
                </AuthContext.Provider>
            ) : (
                <main className='flex items-center justify-center h-screen'>
                    <Loader2 className='animate-spin text-4xl font-bold text-blue-500 text-center' />
                </main>
            )}
        </>
    );
}

export default AuthContext;

The AuthProvider component retrieves the currently signed-in user and the leaderboard data from the Firestore collection. It then makes this data available to your application through the context provider. Wrap the AuthProvider around any page that requires restricted access.

Creating and Updating the Games Collection

Before we dive into real-time gameplay and tracking players' moves, let's first set up the Firebase games collection. This collection will store players' scores and enable us to update the leaderboard based on game results.

Use the function below to retrieve the top ten players based on their total score across all games:

export const getLeaderboard = async () => {
    try {
        const leaderboardRef = collection(db, "leaderboard");
        const q = query(leaderboardRef, orderBy("score", "desc"), limit(10));
        const querySnapshot = await getDocs(q);

        const allLeaders = querySnapshot.docs.map((doc) => ({
            id: doc.id,
 ...doc.data(),
 }));

        return allLeaders;
 } catch (error) {
        console.error("Error fetching leaderboard:", error);
        return [];
 }
};

The getLeaderboard function returns all the top ten players using the Firestore query methods.

Players can create game sessions when they navigate to the /games/request page. After submitting the form containing their opponent and the game type, execute the following function.

export const createGame = async (game: Game) => {
    const { id, type, players } = game;

    try {
        const docRef = doc(db, "games", id);
        await setDoc(docRef, {
            id,
            type,
            players,
 });
        return {
            code: "game/success",
            status: 200,
            game: { id, type, players },
            message: "Game created successfully! 🎉",
 };
 } catch (error) {
        return {
            code: "game/failed",
            status: 500,
            game: null,
            message: "Failed to create game",
            error,
 };
 }
};

The createGame function accepts the selected opponent, game type, and an auto-generated game ID and adds these parameters to the games collection in Firestore.

When players visit a specific game session page, you can retrieve the game data by its ID using the function below:

export const getGameById = async (id: string) => {
    try {
        const docSnap = await getDoc(doc(db, "games", id));

        if (docSnap.exists()) {
            return {
                code: "game/success",
                status: 200,
                game: docSnap.data(),
                message: "Game fetched successfully! 🎉",
 };
 } else {
            return {
                code: "game/failed",
                status: 404,
                game: null,
                message: "Game not found",
 };
 }
 } catch (error) {
        return {
            code: "game/failed",
            status: 500,
            game: null,
            message: "Failed to fetch game",
            error,
 };
 }
};

The getGameById function retrieves game data based on the provided ID. If a game with the specified ID exists, the function returns its full details. Otherwise, it returns an error object to the client.

After each game is completed, you’ll need to update the game’s score and reflect the results on the leaderboard. You can achieve this using the function below:

export const updatePlayerScore = async (userId: string, gameId: string) => {
    // Step 1: Get the current leaderboard score
    // Step 2: Read game doc to update the score in the players array
    // Step 3: Update the player's score
};

Modify the updatePlayerScore to get and update the current leaderboard score.

export const updatePlayerScore = async (userId: string, gameId: string) => {
    try {
        //👇🏻 get the current user data
        const userDocRef = doc(db, "leaderboard", userId);
        //👇🏻 get the game data
        const gameDocRef = doc(db, "games", gameId);

        // get the current and add 1 to its value
        const userSnap = await getDoc(userDocRef);
        if (!userSnap.exists()) {
            throw new Error("User not found");
 }
        const userData = userSnap.data();
        const currentScore =
            typeof userData.score === "number" ? userData.score : 0;

        const leaderboardUpdate = updateDoc(userDocRef, {
            score: currentScore + 1,
 });

        // Step 2: Read game doc to update the score in the players array
        // Step 3: Update the player's score
 } catch (error) {
        console.error("Error updating player score:", error);
        return {
            code: "user/failed",
            status: 500,
            message: "Failed to update user score",
            error,
 };
 }
};

Finally, add the following code snippet within the placeholder for step 2 and 3.

// Step 2: Read game doc to update the score in the players array
const gameSnap = await getDoc(gameDocRef);
if (!gameSnap.exists()) {
    throw new Error("Game not found");
}

const gameData = gameSnap.data();
if (!Array.isArray(gameData.players)) {
    throw new Error("Players field is invalid");
}

// Step 3: Efficiently update the matching player's score
const updatedPlayers = gameData.players.map((player: any) => {
    if (player.id === userId) {
        return {
 ...player,
            score: (player.score ?? 0) + 1,
 };
 }
    return player;
});

const gameUpdate = updateDoc(gameDocRef, {
    players: updatedPlayers,
});

await Promise.all([leaderboardUpdate, gameUpdate]);

return {
    code: "user/success",
    status: 200,
    message: "User score updated successfully! 🎉",
};

The code snippet above retrieves the user's current score and updates it to reflect the latest result. It ensures that both the game's score and the leaderboard are updated accordingly.

How to Implement Group Chat Messaging with Stream Chat

In this section, you'll learn how to create a group chat interface using Stream components and send and listen to events using the Stream Chat SDK.

First, create a hooks folder containing a useGetStreamClient.ts file, then copy the following code snippet into the file:

import { createToken } from "../../../actions/stream.action";
import { useCreateChatClient } from "stream-chat-react";
import type { Leaderboard } from "../../../types";
import { useCallback } from "react";

export const useGetStreamClient = (user: Leaderboard) => {
    const tokenProvider = useCallback(async () => {
        return await createToken(user);
 }, [user]);

    const client = useCreateChatClient({
        apiKey: process.env.NEXT_PUBLIC_STREAM_API_KEY!,
        tokenOrProvider: tokenProvider,
        userData: {
            id: user.id,
            name: user.nickname,
            image: `https://api.dicebear.com/9.x/pixel-art/svg?seed=${user.nickname}`,
 },
 });

    if (!client) return { client: null };

    return { client };
};

The useGetStreamClient hook creates a Stream client using the Stream API key, the current user’s ID and name, and an auto-generated user image. This Stream client uniquely identifies each user and allows us to perform various chat operations.

Next, update the ChatComponent inside the games/page.tsx file by copying the following code snippet:

"use client";
import {
    Channel,
    ChannelList,
    Window,
    ChannelHeader,
    MessageList,
    MessageInput,
} from "stream-chat-react";
import { Loader2 } from "lucide-react";
import { Chat } from "stream-chat-react";
import type { Leaderboard } from "../../../types";
import { useGetStreamClient } from "../hooks/useGetStreamClient";

export default function ChatComponent({ user }: { user: Leaderboard }) {
    //👇🏻 get the Stream client
    const { client } = useGetStreamClient(user!);
    const filters = {
        type: "messaging",
        id: { $in: ["tic-tac-toe", "rock-paper-scissors"] },
        members: { $in: [user.id] },
    };

    const options = { presence: true, state: true };

    if (!client)
        return (
            <div className='flex items-center justify-center h-screen'>
                <Loader2 className='animate-spin text-blue-500' />
            </div>
        );

    return (
        <Chat client={client}>
            <div className='chat-container'>
                {/* -- Channel List -- */}
                <div className='channel-list'>
                    <ChannelList
                        sort={{ last_message_at: -1 }}
                        filters={filters}
                        options={options}
                    />
                </div>

                {/* -- Messages Panel -- */}
                <div className='chat-panel'>
                    <Channel>
                        <Window>
                            <ChannelHeader />
                            <MessageList />
                            <MessageInput />
                        </Window>
                    </Channel>
                </div>
            </div>
        </Chat>
    );
}

From the code snippet above:
- The useGetStreamClient custom hook returns the Stream Chat client for the current user.
- Chat component initializes the Stream Chat client and wraps the entire Chat page.
- ChannelList shows available chat channels.
- Channel sets up an active chat session.
- The Window component contains the message display and input areas.
- ChannelHeader, MessageList, and MessageInput provide a fully functional chat interface.

Sending and Receiving Real-Time Events with Stream

Stream allows you to send and listen to events within a channel. In this section, you will learn how to handle custom events using the Stream Chat SDK.

When a user creates a game using the createGame function, run the following code snippet to create a Stream channel for that game session.

const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    //👉🏻 execute createGame function
    const newChannel: ChannelType = await client.channel("messaging", gameId, {
        members: [user.id, selectedPlayerObject.id],
 });
    await newChannel.watch();
    setChannel(newChannel);
    router.push(`/games/${newChannel.id}`);
};

Every game session is a Stream channel that allows us to track the members' activities and create custom events for that channel.

The handleSubmit function adds the game details to Firebase, creates a new game channel using the generated ID, and adds both the host's ID and the opponent's ID as members to the channels.

Next, add the following imports to the [id]/page.tsx file:

"use client";
//👇🏻 React imports
import { useContext, useEffect, useCallback, useState, useMemo } from "react";
import { useGetStreamClient } from "@/app/hooks/useGetStreamClient";
import { useParams, useRouter } from "next/navigation";

//👇🏻 Stream chat imports
import type { Channel as ChannelType } from "stream-chat";
import { Chat, Channel } from "stream-chat-react";

//👇🏻 Firebase imports
import { doc, onSnapshot } from "firebase/firestore";
import { getGameById } from "@/lib/serverfunctions";
import db from "@/lib/firebase";

//👇🏻 React components import
import WinnerModal from "@/app/(components)/WinnerModal";
import AuthContext from "@/app/(context)/AuthContext";
import RockPaper from "@/app/(components)/RockPaper";
import TicTacToe from "@/app/(components)/TicTacToe";
import GamesNav from "@/app/(components)/GamesNav";
import { Loader2 } from "lucide-react";

Modify the [id]/page.tsx file as shown below:

export default function GamePlay() {
    const [channel, setChannel] = useState<ChannelType | null>(null);
    const [game, setGame] = useState<Game | null>(null);
    const router = useRouter();
    //👇🏻 game ID from page URL
    const { id } = useParams<{ id: string }>();
    //👇🏻 current user
    const { user } = useContext(AuthContext);
    //👇🏻 Stream client
    const { client } = useGetStreamClient(user!);

    const getChannel = useCallback(async () => {
        if (!client || !id) return;
        const [channel, { game }] = await Promise.all([
            client.queryChannels({
                id: id,
 }),
            getGameById(id),
 ]);
        if (!channel || !game || !user) return router.back();
        //👇🏻 if user is not a member of the channel
        if (!channel[0].state.members[user.id as string]) {
            return router.back();
 }
        setGame(game as Game);
        setChannel(channel[0]);
 }, [client, setChannel, id, router, user]);

    useEffect(() => {
        getChannel();
 }, [getChannel]);

    return {
        /** -- UI components -- */
 };
}

From the code snippet above:
- The useParams function retrieves the game ID from the page URL.
- The getChannel function fetches the Stream channel data using the game ID, which doubles as the channel ID, and also retrieves the corresponding game data by its ID.
- The function checks that the user is a channel member before granting access to the game page. This ensures that only the game host and their opponent can access the game session.

Update the GamePlay component to listen for real-time updates on the game document. This way, whenever something changes, like when a player wins, the latest scores and game status are shown immediately on the screen for everyone.

useEffect(() => {
    const unsubscribe = onSnapshot(doc(db, "games", id), (docSnap) => {
        if (docSnap.exists()) {
            setGame({ id: docSnap.id, ...docSnap.data() } as Game);
 }
 });

    return () => unsubscribe();
}, [id]);

//👇🏻 none exists - show a loader
if (!client || !user || !channel) {
    return (
 <div className='flex items-center justify-center h-screen'>
 <Loader2 className='animate-spin text-blue-500' />
 </div>
 );
}

Return the page component wrapped with the Stream Chat and Channel components.

return (
 <Chat client={client}>
 <Channel channel={channel}>
 <Page channel={channel} game={game} />
 </Channel>
 </Chat>
);

The Stream Channel component must be nested inside the Stream Chat component. The Channel component lets us send and listen to events within the channel, enabling real-time tracking of each player's moves. It also supports custom events that help determine the winner and track the player's online status.

You can monitor the channel's watcher count to see how many users are currently in it. When both the host and opponent are active and ready, the playersCompleted state is set to true, indicating the game can start.

const [playersCompleted, setPlayersCompleted] = useState<boolean>(() =>
    Boolean(channel.state.watcher_count === 2)
);

useEffect(() => {
    if (!channel) return;
    //👇🏻 updates the state
    const handleWatchChange = (event: { watcher_count: number }) => {
        setPlayersCompleted(event.watcher_count === 2);
 };

    // Listen for changes in the users' online activity
    channel.on("user.watching.start", handleWatchChange);
    channel.on("user.watching.stop", handleWatchChange);

    // Cleanup on channel change or unmount
    return () => {
        channel.off("user.watching.start", handleWatchChange);
        channel.off("user.watching.stop", handleWatchChange);
 };
}, [channel]);

The useEffect hook subscribes to the players’ online status and updates the playersCompleted state whenever there’s a change. If both players are active, playersCompleted is set to true; otherwise, it’s set to false. You can use this state to show a loader while waiting for a player.

Additionally, you can create and listen for custom events to handle game actions like player moves and declaring a winner. For example, when a player makes a move in Tic Tac Toe, you must notify the opponent about the move and its position. You can do this using the following function:

channel.sendEvent({
    type: "custom-event-name",
    data: {
        /* -- values to be sent to the opponent*/
 },
});

//👇🏻 TicTacToe Game
await channel.sendEvent({
    type: "game-move",
    data: { index, sign: currentPlayer.sign },
});

You can listen to events using the useEffect function as shown below:

useEffect(() => {
    if (!channel) return;
    const handleMoveEvent = (event: any) => {
        const { index, sign } = event.data;
        setCells((prev) => {
            const updated = [...prev];
            updated[index] = sign;
            return updated;
 });
        // Update turn based on sign
        setXIsNext(sign === "O");
 };

    // Listen for custom 'game-move' events
    channel.on("game-move", handleMoveEvent);

    // Cleanup listener on unmount
    return () => {
        channel.off("game-move", handleMoveEvent);
 };
}, [channel]);

The handleMoveEvent function receives the player’s sign and the index of the selected cell, then updates the board to reflect the move on the opponent’s screen. You can see how to implement this in the Tic Tac Toe and Rock Paper Scissors game components.

Check out the video walkthrough on YouTube:

You can also try out the live version of the app.

If you're interested in the source code, it is available on GitHub.

Next Steps

So far, you’ve learned how to build a gaming application that integrates group chat channels using the Stream Chat SDK and Firebase. This app enables gamers to connect through chat and compete to become the top players on the leaderboard.

Stream also offers various other powerful features to help you build engaging, scalable applications. These include performant and flexible Chat, Video, Audio, Feeds, and Moderation APIs and SDKs.

What's next? Keep building with these recommended tutorials:

Thank you for reading. 🎉

Build a Therapy Marketplace Using Next.js and Firebase

David Asaolu — Fri, 16 May 2025 11:12:45 +0000

TL;DR

In this tutorial, you will learn how to build a therapy marketplace app using Next.js, Stream, and Firebase. The app will allow clients to find therapists, chat, and book virtual therapy sessions.

Firebase will handle the backend operation, while Stream will handle in-app chat and video calls.

App Overview

The application supports two types of users: therapists and clients.

Therapists can:

🥼 Create an account based on their area of specialization and set an hourly rate.
🥼 Manage and confirm booking payments.
🥼 Initiate chats with clients and schedule virtual video sessions.
🥼 Receive reviews from clients after each session.

Clients can:

👉🏻 Browse and book therapists based on their specialization and specific needs.
👉🏻 Chat with therapists once a booking is confirmed.
👉🏻 Attend 1-on-1 virtual sessions with therapists.
👉🏻 Leave reviews on therapists’ profiles.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We will use the following tools:

Firebase - a Backend-as-a-service platform developed by Google to enable us to add authentication, database, real-time communication, file storage, cloud functions, and many others within software applications.
Stream Chat Firebase Extension - a Firebase extension that automatically connects your Firebase users to Stream.
Stream React Chat and React Video SDK - enables real-time chat and video/audio communication in your application.
Shadcn UI: a UI component library that provides customizable, beautifully designed, and accessible UI components for your applications.

Create a Next.js project by running the following code snippet:

npx create-next-app therapy-app

Install the package dependencies for the project:

npm install firebase @stream-io/node-sdk @stream-io/video-react-sdk stream-chat stream-chat-react

To install the Shadcn UI library, follow the installation guide.

Once everything is set up, your Next.js project is ready.

Now, let's start building! 🚀

How to Set Up Firebase for Auth and DB Interactions

In this section, you'll learn how to install Firebase in a Next.js application and configure the Firestore Database, Firebase storage, and authentication within your Next.js application.

Setting up Firebase in a Next.js Application

Install the Firebase Node.js package by running the code snippet below:

npm install firebase

Open the Firebase Console in your browser and create a new Firebase project.

Within the project dashboard, click the web icon </> to add a Firebase app to the project.

Create a lib/firebase.ts file within the Next.js src folder and paste the following code snippet into the file:

import { initializeApp, getApps } from "firebase/app";
import { getFirestore } from "firebase/firestore";
import { EmailAuthProvider } from "firebase/auth";
import { getAuth } from "firebase/auth";
import { getStorage } from "firebase/storage";

const firebaseConfig = {
    // 👉🏻 your Firebase app configuration code
};

//👇🏻 Initialize Firebase
const app =
    getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];
const provider = new EmailAuthProvider();
const storage = getStorage(app);
const db = getFirestore(app);
const auth = getAuth(app);

//👇🏻 exports each variable for use within the application
export { provider, auth, storage };
export default db;

The code snippet above initializes Firebase Storage, Firestore, and the Email Authentication provider. This setup allows you to add file storage, interact with a database, and implement email/password authentication within the application.

Before interacting with Firebase features, you must set them up in your project dashboard.

Click Build in your dashboard's sidebar navigation. This will open a dropdown menu with various features you can enable for your project.

Select Authentication, Firestore Database, and Storage from the drop-down and add them to the project.

Congratulations! You can now start interacting with these Firebase features in your Next.js project.

Authenticating Client Users

In this section, you will learn how to handle the authentication process for client users using Firebase.

Add a lib/auth-functions.ts file to the Next.js project and copy the following code snippet into the file:

import {
    createUserWithEmailAndPassword,
    signInWithEmailAndPassword,
} from "firebase/auth";
import { getDownloadURL, ref, uploadBytes } from "@firebase/storage";
import db, { auth, storage } from "./firebase";
import { doc, setDoc, getDoc } from "firebase/firestore";

export const clientSignUp = async (form: FormData) => {
    //👇🏻 Get form data
const { name, email, password } = {
        name: form.get("name") as string,
        email: form.get("email") as string,
        password: form.get("password") as string,
 };

    try {
        //👇🏻 Create user using the email and password
        const { user } = await createUserWithEmailAndPassword(
            auth,
            email,
            password
 );
        // 👇🏻 Check if user has been created
        if (!user) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "Failed to create user",
 };
 }
        // 👇🏻 Create a document in the Firebase Firestore
        const docRef = doc(db, "clients", user.uid);
        await setDoc(docRef, {
            name,
            email,
 });
        // 👇🏻 Return user data
        return {
            code: "auth/success",
            status: 201,
            user,
            message: "Acount created successfully! 🎉",
 };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            err,
            message: "Failed to create user",
 };

The clientSignUp function accepts the form data, creates an account using the email and password, and adds a document containing the user's email, ID, and name to Firebase Firestore. Execute the function when the user submits the sign-up form.

Add the following code snippet to the auth-functions.ts file to sign client users into the application.

export const clientLogin = async (form: FormData) => {
    // 👇🏻 Get form data
    const email = form.get("email") as string;
    const password = form.get("password") as string;

    try {
        // 👇🏻 Sign in using the email and password
        const { user } = await signInWithEmailAndPassword(auth, email, password);
        // 👇🏻 Return error if credentials are incorrect
        if (!user) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
 message: "Failed to login",
 };
 }
        // 👇🏻 Retrieve user data from Firebase Firestore
        const docSnap = await getDoc(doc(db, "clients", user.uid));

        // 👇🏻 Return error if document doesn't exist
        if (!docSnap.exists()) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "User is Not a Client",
 };
 }
        // 👇🏻 Return data
        return {
            code: "auth/success",
            status: 200,
            user,
            message: "Login successful",
 };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            err,
            message: "Failed to login",
 };
 }
};

The clientLogin function takes the user's email and password from the form and signs them into the application. It then checks if the user has a document in the Firebase clients collection to confirm that they are a client user and not a therapist before allowing access to client-only pages.

Finally, add a sign out function to the file to allow users to log out of the application when needed.

export const authLogout = async () => {
    try {
        await auth.signOut();
        return { code: "auth/success", status: 200, message: "Logout successful" };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            message: "Failed to logout",
            err,
 };
 }
};

Authenticating Therapists

Here, you’ll learn about the necessary attributes for the therapists and how they can create an account and sign in to the application.

Add the code snippet below to the auth-functions.ts file:

export const therapistSignUp = async (form: FormData) => {
    const userData = {
        name: form.get("name") as string,
        email: form.get("email") as string,
        password: form.get("password") as string,
        qualification: form.get("qualification") as string,
        summary: form.get("summary") as string,
        specialization: form.get("specialization") as string,
        country: form.get("country") as string,
        image: form.get("image") as File,
 };

    //👇🏻 -- Next steps --
    // 1. create an account using the email and password.
    // 2. upload the image to Firebase storage.
    // 3. retrieve the image download URL.
    // 4. create a Firebase document with all the attributes.
};

Modify the therapistSignUp function to create a user using the email and password, upload the therapist's image, and save all the form data to the Firebase therapists collection.

export const therapistSignUp = async (form: FormData) => {
    //  ..👉🏻 form data placeholder

    try {
        // 👇🏻 create an account
        const { user } = await createUserWithEmailAndPassword(
            auth,
            userData.email,
            userData.password
 );
        // 👇🏻 if error return
        if (!user) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "Failed to create user",
 };
 }
        // 👇🏻 upload image
        const imageRef = ref(storage, `therapists/${user.uid}/image`);
        await uploadBytes(imageRef, userData.image).then(async () => {
            // 👇🏻 get image download URL
            const downloadURL = await getDownloadURL(imageRef);
            if (!downloadURL) {
                return {
                    code: "auth/failed",
                    status: 500,
                    user: null,
                    message: "Failed to upload image",
 };
 }
            // 👇🏻 create a Firebase document using the user attributes
            const docRef = doc(db, "therapists", user.uid);

            await setDoc(docRef, {
                name: userData.name,
                email: userData.email,
                specialization: userData.specialization,
                qualification: userData.qualification,
                summary: userData.summary,
                country: userData.country,
                image: downloadURL,
 });
        // 👇🏻 return success message
        return {
            code: "auth/success",
            status: 201,
            user: userData,
            message: "Acount created successfully! 🎉",
 };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            err,
            message: "Failed to create user",
 };
 }
};

Finally, add a therapistsLogin function to the file that takes the user's email and password from the form and signs them into the application. It also checks if the user has a document in the Firebase therapists collection before granting access to the dashboard page.

export const therapistLogin = async (form: FormData) => {
    const email = form.get("email") as string;
    const password = form.get("password") as string;

    try {
        const { user } = await signInWithEmailAndPassword(auth, email, password);

        if (!user) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "Failed to login",
 };
 }

        const docSnap = await getDoc(doc(db, "therapists", user.uid));
        if (!docSnap.exists()) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "User is Not a Therapist",
 };
 }

        return {
            code: "auth/success",
            status: 200,
            user,
            message: "Login successful",
 };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            err,
            message: "Failed to login",
 };
 }
};

Installing the Stream Chat Firebase Extension

The Authenticate with Stream Chat extension automatically connects your Firebase users to Stream Chat, making it easy for Stream to access and manage your users.

Before we proceed, create a Stream account and a new organization that holds all your apps.

Add a new app to the organization and copy the Stream API and Secret key into the .env.local file.

NEXT_PUBLIC_STREAM_API_KEY=<paste_from_Stream_app_dashboard>
STREAM_SECRET_KEY=<paste_from_Stream_app_dashboard>

Next, visit the Stream Chat Firebase Extension page and select the Firebase project where you want to install the extension.

Note: Before installing the extension, you must upgrade your Firebase project to the Blaze (pay-as-you-go) plan.

During installation, enable Artifact Registry, Cloud Functions, and Secret Manager. These permissions allow Stream to access and manage your Firebase users.

Finally, enter your Stream API key and secret in the configuration fields, then click the Install Extension button.

The extension will be installed within a few minutes. Once setup is complete, every new Firebase user will automatically be added to Stream.

The Application Database Design

In this section, you'll learn how to create the required Firestore collections and perform CRUD operations within the application.

Beyond the authentication pages, the app has four key pages:

/clients/dashboard – displays pending payment confirmations, open chats with therapists, and upcoming video call sessions.
/therapists – lists all available therapists and allows clients to filter them based on specialization.
/therapists/dashboard – shows pending payments, lets therapists approve or reject them, and displays open chats and upcoming video sessions.
/therapists/profile/[id] – renders the therapist details using their ID and allows clients to book a session and leave a review.

The table below outlines the attributes of the Firestore collections:

clients	therapists	pending_payments	reviews
user_id	user_id	id	client_id
email	email	client_id	client_name
name	name	client_name	review
	country	therapist_id	therapist_id
	image	payment_id	rating : (integer)
	payPerHour	payment_date
	paymentLink
	qualification
	specialization
	summary

From the table above:

The clients collection stores each user's full name, email address, and ID, all obtained from Firebase Authentication.
The therapists collection holds all attributes related to each therapist. Therapists must set their hourly rate and payment URL from the dashboard to allow clients to make payments and book sessions. The remaining details are displayed on the profile page.
The pending_payments collection records all payments that are yet to be approved by the therapist. Once a therapist approves a booking payment, a Stream channel is automatically created, allowing both the client and therapist to chat and schedule a virtual session.
The reviews collection stores the client's feedback and ratings submitted after a virtual session. The rating value is used to calculate the therapist’s average score.

Database Operations for the Therapists Collection

In this section, you'll learn how to fetch all therapists from the database, retrieve a specific therapist by their ID, and implement a search functionality to filter therapists by specialization.

First, create a lib/db-functions.ts file and add the following imports to the file:

import db from "./firebase";
import {
    collection,
    getDocs,
    getDoc,
    where,
    query,
    doc,
    updateDoc,
    addDoc,
    deleteDoc,
} from "firebase/firestore";

interface UpdateTherapistProps {
    payPerHr: number;
    paymentLink: string;
    userId: string;
}

Run the following function to fetch all therapists from the database:

export const getTherapistsList = async () => {
    try {
        //👇🏻 Query the therapists collection
        const q = query(collection(db, "therapists"));
        const querySnapshot = await getDocs(q);
        //👇🏻 Save all the therapists into the variable
        const therapists: TherapistData[] = querySnapshot.docs.map((doc) => ({
            id: doc.id,
 ...doc.data(),
 })) as TherapistData[];
        //👇🏻 Return the array of therapists
        return {
            code: "doc/success",
            status: 200,
            therapists,
            message: "Therapists fetched successfully",
 };
 } catch (err) {
        return {
            code: "doc/failed",
            status: 500,
            err,
            therapists: null,
            message: "Failed to fetch therapists",
 };
 }
};

Add the following code snippet to the db-functions.ts file:

export const getTherapistProfile = async (uid: string) => {
    try {
        const docSnap = await getDoc(doc(db, "therapists", uid));

        if (!docSnap.exists()) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "Invalid ID",
 };
 }

        return {
            code: "auth/success",
            status: 200,
            user: docSnap.data(),
            message: "User found",
 };
} catch (err) {
        return {
            code: "auth/failed",
            status: 404,
            user: null,
            err,
            message: "User Not Found",
 };
 }
};

The getTherapistProfile function accepts a therapist's ID as a parameter and retrieves all their attributes from the database.

Next, use the function below to retrieve therapists based on their specialization:

export const getTherapistBySpecialization = async (specialization: string) => {
    try {
        const q = query(
            collection(db, "therapists"),
            where("specialization", "==", specialization)
 );
        const querySnapshot = await getDocs(q);
        const therapists: TherapistData[] = querySnapshot.docs.map((doc) => ({
            id: doc.id,
 ...doc.data(),
 })) as TherapistData[];

        return {
            code: "doc/success",
            status: 200,
            therapists,
            message: "Therapists fetched successfully",
 };
 } catch (err) {
        return {
            code: "doc/failed",
            status: 500,
            err,
            therapists: null,
            message: "Failed to fetch therapists",
 };
 }
};

Finally, therapists can update their hourly pay and payment link on their dashboard, enabling clients to make payments and book a therapy session.

xport const updateTherapist = async ({
    payPerHr,
    paymentLink,
    userId,
}: UpdateTherapistProps) => {
    try {
        const therapistRef = doc(db, "therapists", userId);
        await updateDoc(therapistRef, {
            payPerHr,
            paymentLink,
 });
        return {
            code: "doc/success",
            status: 200,
            message: "Therapist updated successfully",
 };
 } catch (err) {
        return {
            code: "doc/failed",
            status: 500,
            err,
            message: "Failed to update therapist",
 };
 }
};

Database Operations for the Reviews Collection*

In this section, you'll learn how to fetch reviews from the database and enable clients to give reviews.

Use the function below to retrieve all reviews associated with a specific therapist:

export const getReviews = async (therapistId: string) => {
    try {
        const q = query(
            collection(db, "reviews"),
            where("therapist_id", "==", therapistId)
 );

        const querySnapshot = await getDocs(q);
        const reviews: Reviews[] = querySnapshot.docs.map((doc) => ({
            id: doc.id,
 ...doc.data(),
 })) as Reviews[];

        return {
            code: "doc/success",
            status: 200,
            reviews,
            message: "Reviews fetched successfully",
 };
 } catch (err) {
        return {
            code: "doc/failed",
            status: 500,
            err,
            reviews: null,
            message: "Failed to fetch reviews",
 };
 }
};

The getReviews function accepts a therapist's ID as a parameter, queries the reviews collection, and returns all the reviews submitted for that therapist.

To allow clients to submit a review for therapists, add the following code snippet to the db-functions file:

export const createReview = async (
    formData: FormData,
    therapistId: string,
    userId: string
) => {
    //👇🏻 accepts form data
    const rating = formData.get("rating") as string;
    const review = formData.get("review") as string;

    //👇🏻 verifies the rating
    if (isNaN(Number(rating)) || Number(rating) < 1 || Number(rating) > 5) {
        return {
            code: "doc/failed",
            status: 500,
            message: "Invalid rating",
 };
 }
    // 1. Retrieve user object using the userId
    // 2. Query the reviews collection to ensure the user hasn't left a review earlier.
    // 3. Add the client's review to the collection
};

Modify the createReview function as follows:

export const createReview = async (
    formData: FormData,
    therapistId: string,
    userId: string
) => {
    //...form data and its verification

    // Retrieve user object using the userId
    const clientSnap = await getDoc(doc(db, "clients", userId));
    if (!clientSnap.exists()) {
        return {
            code: "doc/failed",
            status: 500,
            message: "User client not found",
 };
 }
    // Query the reviews collection
    const reviewsRef = query(
        collection(db, "reviews"),
        where("client_id", "==", userId),
        where("therapist_id", "==", therapistId)
 );
    const querySnapshot = await getDocs(reviewsRef);
    // Review already exist
    if (!querySnapshot.empty) {
        return {
            code: "doc/failed",
            status: 500,
            message: "You have already submitted a review for this therapist",
 };
 }
    // Add review to the collection
    await addDoc(collection(db, "reviews"), {
        client_name: clientSnap.data()?.name,
        client_id: userId,
        therapist_id: therapistId,
        rating: Number(rating),
        review,
 });

    return {
        code: "doc/success",
        status: 200,
        message: "Review submitted successfully",
 };
};

The createReview function accepts the form data, including the rating, review text, therapist ID, and client ID (since only clients can leave reviews). The function does the following:

Retrieves the client object using the client ID to get the full name.
Checks if the client has already left a review for the therapist.
If the client has previously submitted a review, it returns an error.
If not, it adds the new review to the reviews collection.

Database Operations for the Pending Payments Collection

In this section, you'll learn how to retrieve the pending payments collection, allow clients to add new payments, and enable therapists to approve or cancel payments.

Copy the following code snippet into the db-functions.ts file:

interface PaymentProps {
    uid: string;
    user: "client_id" | "therapist_id";
}

export const getPendingPayments = async ({ uid, user }: PaymentProps) => {
    try {
        const q = query(collection(db, "pending_payments"), where(user, "==", uid));
        const querySnapshot = await getDocs(q);
        const pendingPayments: PendingPayments[] = querySnapshot.docs.map(
 (doc) =>
 ({
                    id: doc.id,
 ...doc.data(),
 } as PendingPayments)
 );
        return {
            code: "doc/success",
            status: 200,
            pendingPayments,
            message: "Pending payments fetched successfully",
 };
 } catch (err) {
        return {
            code: "doc/failed",
            status: 500,
            pendingPayments: null,
            err,
            message: "Failed to fetch pending payments",
 };
 }
};

The code snippet above retrieves the pending payments for both therapist and client users.

Clients can also submit their payment details after successfully making a payment, allowing therapists to approve it.

export const submitPayment = async (
    formData: FormData,
    userId: string,
    therapistId: string
) => {
    const paymentId = formData.get("paymentId") as string;
    const payeeName = formData.get("payeeName") as string;
    const paymentDate = formatPaymentDate(formData.get("paymentDate") as string);

    if (therapistId === userId) {
        return {
            code: "doc/failed",
            status: 500,
            message: "You cannot confirm your own payment",
 };
 }

    try {
        await addDoc(collection(db, "pending_payments"), {
            client_name: payeeName,
            client_id: userId,
            therapist_id: therapistId,
            payment_id: paymentId,
            payment_date: paymentDate,
 });
 } catch (err) {
        return {
            code: "doc/failed",
            status: 500,
            message: "Failed to submit details",
            err,
 };
 }
};

The submitPayment function accepts the payee's name, payment date, and reference ID and adds the payment information to the pending_payments collection.

Therapists can then approve or decline the payment. If a therapist declines the payment, the payment data is deleted immediately from the collection. If the therapist approves the payment, a new chat channel is created with the client before the pending_payments collection is updated.

export const cancelPayment = async (payment: PendingPayments) => {
    try {
        await deleteDoc(doc(db, "pending_payments", payment.id));
        return {
            code: "doc/success",
            status: 200,
            message: "Payment cancelled successfully",
 };
 } catch (err) {
        return {
            code: "doc/failed",
            status: 500,
            err,
            message: "Failed to cancel payment",
 };
 }
};

The cancelPayment function accepts the payment ID and deletes its document from the collection. In the next section, you will learn how to approve a payment by creating a new chat channel with the therapist.

How to Integrate 1-on-1 Chat Feature with Stream

In this section, you'll learn how to create private channels and send user messages within the application. This enables therapists to chat with clients before scheduling a call.

Before we proceed, install the following Stream packages to integrate chat and video call features into the application.

// 👇🏻 for Stream Chat SDK
npm install stream-chat stream-chat-react

//👇🏻 for Stream Video & Audio SDK
npm install @stream-io/node-sdk @stream-io/video-react-sdk

Import the Stream Chat and Audio & Video CSS files into your layout.tsx file:

import type { Metadata } from "next";
import { Rubik } from "next/font/google";
import "@stream-io/video-react-sdk/dist/css/styles.css";
import "stream-chat-react/dist/css/v2/index.css";
import "./globals.css";

const inter = Rubik({
    weight: ["300", "400", "500", "600", "700"],
    subsets: ["latin"],
});

export const metadata: Metadata = {
    title: "TherapyMart",
    description: "Generated by create next app",
};

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

Create an actions/stream.action.ts file and copy the following code snippet into the file:

"use server";
import { StreamChat } from "stream-chat";
import { StreamClient } from "@stream-io/node-sdk";
const STREAM_API_KEY = process.env.NEXT_PUBLIC_STREAM_API_KEY!;
const STREAM_API_SECRET = process.env.STREAM_SECRET_KEY!;

// 👇🏻 -- Stream server client  --
const serverClient = StreamChat.getInstance(STREAM_API_KEY, STREAM_API_SECRET);

//👇🏻 -- create auth token function --
export async function createToken(userId: string): Promise<string> {
    if (!userId) throw new Error("User is not authenticated");
    return serverClient.createToken(userId);
}

The code snippet above initializes the Stream Chat server client, allowing us to perform various Stream actions on the server side. The createToken function accepts a user object and creates an authentication token using the user's ID.

Since Firebase works on the client side, we also need a Stream client to perform actions such as fetching calls and existing channels, and creating and joining them.

To achieve this, create a hooks folder in your project and add a useGetStreamClient.ts custom hook within a (stream) folder in your Next.js app. This hook will manage the client-side Stream functionality.

cd app && \
mkdir (stream) && cd (stream) && \
mkdir hooks && cd hooks && \
touch useGetStreamClient.ts

Copy the following code snippet into the useGetStreamClient.ts:

import { useCreateChatClient } from "stream-chat-react";
import { createToken } from "../../../../actions/stream.action";
import { useCallback } from "react";

export const useGetStreamClient = (
    user: TherapistData | ClientData
) => {
    //👇🏻 executes the createToken function from the server
    const tokenProvider = useCallback(async () => {
        return await createToken(user);
 }, [user]);

    //👇🏻 creates the chat client
    const client = useCreateChatClient({
        apiKey: process.env.NEXT_PUBLIC_STREAM_API_KEY!,
        tokenOrProvider: tokenProvider,
        userData: { id: user.id, name: user.name, image: user.image },
 });
    //👇🏻 returns the chat client
    if (!client) return { client: null };

    return { client };
};

Next, add a createChannel function within the stream.action.ts file:

export async function createChannel({
    therapist,
    clientName,
    clientId,
}: {
    therapist: TherapistData;
    clientName: string;
    clientId: string;
}) {
    try {
        //👇🏻 check if channel already exists
        const filter = {
            type: "messaging",
            members: { $in: [therapist.id, clientId] },
 };
        const sort = [{ last_message_at: -1 }];

        const channels = await serverClient.queryChannels(filter, sort, {
            watch: true,
            state: true,
 });
        //👇🏻 channel already exists? return its ID
        if (channels.length > 0) {
            return { success: true, error: null, id: channels[0].id };
 }
        //👇🏻 channel configuration
        const channel = serverClient.channel("messaging", `therapist-${clientId}`, {
            name: `${clientName} with ${therapist.name}`,
            members: [therapist.id, clientId],
            created_by_id: therapist.id,
 });
        //👇🏻 create channel
        await channel.create();
        //👇🏻 return its ID
        return { success: true, error: null, id: channel.id };
 } catch (err) {
        console.log("Error creating channel:", err);
     return { success: false, error: "Failed to create channel", id: null };
 }
}

The createChannel function takes the therapist's data, client ID, and name as parameters. Then, it checks if the therapist and the client already have a chat channel. If so, it returns the existing channel's ID; otherwise, it creates a new one.

When a therapist approves the payment, call the createChannel function to set up a private messaging channel between the therapist and client.

export const approvePayment = async (
    payment: PendingPayments,
    therapist: TherapistData
) => {
    try {
        //👇🏻 create chat channel
        const createChat = await createChannel({
            therapist,
            clientName: payment.client_name,
            clientId: payment.client_id,
 });

        if (!createChat.success) {
            return {
                code: "doc/failed",
                status: 500,
                message: createChat.error,
 };
 }
        //👇🏻 delete data after creating a chat
        await deleteDoc(doc(db, "pending_payments", payment.id));

        return {
            code: "doc/success",
            status: 200,
            message: "Payment approved successfully",
 };
 } catch (err) {
        return {
            code: "doc/failed",
            status: 500,
          err,
            message: "Failed to approve payment",
 };
 }
};

The approvePayment function accepts the therapist's data and the client's payment details. It executes the createChannel function, and once the channel is successfully created, it removes the payment details from the pending_payments collection.

You can retrieve all user’s chat channels using the function below:

import { Channel } from "stream-chat";

export default function Page() {
    const [channels, setChannels] = useState<Channel[] | null>(null);
    const { client: chatClient } = useGetStreamClient(user);

    const getChannels = useCallback(async () => {
        if (!chatClient || !user) return;
        const channelList = await chatClient.queryChannels({
                type: "messaging",
                members: { $in: [user.id] },
 }),

        setChannels(channelList);

 }, [user, chatClient]);

    useEffect(() => {
        getChannels();
 }, [getChannels]);

return (
 {/** -- UI elements  -- */}
)
}

The code snippet above shows how to retrieve chat channels for a Stream user. The useGetStreamClient hook accepts a user object and returns the Stream Chat client, which is used to fetch all the user channels.

Stream provides multiple UI components to render the chat interface that allow users to send messages and share files. Create a (stream)/chat/[id].tsx file within the Next.js app directory and copy the following code snippet into it:

"use client";
import {
    Chat,
    Channel,
    ChannelList,
    Window,
    ChannelHeader,
    MessageList,
    MessageInput,
} from "stream-chat-react";
import { useGetStreamClient } from "@/app/(stream)/hooks/useGetStreamClient";

export default function StreamChatUI({
    user,
}: {
    user: ClientData | TherapistData;
}) {
    const { client } = useGetStreamClient(user!);

    const filters = { members: { $in: [user.id] }, type: "messaging" };
    const options = { presence: true, state: true };

    if (!client) return <div>Loading...</div>;

    return (
 <div className='W-full min-h-screen'>
 <Chat client={client}>
 <div className='chat-container'>
                    {/* -- Channel List -- */}
 <div className='channel-list'>
 <ChannelList
                            sort={{ last_message_at: -1 }}
                            filters={filters}
                            options={options}
 />
 </div>

                    {/* -- Messages Panel -- */}
 <div className='chat-panel'>
 <Channel>
 <Window>
 <ChannelHeader />
 <MessageList />
 <MessageInput />
 </Window>
 </Channel>
 </div>
 </div>
 </Chat>
 </div>
 );
}

From the code snippet above:

The useGetStreamClient custom hook returns the Stream Chat client for the current user.
Chat component initializes the Stream Chat client and wraps the entire Chat page.
ChannelList shows available chat channels.
Channel sets up an active chat session.
Window contains the message display and input areas.
ChannelHeader, MessageList, and MessageInput provide a fully functional chat interface.

How to Book Video Call Sessions with Stream

In this section, you'll learn how to integrate video calling functionality into the Next.js application, allowing therapists to schedule virtual sessions with clients.

Copy the following code snippet into the actions/stream.action.ts file:

export const tokenProvider = async (user_id: string) => {
    if (!STREAM_API_KEY) throw new Error("Stream API key secret is missing");
    if (!STREAM_API_SECRET) throw new Error("Stream API secret is missing");

    const streamClient = new StreamClient(STREAM_API_KEY, STREAM_API_SECRET);

    const expirationTime = Math.floor(Date.now() / 1000) + 3600;
    const issuedAt = Math.floor(Date.now() / 1000) - 60;

    const token = streamClient.generateUserToken({
        user_id,
        exp: expirationTime,
        validity_in_seconds: issuedAt,
 });

    return token;
}

The tokenProvider function generates an authentication token for the user, enabling Stream to identify and manage users during real-time communication.

Within the (stream)/hooks folder, add the following files:

cd app && cd (stream)/hooks && \
touch useGetCallById.ts useGetCalls.ts

The useGetCallById file defines a React hook that fetches details of a specific Stream call via its ID, while the useGetCalls hook retrieves all the calls created by a particular Stream user.

Let's create these custom React hooks.

Copy the following code snippet into the useGetCallById.ts file:

import { useEffect, useState } from "react";
import { Call, useStreamVideoClient } from "@stream-io/video-react-sdk";

export const useGetCallById = (id: string | string[]) => {
    const [call, setCall] = useState<Call>();
    const [isCallLoading, setIsCallLoading] = useState(true);

    const client = useStreamVideoClient();

    useEffect(() => {
        if (!client) return;

        const loadCall = async () => {
            try {
                // https://getstream.io/video/docs/react/guides/querying-calls/#filters
                const { calls } = await client.queryCalls({
                    filter_conditions: { id },
 });

                if (calls.length > 0) setCall(calls[0]);

                setIsCallLoading(false);
 } catch (error) {
                console.error(error);
                setIsCallLoading(false);
 }
 };

        loadCall();
 }, [client, id]);

    return { call, isCallLoading };
}

Add the following to the useGetCalls.ts file:

import { useEffect, useState } from "react";
import { Call, useStreamVideoClient } from "@stream-io/video-react-sdk";

export const useGetCalls = (id: string) => {
    const client = useStreamVideoClient();
    const [calls, setCalls] = useState<Call[]>();
    const [isLoading, setIsLoading] = useState(false);

    useEffect(() => {
        const loadCalls = async () => {
            if (!client || !id) return;

            setIsLoading(true);

            try {
                const { calls } = await client.queryCalls({
                    sort: [{ field: "starts_at", direction: 1 }],
                    filter_conditions: {
                        starts_at: { $exists: true },
                        $or: [{ created_by_user_id: id }, { members: { $in: [id] } }],
 },
 });

                setCalls(calls);
 } catch (error) {
                console.error(error);
 } finally {
                setIsLoading(false);
 }
 };

        loadCalls();
 }, [client, id]);

    const now = new Date();

    const upcomingCalls = calls?.filter(({ state: { startsAt } }: Call) => {
        return startsAt && new Date(startsAt) > now;
 });

    const ongoingCalls = calls?.filter(
 ({ state: { startsAt, endedAt } }: Call) => {
            return startsAt && new Date(startsAt) < now && !endedAt;
 }
 );

    return { upcomingCalls, isLoading, ongoingCalls };
}

The useGetCalls hook retrieves all calls created by the recruiter, including ongoing and upcoming calls. It also provides an isLoading state to indicate when data is being fetched, enabling conditional rendering.

Next, to create, join, and retrieve calls, wrap the pages that require access to the calls with the StreamVideo component.

Add a providers/StreamVideoProvider component inside the (stream) folder. Then, copy the following code snippet into the file:

"use client";
import { tokenProvider } from "../../../../actions/stream.action";
import { StreamVideo, StreamVideoClient } from "@stream-io/video-react-sdk";
import { useState, ReactNode, useEffect, useCallback } from "react";
import { onAuthStateChanged, User } from "firebase/auth";
import { auth } from "@/lib/firebase";
import db from "@/lib/firebase";
import { doc, getDoc } from "firebase/firestore";
import { useRouter } from "next/navigation";
import { Loader2 } from "lucide-react";

const apiKey = process.env.NEXT_PUBLIC_STREAM_API_KEY!;

export const StreamVideoProvider = ({ children }: { children: ReactNode }) => {
    const [videoClient, setVideoClient] = useState<StreamVideoClient | null>(
        null
 );

    const [user, setUser] = useState<User | null>(null);
    const router = useRouter();

    // 👉🏻 auth functions placeholder

    return <StreamVideo client={videoClient}>{children}</StreamVideo>;
};

Update the component with the authentication functions:

useEffect(() => {
        const unsubscribe = onAuthStateChanged(auth, async (user) => {
            if (user?.uid) {
                setUser(user);
 } else {
                return router.push("/clients/login");
 }
 });

        return () => unsubscribe();
 }, [router]);

    const getUser = useCallback(async () => {
        if (!user) return null;

        const [therapistSnap, clientSnap] = await Promise.all([
            getDoc(doc(db, "therapists", user.uid)),
            getDoc(doc(db, "clients", user.uid)),
 ]);

        if (!therapistSnap.exists() && !clientSnap.exists()) {
            console.warn("User data not found in Firestore");
            return null;
 }
   return new StreamVideoClient({
            apiKey,
            user: {
            id: user.uid,
            name: therapistSnap.data()?.name || clientSnap.data()?.name,
            image: therapistSnap.data()?.image || null,
 },
            tokenProvider: () => tokenProvider(user.uid),
 });
 }, [user]);

    useEffect(() => {
        const result = getUser();
        if (result) {
            result.then((client) => setVideoClient(client));
 }
 }, [getUser]);

    if (!videoClient)
        return (
            <div className='h-screen flex items-center justify-center'>
                <Loader2 size='32' className='mx-auto animate-spin' />
            </div>
 );

The code snippet above does the following:

retrieves the authenticated Firebase user object and redirects them to the login page if they are not signed in.
fetches the user's data from the therapists or clients Firestore collection and initializes a StreamVideoClient with their details.
updates the videoClient state once the user data is retrieved, displaying a loading spinner while waiting for the client to be set.

Finally, therapists need to be able to schedule calls with clients. They can execute this function after submitting a form that accepts the meeting title and a specific date and time for the therapy session.

import { useStreamVideoClient } from "@stream-io/video-react-sdk";
const client = useStreamVideoClient();

const handleScheduleCall = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    if (!description || !dateTime || !client) return;

    try {
        const id = crypto.randomUUID(); //👉🏻 generates a random id
        const call = client.call("default", id);
        if (!call) throw new Error("Failed to create meeting");
        // 👇🏻 creates a call
        await call.getOrCreate({
            data: {
                starts_at: new Date(dateTime).toISOString(),
                custom: {
                    description,
 },
                members: [{ user_id: clientId }, { user_id: therapistId }],
 },
 });
 } catch (error) {
        console.error(error);
 }
};

The code snippet above creates a Stream video call with a default call type. It assigns the call a unique ID, sets the scheduled date and time, and includes a custom description.

Note: Ensure that the <StreamVideoProvider> component wraps the recruiter's dashboard where the video call is created. You can achieve this by adding a layout.tsx file to the dashboard page and wrapping all child elements with <StreamVideoProvider>.

Stream Call UI Components

Here, you will learn how to create the call page, where the therapist and the client can communicate via video call, share screens, and seamlessly meet.

First, create an interview/[id]/page.tsx file within the (stream) folder and add copy the following code snippet into the file:

"use client";
import { useGetCallById } from "@/app/(stream)/hooks/useGetCallById";
import { useParams } from "next/navigation";
import { StreamCall, StreamTheme } from "@stream-io/video-react-sdk";
import { Loader2 } from "lucide-react";
import { useState } from "react";
import SetUp from "../components/SetUp";
import CallRoom from "../components/CallRoom";

export default function CallPage() {
    const { id } = useParams<{ id: string }>();
    const { call, isCallLoading } = useGetCallById(id);
    const [isCallJoined, setIsCallJoined] = useState(false);

    if (!call || isCallLoading) {
        return (
            <main className='min-h-screen w-full items-center justify-center'>
                <Loader2 className='animate-spin text-blue-500' />
            </main>
 );
 }

    return (
        <main className='min-h-screen w-full items-center justify-center'>
            <StreamCall call={call}>
                <StreamTheme>
                    {isCallJoined ? (
                        <CallRoom call={call} />
 ) : (
                        <SetUp call={call} setIsCallJoined={setIsCallJoined} />
 )}
                </StreamTheme>
            </StreamCall>
        </main>
 );
}

In the code snippet above:

The StreamCall component wraps the entire call interface and enables access to audio and video calling features. It receives the call object as a prop.
The StreamTheme component provides styling for the call interface and allows theme customization.
The isCallJoined state is initially set to false, which renders the SetUp component. Once its value is true, the CallRoom component is rendered to display the active call interface.

Add the SetUp component within the components folder and copy the following code snippet into the file:

"use client";
import { Call } from "@stream-io/video-react-sdk";
import { useState } from "react";
import { Camera, CameraOff, Mic, MicOff } from "lucide-react";
import { toast } from "sonner";
import { VideoPreview, DeviceSettings } from "@stream-io/video-react-sdk";

export default function SetUp({
    call,
    setIsCallJoined,
}: {
    call: Call;
    setIsCallJoined: (value: boolean) => void;
}) {
    const [camEnabled, setCamEnabled] = useState<boolean>(false);
    const [micEnabled, setMicEnabled] = useState<boolean>(false);

    const handleEnableCamera = () => {
        if (!camEnabled) {
            call?.camera.enable();
            setCamEnabled(true);
            toast.success("Camera enabled");
 } else {
            call?.camera.disable();
            setCamEnabled(false);
            toast.error("Camera disabled");
 }
 };

    const handleEnableMic = () => {
        if (!micEnabled) {
            call?.microphone.enable();
            setMicEnabled(true);
            toast.success("Microphone enabled");
 } else {
            call?.microphone.disable();
            setMicEnabled(false);
            toast.error("Microphone disabled");
 }
 };

    const handleJoinCall = () => {
        call.join();
        setIsCallJoined(true);
 };

return ({/** — 👉🏻 Call Set up elements 👈🏼 —*/})

}

The SetUp component provides a pre-call interface where users can test and toggle their camera and microphone settings before joining a Stream call.. The handleJoinCall function allows call members to join the call.

Return the following UI elements from the component:

return (
 <main>
 <h2>
            {call.state.custom.description}
 </h2>
 <p>
 Please update your microphone and camera settings
 </p>

 <div>
 <VideoPreview className='w-full h-full mt-4' />
 </div>

 <div className='flex gap-4 my-4'>
 <button
                onClick={handleEnableCamera}
 >
                {camEnabled ? (
 <CameraOff className='text-blue-500' size={40} />
 ) : (
 <Camera className='text-blue-500' size={40} />
 )}
 </button>

 <button
                      onClick={handleEnableMic}
 >
                {micEnabled ? (
 <MicOff className='text-blue-500' size={40} />
 ) : (
 <Mic className='text-blue-500' size={40} />
 )}
 </button>

 <button>
 <DeviceSettings />
 </button>
 </div>

 <button
                  onClick={handleJoinCall}
 >
 Join Call
 </button>
 </main>
);

Create the CallRoom component and copy the following code into the file:

"use client";
import { useState } from "react";
import { useRouter } from "next/navigation";
import {
    PaginatedGridLayout,
    SpeakerLayout,
    CallControls,
    Call,
    useCallStateHooks,
} from "@stream-io/video-react-sdk";
import { toast } from "sonner";
type CallLayoutType = "grid" | "speaker-left" | "speaker-right";

export default function CallRoom({ call }: { call: Call }) {
    const [layout, setLayout] = useState<CallLayoutType>("grid");
    const router = useRouter();

    const handleLeave = () => {
        if (confirm("Are you sure you want to leave the call?")) {
            router.push("/");
 }
 };

    const CallLayout = () => {
        switch (layout) {
            case "grid":
                return <PaginatedGridLayout />;
            case "speaker-right":
                return <SpeakerLayout participantsBarPosition='left' />;
            default:
                return <SpeakerLayout participantsBarPosition='right' />;
 }
 };

    return (
 <section className='relative min-h-screen w-full overflow-hidden pt-4'>
 <div className='relative flex size-full items-center justify-center'>
 <div className='flex size-full max-w-[1000px] items-center'>
 <CallLayout />
 </div>
 <div className='fixed bottom-0 flex w-full items-center justify-center gap-5'>
 <CallControls onLeave={handleLeave} />
 </div>

 <div className='fixed bottom-0 right-0 flex items-center justify-center gap-5 p-5'>
 <EndCallButton call={call} />
 </div>
 </div>
 </section>
 );
}

The CallLayout and CallControls components are rendered on the page, allowing users to communicate, share their screen, turn their camera on or off, and engage in conversations through reactions.

Finally, the EndCallButton component will be created to enable the host (therapist) to end the call for everyone.

const EndCallButton = ({ call }: { call: Call }) => {
    const { useLocalParticipant } = useCallStateHooks();
    const localParticipant = useLocalParticipant();
    const router = useRouter();

    const participantIsHost =
        localParticipant &&
        call.state.createdBy &&
        localParticipant.userId === call.state.createdBy.id;

    if (!participantIsHost) return null;

    const handleEndCall = () => {
        call.endCall();
        toast("Call ended for everyone", {
            description: "The call has been ended for everyone",
 });
        router.push("/");
 };

    return (
 <button
            className='bg-red-500 text-white px-4 py-2 rounded-md mt-2'
            onClick={handleEndCall}
 >
 End Call for Everyone
 </button>
 );
};

The code snippet above ensures that only the call host can end the call for all participants. It first checks if the current user is the host before displaying the "End Call for Everyone" button.

The source code is available on GitHub:
https://github.com/dha-stix/stream-therapy-app

Next Steps

So far, you've learned how to build a full-stack therapy marketplace app using Stream and Firebase. This platform allows users to connect with professional therapists, schedule virtual sessions, and communicate through real-time chat powered by Stream.

Here are some valuable resources to help you get started:

Thank you for reading. 🎉

A great portfolio project for anyone looking forward to building fullstack applications

David Asaolu — Thu, 24 Apr 2025 05:24:54 +0000

David Asaolu for Stream

Apr 23 '25

Build a Job Application and Interview App with NextJS, Stream & Firebase

#javascript #tutorial #webdev #react

Comments 7

28 min read

Build a Job Application and Interview App with NextJS, Stream & Firebase

David Asaolu — Wed, 23 Apr 2025 11:42:41 +0000

Hiring the right candidate and finding the perfect job can be challenging. Recruiters need an efficient way to manage job postings, screen applicants, and conduct virtual interviews—all in one platform.

In this tutorial, you will learn how to build a job application and interviewing platform using Next.js, Stream, and Firebase. This app will allow recruiters to post job openings, review applications, and schedule interviews. Job seekers can also apply for jobs and communicate with recruiters.

The Stream Video & Audio API will enable recruiters to schedule and conduct virtual interviews, and the Stream Chat SDK will allow them to chat with shortlisted candidates.

App Overview

The application has two types of users: job seekers and recruiters.

Job seekers can:

Have a public profile URL and can upload a downloadable resume.
See a job feed tailored to their selected interests upon signing in.
Apply for jobs, chat with recruiters, and join online interviews within the application.
Track their progress on every job application.

Recruiters can:

Create job postings.
Manage applications by accepting or rejecting candidates.
Chat privately with shortlisted applicants.
Schedule online interviews and hire the best candidate.

Here is the application demo:

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We will use the following tools:

Firebase - a Backend-as-a-service platform developed by Google to enable us to add authentication, database, real-time communication, file storage, cloud functions, and many others within software applications.
Stream React Chat SDK and React Video SDK - SDKs that enable real-time chat and video/audio communication in your application.
Shadcn UI: a UI component library that provides customizable, beautifully designed, and accessible UI components for your applications.

Create a Next.js project by running the following code snippet:

npx create-next-app job-interview-app

Install the package dependencies for the project:

npm install firebase @stream-io/node-sdk @stream-io/video-react-sdk stream-chat stream-chat-react

To install the Shadcn UI library, follow the installation guide.

Once everything is set up, your Next.js project is ready.
Now, let's start building! 🚀

How to Set up Firebase in a Next.js Application

In this section, you'll learn how to install Firebase in a Next.js application and configure the Firestore Database, Firebase storage and authentication within your Next.js application.

Setting up Firebase in a Next.js Application

Install the Firebase Node.js package by running the code snippet below:

npm install firebase

Open the Firebase Console in your browser and create a new Firebase project.

Within the project dashboard, click the web icon </> to add a Firebase app to the project.

Register the app by entering a nickname, then copy the auto-generated Firebase configuration code. You will need this code to connect your application to the Firebase backend.

Create a lib/firebase.ts file within the Next.js src folder and paste the following code snippet into the file:

import { initializeApp, getApps } from "firebase/app";
import { getFirestore } from "firebase/firestore";
import { EmailAuthProvider } from "firebase/auth";
import { getAuth } from "firebase/auth";
import { getStorage } from "firebase/storage";

const firebaseConfig = {
    // 👉🏻 your Firebase app configuration code
};

//👇🏻 Initialize Firebase
const app =
    getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];
const provider = new EmailAuthProvider();
const storage = getStorage(app);
const db = getFirestore(app);
const auth = getAuth(app);

//👇🏻 exports each variable for use within the application
export { provider, auth, storage };
export default db;

Before interacting with Firebase features, you must set them up in your project dashboard.

Click Build in the sidebar navigation of your dashboard. This will open a dropdown menu with various features you can enable for your project.

Select Authentication, Firestore Database, and Storage from the drop-down and add them to the project.

Congratulations! You can now start interacting with these Firebase features in your Next.js project.

Authenticating Job Seekers

In this section, you’ll learn about the necessary attributes for job seekers and how they can create an account, sign in, and sign out of the application.

Before we proceed, create a types.d.ts file at the root of your Next.js project and copy the following code into it:

//👇🏻 before Firebase upload
interface JobSeeker {
    name: string;
    email: string;
    password: string;
    image: File;
    bio: string;
    cv: File;
    fieldOfInterest: "tech" | "consulting" | "finance" | "healthcare";
    portfolioUrl: string;
}
//👇🏻 after Firebase upload
interface JobSeekerFirebase {
    name: string;
    email: string;
    image: string;
    bio: string;
    cv: string;
    id: string;
    fieldOfInterest: "tech" | "consulting" | "finance" | "healthcare";
    portfolioUrl: string;
}

The code snippet above defines the data structure for a job seeker. The JobSeeker interface shows that job seekers provide their name, email, password, short bio, field of interest, and portfolio URL when signing up. They must also upload their CV/Resume and a professional headshot image.

In the JobSeekerFirebase structure, the CV and image fields are represented as strings because, after uploading the files, we'll retrieve their Firebase storage URLs.

Create a lib/auth-functions.ts file. It will contain the Firebase authentication functions for both job seekers and recruiters, so you can easily import them into any component where these functions are needed.

mkdir lib && cd lib && \
touch auth-functions.ts

Next, add the signup function to the file:

import {
    createUserWithEmailAndPassword,
    signInWithEmailAndPassword,
} from "firebase/auth";
import { getDownloadURL, ref, uploadBytes } from "@firebase/storage";
import db, { auth, storage } from "./firebase";
import { doc, setDoc, getDoc } from "firebase/firestore";

export const jobSeekerSignUp = async (form: FormData) => {
    //👇🏻 Things to do here:
    // 1. get the form data
    // 2. create a user using the email and password
    // 3. upload the CV and headshot to Firebase storage
    // 4. create a Firestore collection using the jobseeker data
    // 5. return errors at each stage.
}

Modify the function to create a new user in Firebase.

export const jobSeekerSignUp = async (form: FormData) => {
    const userData: JobSeeker = {
        name: form.get("name") as string,
        email: form.get("email") as string,
        bio: form.get("bio") as string,
        password: form.get("password") as string,
        fieldOfInterest: form.get("field") as JobSeeker["fieldOfInterest"],
        image: form.get("image") as File,
        cv: form.get("cv") as File,
        portfolioUrl: form.get("url") as string,
 };
    //👇🏻 creates a Firebase user using the email and password
    const { user } = await createUserWithEmailAndPassword(
        auth,
        userData.email,
        userData.password
 );
    //👇🏻 returns an error message
    if (!user) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to create user",
 };
 }

    // 3. upload the CV and headshot to Firebase storage
    // 4. create a Firestore collection using the jobseeker data
    // 5. return errors at each stage.
};

Finally, add the following code snippet within the jobSeekerSignUp function to upload the user's resume and headshot to Firebase storage and create a Firebase collection for the user.

export const jobSeekerSignUp = async (form: FormData) => {
    //👉🏻 ...other functions for step 1-2
      //👇🏻 creates a Firebase storage ref using the user's ID
    const cvRef = ref(storage, `resumes/${user.uid}/cv`);
    const imageRef = ref(storage, `applicants/${user.uid}/image`);

    //👇🏻 uploads the image and CV to Firebase and create a Firebase collection
    await uploadBytes(cvRef, userData.cv).then(async () => {
        await uploadBytes(imageRef, userData.image).then(async () => {
            const [cvDownloadURL, imageDownloadURL] = await Promise.all([
                getDownloadURL(cvRef),
                getDownloadURL(imageRef),
 ]);
            if (!cvDownloadURL || !imageDownloadURL) {
                return {
                    code: "auth/failed",
                    status: 500,
                    user: null,
                    message: "Failed to upload cv or image",
 };
 }
            //👇🏻 creates a Firebase collection including the user ID & download URLs
            const docRef = doc(db, "jobSeekers", user.uid);

            await setDoc(docRef, {
                name: userData.name,
                email: userData.email,
                bio: userData.bio,
                fieldOfInterest: userData.fieldOfInterest,
                portfolioUrl: userData.portfolioUrl,
                cv: cvDownloadURL,
                image: imageDownloadURL,
 });
 });
 });
    //👇🏻 returns the user object and success messages

    return {
        code: "auth/success",
        status: 200,
        user,
        message: "Acount created successfully! 🎉",
 };
}

The code snippet above accepts the user form data, uploads the resume and headshot image to Firebase storage, authenticates the user, and creates a Firebase collection containing the user's attributes.

To allow job seekers to sign into the application, add this function to the lib/auth-functions.ts file:

export const jobSeekerAuthLogin = async (form: FormData) => {
    //👇🏻 Things to do here:
    // 1. accept the user's email and password
    // 2. authenticates and validate user credentials
    // 3. check if user exists in the jobSeekers Firebase collection
    // 4. create a Stream user using the data (later in the tutorial)
    // 5. return errors at each stage.
};

Modify the function to perform the tasks listed above:

export const jobSeekerAuthLogin = async (form: FormData) => {
    const email = form.get("email") as string;
    const password = form.get("password") as string;
    //👇🏻 authenticate user
    const { user } = await signInWithEmailAndPassword(auth, email, password);

    if (!user) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to login",
 };
 }
    //👇🏻 check if user exists in the collection
    const userRef = doc(db, "jobSeekers", user.uid);
    const docSnap = await getDoc(userRef);

    if (!docSnap.exists()) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "User Not a Job Seeker",
 };
 }

    return {
        code: "auth/success",
        status: 200,
        user,
        message: "Login successful",
 };
};

The code snippet above accepts the user's email and password, validates the credentials using Firebase Authentication, and checks if the user exists in the jobSeekers Firebase collection before granting access to the application.

Authenticating Recruiters

Here, you’ll learn about the necessary attributes for recruiters and how they can create an account, sign in, and sign out of the application.

Copy the following code snippet into the lib/auth-functions.ts:

export const recruiterSignUp = async (form: FormData) => {
    //👇🏻 Things to do here:
    // 1. get the form data
    // 2. create a user using the email and password
    // 3. upload the recruiter's image to Firebase storage
    // 4. create a Firestore collection using the recruiter data
    // 5. return errors at each stage.
};

Modify the sign-up function as shown below:

export const recruiterSignUp = async (form: FormData) => {
    const userData: Recruiter = {
        name: form.get("name") as string,
        email: form.get("email") as string,
        companyName: form.get("companyName") as string,
        companyPosition: form.get("companyPosition") as string,
        password: form.get("password") as string,
        field: form.get("field") as Recruiter["field"],
        image: form.get("image") as File,
        url: form.get("url") as string,
 };

    const { user } = await createUserWithEmailAndPassword(
        auth,
        userData.email,
        userData.password
 );

    if (!user) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to create user",
 };
 }
    // 3. upload the recruiter's image to Firebase storage
    // 4. create a Firestore collection using the recruiter data
    // 5. return errors at each stage.
}

The recruiterSignUp function accepts the form data, creates a Firebase user using the recruiter's email and password, and returns the user object.

Next, add the following code snippet within the recruiterSignUp function:

export const recruiterSignUp = async (form: FormData) => {
    //👉🏻 Recruiter sign up function for steps 1-2

    const imageRef = ref(storage, `recruiters/${user.uid}/image`);
    await uploadBytes(imageRef, userData.image).then(async () => {
        const downloadURL = await getDownloadURL(imageRef);
        if (!downloadURL) {
            return {
                code: "auth/failed",
                status: 500,
                user: null,
                message: "Failed to upload image",
 };
 }
        const docRef = doc(db, "recruiters", user.uid);

        await setDoc(docRef, {
            name: userData.name,
            email: userData.email,
            companyName: userData.companyName,
            companyPosition: userData.companyPosition,
            field: userData.field,
            url: userData.url,
            image: downloadURL,
 });
 });

    return {
        code: "auth/success",
        status: 200,
        user,
        message: "Acount created successfully! 🎉",
 };
};

The ID obtained from the user object is used to save the recruiter's image in Firebase Storage and to create a Firebase collection that includes the recruiter's attributes.

Create the following function to allow recruiters to sign into the application:

export const recruiterAuthLogin = async (form: FormData) => {
   const email = form.get("email") as string;
    const password = form.get("password") as string;

    const { user } = await signInWithEmailAndPassword(auth, email, password);

    if (!user) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Failed to login",
 };
 }

    const userRef = doc(db, "recruiters", user.uid);
    const docSnap = await getDoc(userRef);

    if (!docSnap.exists()) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "User Not a Recruiter",
 };
 }

    return {
        code: "auth/success",
        status: 200,
        user,
        message: "Login successful",
 };
};

The code snippet above validates the recruiter's credentials and checks if the user exists within the Firebase recruiters collection before signing the recruiter into the application.

Additionally, other functions include the authLogout and getJobSeekerData functions.

The authLogout function below allows both recruiters and job seekers to sign out of the application:

export const authLogout = async () => {
  try {
        await auth.signOut();
        return { code: "auth/success", status: 200, message: "Logout successful" };
 } catch (err) {
        return {
            code: "auth/failed",
            status: 500,
            message: "Failed to logout",
            err,
 };
 }
};

The getJobSeekerData function retrieves all the attributes related to a job seeker and can be executed on the jobseeker’s profile page.

export const getUserProfile = async (uid: string) => {
    const userRef = doc(db, "jobSeekers", uid);
    const docSnap = await getDoc(userRef);

    if (!docSnap.exists()) {
        return {
            code: "auth/failed",
            status: 500,
            user: null,
            message: "Invalid ID",
 };
 }

    return {
        code: "auth/success",
        status: 200,
        user: docSnap.data() as JobSeekerFirebase,
        message: "User found",
 };
}

Stream Chat Firebase Extension

In the previous sections, you learned how to authenticate users with Firebase. Stream also provides Firebase extensions that let you sync Firebase Authentication and Firestore with Stream. The Authenticate with Stream Chat extension automatically syncs Firebase users with Stream Chat, making it easier for Stream to manage your users.

Stream recommends using these Firebase extensions for easy integration and seamless communication between both platforms.

Alternatively, you can manually add users to Stream.

First, create an actions folder at the root of your Next.js project and add a stream.action.ts file:

mkdir actions && cd actions && \
touch stream.action.ts

Copy the following code into the file:

"use server";
import { StreamChat } from "stream-chat";
const STREAM_API_KEY = process.env.NEXT_PUBLIC_STREAM_API_KEY!;
const STREAM_API_SECRET = process.env.STREAM_SECRET_KEY!;

const serverClient = StreamChat.getInstance(STREAM_API_KEY, STREAM_API_SECRET);

export const createStreamUser = async (
    id: string,
    name: string,
    image: string
) => {
    const { users } = await serverClient.queryUsers({ id });
    if (users.length > 0) return users[0];

    const user = await serverClient.upsertUser({
        id,
        name,
        image,
 });

    return user;
};

The createStreamUser function takes a user ID, name, and image, checks if the user already exists in Stream, and adds them if they don’t. You can call this function right after a job seeker or recruiter logs into the app—inside jobSeekerAuthLogin and recruiterAuthLogin.

To connect your Firebase users to Stream, create a Stream app and add your API credentials to the .env.local file:

NEXT_PUBLIC_STREAM_API_KEY=<your_Stream_API_key>
STREAM_SECRET_KEY=<your_Stream_Secret_key>

Later in this tutorial, you'll learn about Stream's real-time chat and video calling features and discover how to integrate them into your application.

The Application Database Design

This section will teach you how to create Firestore Database collections and perform CRUD operations within the application.

Beyond the authentication pages, recruiters and job seekers have dedicated pages with specific functionalities.

Recruiter Page Routes

/dashboard – This is the recruiter's dashboard, where they can create job listings and view upcoming interview sessions.
/jobs – displays a list of jobs created by the recruiter, including the number of applicants. Recruiters can also delete a job if necessary.
/jobs/[id]/applicants – lists all applicants for a particular job along with their details, including profile links, downloadable CVs, cover letters, and notes to the employer. Each job in the /jobs route includes an applicant link that directs recruiters to the complete list of applicants and their information.

Job Seeker Page Routes

/[id] – displays the name, image, downloadable CV, and portfolio link for a job seeker.
/feed – shows job listings that match the job seeker’s interests or field (e.g., tech, consulting, etc.).
/jobs/[id] - displays the job description and a form that allows job seekers to apply.
/jobs/applied – enables job seekers to track the status of their applications, displaying a list of applied jobs and their respective statuses.

The table below outlines the attributes of the Firestore collections:

jobSeekers	recruiters	applications	jobs
name	name	coverLetter	jobTitle
email	email	jobID	jobDescription
image	image	note	expiryDate
cv	url	status	applications: [{ applicationId, userId }]
bio	field	user : { jobSeekers attributes }	recruiter: { recruiters attributes }
portfolioUrl	companyName
fieldOfInterest	companyPosition

From the table above:

The jobSeekers and recruiters collections store essential attributes for job seekers and recruiters, respectively.
The fieldOfInterest (for job seekers) and field (for recruiters) attributes help personalize job feeds by displaying only relevant job listings.
The applications collection contains a user object with all job seeker details. For larger applications, storing only the jobSeekerId is more efficient, allowing the system to fetch user details on demand.
The jobs collection includes an applications array that stores objects with applicationId and userId, representing submitted applications.
The jobs collection also contains a recruiter attribute that stores the whole recruiter object.

Database Operations for Recruiters

Recruiters can perform the following actions within the application:

Create job postings.
Delete a job posting using its ID.
Retrieve all jobs they have created.
View all applicants for a specific job, including their details.
Reject job applications.
Update the status of a job application.

Next, let's implement these functions. First, create a lib/db-functions.ts file inside the src folder of your Next.js project. Then, add the following imports at the top of the file:

import db from "./firebase";
import {
    addDoc,
    collection,
    deleteDoc,
    doc,
    getDocs,
    getDoc,
    where,
    query,
    updateDoc,
    arrayUnion,
    arrayRemove,
} from "firebase/firestore";

Copy the following code snippet into the file:

export const createJobPosting = async (
    form: FormData,
    user: RecruiterFirebase
) => {
    const jobTitle = form.get("jobTitle") as string;
    const jobDescription = form.get("jobDescription") as string;
    const expiryDate = form.get("expiryDate") as string;

    // 👇🏻 add the job to the listing
    const docRef = await addDoc(collection(db, "jobs"), {
        jobTitle,
        jobDescription,
        expiryDate: formatDate(expiryDate),
        applications: [],
 ...user,
 });

    if (!docRef.id) {
        return { code: "job/failed", status: 500, message: "Failed to create job" };
 }

    return {
        code: "job/success",
        status: 200,
        message: "Job created successfully",
 };
};

The createJobPosting function accepts a job title, description, expiry date, and the recruiter's user object as parameters. It then creates a new job listing in the database. This function is only available to the recruiters on their dashboard.

To delete a job, you can add a delete button on every job displayed to execute this function:

export const deleteJobPosting = async (doc_id: string) => {
    try {
        const docRef = doc(db, "jobs", doc_id);
        //👇🏻 gets the job via ID
        const docSnap = await getDoc(docRef);
        if (!docSnap.exists()) {
            return { code: "job/failed", status: 404, message: "Job does not exist" };
 }
        const { applications } = docSnap.data() as JobProps;
        //👇🏻 gets all its applicants and delete them
        for (const application of applications) {
            const applicationRef = doc(db, "applications", application.applicationId);
            await deleteDoc(applicationRef);
 }
        //👇🏻 delete the job
        await deleteDoc(doc(db, "jobs", doc_id));
        return {
          code: "job/success",
            status: 200,
            message: "Job deleted successfully",
 };
 } catch (error) {
        return {
            code: "job/failed",
            status: 500,
            message: "Failed to delete job",
            error,
 };
 }
};

The deleteJobPosting function first retrieves the job via its ID. If the job exists, it fetches all associated applications and deletes them before removing the job itself from the database. This ensures that no application in the database references a non-existent job.

You can get all recruiter posts by using their ID to search the jobs collection and return the job list.

export const getRecruiterJobs = async (recruiterId: string) => {
    const q = query(collection(db, "jobs"), where("id", "==", recruiterId));
    const querySnapshot = await getDocs(q);
    const jobs: JobProps[] = [];
    querySnapshot.forEach((doc) => {
        jobs.push({ doc_id: doc.id, ...doc.data() } as JobProps);
 });
    return jobs;
}

Recruiters need to review applications for a specific job, so you should create a database function that retrieves all applications for that job to help them make a decision.

export const getJobApplicants = async (jobId: string) => {
    const docRef = doc(db, "jobs", jobId);
    //👇🏻 get job data using its ID
    const docSnap = await getDoc(docRef);

    if (!docSnap.exists()) {
        return {
            code: "job/failed",
            status: 404,
            message: "Job does not exist",
            applicants: [],
 };
 }
    //👇🏻 retrieves the applications array
    const { applications } = docSnap.data() as JobProps;
    const applicants: ApplicationProps[] = [];
    //👇🏻 returns the entire application collections collection using the application ID
    for (const application of applications) {
        const applicationRef = doc(db, "applications", application.applicationId);
        const applicationSnap = await getDoc(applicationRef);
        if (applicationSnap.exists()) {
            applicants.push({
                id: application.applicationId,
 ...applicationSnap.data(),
 } as ApplicationProps);
 }
 }

    return {
        code: "job/success",
        status: 200,
        message: "Job applicants retrieved successfully",
        applicants,
 };
};

The getJobApplicants function accepts the job ID as a parameter, fetches the job data, and extracts the applications array. Since the applications array contains the document IDs of each application, the function retrieves all applications using these IDs.

Finally, recruiters can reject applications and update a job application's status using the following functions:

//👇🏻 reject applications
export const handleRejectApplication = async (
    application: ApplicationProps
) => {
    const applicationRef = doc(db, "applications", application.id);
    await deleteDoc(applicationRef);

    const jobRef = doc(db, "jobs", application.jobID);
    await updateDoc(jobRef, {
        applications: arrayRemove({
            applicationId: application.id,
            userId: application.user.id,
 }),
 });

    return {
        code: "job/success",
        status: 200,
        message: "Application rejected successfully",
 };
};

//👇🏻 update job status
export const updateJobStatus = async (
    applicationId: string,
    status: ApplicationProps["status"]
) => {
    const applicationRef = doc(db, "applications", applicationId);
    await updateDoc(applicationRef, { status });
    return {
        code: "job/success",
        status: 200,
        message: "Application status updated successfully",
 };
};

The handleRejectApplication function accepts the application Firebase document, extracts the job ID and application ID, and deletes the application using its ID. It then removes the applicant from the applications array in the jobs Firebase document, ensuring that the rejected application is fully removed from both collections.

The updateJobStatus function updates the status of a specific job application. This helps job seekers track their application status, whether pending or being reviewed. The function can be triggered when a recruiter chats with the job seeker or schedules an interview.

Database Operations for Job Seekers

Job seekers can perform the following key functions:

Browse available jobs: retrieve all job listings within their chosen field, ensuring that only jobs they haven't applied for are displayed.
View job details: fetch complete job details, including the job description, company name, and other relevant information, using the job ID. This page also provides a form to allow job seekers to apply after reviewing the requirements.
Track applications: view a list of jobs they have applied for and monitor their application status.

To display job listings on the job seeker's feed, use the following code snippet:

export const getJobFeed = async (user: JobSeekerFirebase) => {
    //👇🏻 query jobs matching the user's field of interest
    const q = query(
        collection(db, "jobs"),
        where("field", "==", user.fieldOfInterest)
 );
    const querySnapshot = await getDocs(q);
    const jobs: JobProps[] = [];
    //👇🏻 retreieve only jobs that the user hasn't apply for
    querySnapshot.forEach((doc) => {
        const data = { doc_id: doc.id, ...doc.data() } as JobProps;
        if (data.applications.some((application) => application.userId === user.id))
            return;
        jobs.push(data);
 });

    return jobs;
};

The getJobFeed function takes a job seeker's user object as a parameter and returns job listings that match their field of interest and have not been applied for. This ensures they only see relevant opportunities.

To retrieve a job by its ID and allow job seekers to view its full details, use the following code snippet:

export const getJobById = async (doc_id: string) => {
    const docRef = doc(db, "jobs", doc_id);
    const docSnap = await getDoc(docRef);
    if (docSnap.exists()) {
      return { doc_id, ...docSnap.data() } as JobProps;
 } else {
        return null;
 }
};

Next, you need to allow job seekers to apply for jobs.

export const applyForJob = async (
    jobID: string,
    user: JobSeekerFirebase,
    coverLetter: string,
    note: string
) => {
    ///👇🏻 gets job document reference
    const jobRef = doc(db, "jobs", jobID);
    const jobSnap = await getDoc(jobRef);

    if (!jobSnap.exists()) {
        return { code: "job/failed", status: 404, message: "Job does not exist" };
 }

    const job = jobSnap.data() as JobProps;
    //👇🏻 checks if user already applied
    const alreadyApplied = job.applications.find(
 (application) => application.userId === user.id
 );

    if (alreadyApplied) {
        return {
            code: "job/failed",
            status: 400,
            message: "You have already applied for this job",
 };
 }
    //👇🏻 save job seeker's application
    const addResult = await addDoc(collection(db, "applications"), {
        jobID,
        user,
        coverLetter,
        note,
        status: "Pending",
     });

    if (!addResult.id) {
        return {
            code: "job/failed",
            status: 500,
            message: "Failed to submit application",
 };
 }
    //👇🏻 update the job applications with the new application
    await updateDoc(jobRef, {
        applications: arrayUnion({ applicationId: addResult.id, userId: user.id }),
 });

    return {
        code: "job/success",
        status: 200,
        message: "Application submitted successfully",
 };
};

The applyForJob function:

accepts the job ID, job seeker user object, cover letter, and note to the employer as parameters.
fetches the job document from Firestore and checks if the job exists.
ensures that the user has not already applied.
saves the job application to the Firestore application collection.
updates the job document with the new application.

Finally, you can retrieve all the jobs the user has applied for, including their status.

export const getJobsUserAppliedFor = async (userId: string) => {
    //👇 Fetch all applications for the user
    const q = query(
        collection(db, "applications"),
        where("user.id", "==", userId)
 );
    const querySnapshot = await getDocs(q);
    const applications: ApplicationProps[] = querySnapshot.docs.map((doc) => ({
        id: doc.id,
 ...doc.data(),
})) as ApplicationProps[];

    if (applications.length === 0) return []; // Return empty array if no applications exist

    //👇 Fetch all job documents in a single batch request
    const jobIds = applications.map((app) => doc(db, "jobs", app.jobID));
    const jobSnaps = await getDocs(query(collection(db, "jobs"), where("__name__", "in", jobIds.map((job) => job.id))));

    const jobs: JobProps[] = jobSnaps.docs.map((doc) => {
        const application = applications.find((app) => app.jobID === doc.id);
        return {
            doc_id: doc.id,
 ...doc.data(),
            status: application?.status || "Unknown", // Ensure status is included
 } as JobProps;
 });

    return jobs;
};

The getJobsUserAppliedFor function fetches all job applications for a given user, retrieves the corresponding job details in a batch query, and associates each job with its application status. If no applications exist, it returns an empty array.

How to Integrate the Private Chat Feature with Stream

In this section, you'll learn how to create private channels and send messages to users within the application, enabling recruiters to chat with shortlisted candidates.

Before we proceed, install the following Stream packages to integrate chat and video call features into the application.

// 👇🏻 for Stream Chat SDK 
npm install stream-chat stream-chat-react 
//👇🏻 for Stream Video & Audio SDK 
npm install @stream-io/node-sdk @stream-io/video-react-sdk

Setting Up the Stream Chat SDK in Next.js

Create a Stream account and a new organization that holds all your apps.

Add a new app to the organization and copy the Stream API and Secret key into the .env.local file.

NEXT_PUBLIC_STREAM_API_KEY=<paste_from_Stream_app_dashboard>
STREAM_SECRET_KEY=<paste_from_Stream_app_dashboard>

Within the actions/stream.action.ts file created earlier, copy the following code snippet into the file:

"use server";
import { StreamChat } from "stream-chat";
import { StreamClient } from "@stream-io/node-sdk";
const STREAM_API_KEY = process.env.NEXT_PUBLIC_STREAM_API_KEY!;
const STREAM_API_SECRET = process.env.STREAM_SECRET_KEY!;

// 👇🏻 -- Stream server client  --
const serverClient = StreamChat.getInstance(STREAM_API_KEY, STREAM_API_SECRET);

//👇🏻 -- create auth token function
export async function createToken(
    user: RecruiterFirebase | JobSeekerFirebase
): Promise<string> {
    if (!user) throw new Error("User is not authenticated");
    return serverClient.createToken(user.id);
}

The code snippet above initializes the Stream Chat server client, allowing us to perform various Stream actions on the server side. The createToken function accepts a user object (either a recruiter or job seeker) and creates an authentication token using the user's ID.

Since Firebase works on the client side, we also need a Stream client to perform actions such as fetching upcoming calls and channels, and creating and joining them.

To achieve this, create a hooks folder in your project and add a useGetStreamClient custom hook within a (stream) folder in your Next.js app. This hook will manage the client-side Stream functionality.

cd app && mkdir (stream) && \ 
cd (stream) && mkdir hooks && cd hooks && \
touch useGetStreamClient.ts

Copy the following code snippet into the useGetStreamClient.ts:

import { useCreateChatClient } from "stream-chat-react";
import { createToken } from "../../../../actions/stream.action";
import { useCallback } from "react";

export const useGetStreamClient = (
    user: JobSeekerFirebase | RecruiterFirebase
    ) => {
    //👇🏻 executes the createToken function from the server
    const tokenProvider = useCallback(async () => {
        return await createToken(user);
 }, [user]);

    //👇🏻 creates the chat client
    const client = useCreateChatClient({
        apiKey: process.env.NEXT_PUBLIC_STREAM_API_KEY!,
        tokenOrProvider: tokenProvider,
        userData: { id: user.id, name: user.name, image: user.image },
 });
    //👇🏻 returns the chat client
    if (!client) return { client: null };

    return { client };
};

Private Chat with the Stream Chat SDK

In this section, you will learn how to create private chat channels using the Stream Chat SDK to enable recruiters to send messages to shortlisted job applicants. The chat channels allow recruiters to ask additional questions or interact with the applicant before and after the interview.

Copy the code snippet below into the stream.action.ts file:

export async function createChannel({
    recruiterId,
    applicant,
}: {
    recruiterId: string;
    applicant: ApplicationProps;
}) {
    try {
        const filter = {
            type: "messaging",
            members: { $in: [recruiterId, applicant.user.id] },
 };
  const sort = [{ last_message_at: -1 }];
        //👇🏻 check if job applicant already has a channel with the recruiter
        const channels = await serverClient.queryChannels(filter, sort, {
            watch: true,
            state: true,
 });
        //👇🏻 if true, return the channel id
        if (channels.length > 0) {
            return { success: true, error: null, id: channels[0].id };
 }
        //👇🏻 otherwise, create a new channel for them
        const channel = serverClient.channel(
            "messaging",
            `${applicant.jobID}-chat-${applicant.user.id}`,
 {
                name: `Meeting with ${applicant.user.name}`,
                members: [recruiterId, applicant.user.id],
                created_by_id: recruiterId,
 }
 );
        await channel.create();
        //👇🏻 return the channel id
        return { success: true, error: null, id: channel.id };
 } catch (err) {
        console.log("Error creating channel:", err);
        return { success: false, error: "Failed to create channel", id: null };
 }
}

The createChannel function checks if a chat channel already exists between the recruiter and the job applicant. If such a channel exists, it returns the existing channel's ID. If not, the function creates a new channel and returns the channel ID. This allows recruiters and job applicants to visit the chat page via the /chat/[id] route.

Now, let's build the UI components for the chat page.

Create a chat/[id]/page.tsx file and copy the following code into the file:

"use client";
import StreamChatUI from "../components/StreamChatUI";
import { useState, useEffect, useCallback } from "react";
import { onAuthStateChanged, User } from "firebase/auth";
import { doc, getDoc } from "firebase/firestore";
import { useRouter } from "next/navigation";
import { Loader2 } from "lucide-react";
import { auth } from "@/lib/firebase";
import db from "@/lib/firebase";

export default function ChatPage() {
    //👇🏻 Firebase User object
    const [user, setUser] = useState<User | null>(null);
    //👇🏻 Firestore user collection states
    const [userData, setUserData] = useState<
        JobSeekerFirebase | RecruiterFirebase | null
    >(null);
    const router = useRouter();

    //👉🏻 auth verification functions

    return (
 <div>{userData ? <StreamChatUI user={userData} /> : <ConfirmMember />}</div>
 );
}

const ConfirmMember = () => {
    const router = useRouter();
    return (
 <div className='flex flex-col items-center justify-center h-screen'>
 <button
                className='text-lg mb-4 p-4 bg-blue-500 text-white rounded-md'
                onClick={() => router.back()}
 >
 Go Back
 </button>

 <div className='loader'>
 <Loader2 size={48} className='animate-spin' />
 </div>
 </div>
 );
};

The ChatPage component conditionally renders either the StreamChatUI component or the ConfirmMember component. The ConfirmMember component acts as a loading page and is displayed until the userData value is available.

Next, add the following authentication functions within the ChatPage component:

//👇🏻 check if the user is authenticated and save its Firebase user object
useEffect(() => {
    const unsubscribe = onAuthStateChanged(auth, async (user) => {
        if (user?.uid) {
            setUser(user);
 } else {
            return router.push("/applicant/login");
 }
 });

    return () => unsubscribe();
}, [router]);

//👇🏻 retrieve user's collection
const getUser = useCallback(async () => {
    if (!user) return null;
    const jobSeekerSnap = await getDoc(doc(db, "jobSeekers", user.uid));
    const recruiterSnap = await getDoc(doc(db, "recruiters", user.uid));

    if (jobSeekerSnap.exists()) {
        setUserData({
            id: user.uid,
 ...jobSeekerSnap.data(),
 } as JobSeekerFirebase);
 } else if (recruiterSnap.exists()) {
        setUserData({
            id: user.uid,
 ...recruiterSnap.data(),
 } as JobSeekerFirebase);
 } else {
        return null;
 }
}, [user]);

useEffect(() => {
    getUser();
}, [getUser]);

The code snippet above retrieves the user's Firebase collection when the page loads before passing the userData React state into the StreamChatUI component.

Copy the following code snippet into StreamChatUI component:

"use client";
import {
    Chat,
    Channel,
    ChannelList,
    Window,
    ChannelHeader,
    MessageList,
    MessageInput,
} from "stream-chat-react";
import { useGetStreamClient } from "../../hooks/useGetStreamClient";

export default function StreamChatUI({
    user,
}: {
    user: JobSeekerFirebase | RecruiterFirebase;
}) {
    //👇🏻 retrieves the chat client
    const { client } = useGetStreamClient(user!);

    //👇🏻 filter and sorting objects
    const filters = { members: { $in: [user.id] }, type: "messaging" };
    const options = { presence: true, state: true };

    if (!client) return <div>Loading...</div>;

    return (
 <Chat client={client}>
 <div className='chat-container'>
                {/* -- Channel List -- */}
 <div className='channel-list'>
 <ChannelList
                        sort={{ last_message_at: -1 }}
                        filters={filters}
                        options={options}
 />
 </div>
      {/* -- Messages Panel -- */}
 <div className='chat-panel'>
 <Channel>
 <Window>
 <ChannelHeader />
 <MessageList />
 <MessageInput />
 </Window>
 </Channel>
 </div>
 </div>
 </Chat>
 );
}

From the code snippet above:

The useGetStreamClient custom hook returns the chat client.
Chat component initializes the Stream Chat client and wraps the entire Chat page.
ChannelList shows available chat channels.
Channel sets up an active chat session.
Window contains the message display and input areas.
ChannelHeader, MessageList, and MessageInput provide a fully functional chat interface.

How to Schedule Virtual Interviews with Stream

In this section, you'll learn how to integrate video calling functionality into the Next.js application, allowing recruiters to schedule and conduct virtual interviews with job seekers.

Copy the following code snippet into the actions/stream.action.ts file:

export const tokenProvider = async (user_id: string) => {
    if (!STREAM_API_KEY) throw new Error("Stream API key secret is missing");
    if (!STREAM_API_SECRET) throw new Error("Stream API secret is missing");

    const streamClient = new StreamClient(STREAM_API_KEY, STREAM_API_SECRET);

    const expirationTime = Math.floor(Date.now() / 1000) + 3600;
    const issuedAt = Math.floor(Date.now() / 1000) - 60;
    const token = streamClient.generateUserToken({
        user_id,
        exp: expirationTime,
        validity_in_seconds: issuedAt,
 });

    return token;
}

The tokenProvider function generates an authentication token for the user, enabling Stream to identify and manage users during real-time communication.

Within the (stream)/hooks folder, add the following files:

cd app && cd (stream)/hooks && \
touch useGetCallById.ts useGetCalls.ts

The useGetCallById file defines a React hook that fetches details of a specific Stream call via its ID while the useGetCalls hook retrieves all the calls created by a particular Stream user.

Let's create these custom React hooks.

Copy the following code snippet into the useGetCallById.ts file:

import { useEffect, useState } from "react";
import { Call, useStreamVideoClient } from "@stream-io/video-react-sdk";

export const useGetCallById = (id: string | string[]) => {
    const [call, setCall] = useState<Call>();
    const [isCallLoading, setIsCallLoading] = useState(true);

    const client = useStreamVideoClient();

    useEffect(() => {
        if (!client) return;

        const loadCall = async () => {
            try {
                // https://getstream.io/video/docs/react/guides/querying-calls/#filters
                const { calls } = await client.queryCalls({
        filter_conditions: { id },
 });

                if (calls.length > 0) setCall(calls[0]);

                setIsCallLoading(false);
 } catch (error) {
                console.error(error);
                setIsCallLoading(false);
 }
 };

        loadCall();
 }, [client, id]);

    return { call, isCallLoading };
};

Add the following to the useGetCalls.ts file:

import { useEffect, useState } from "react";
import { Call, useStreamVideoClient } from "@stream-io/video-react-sdk";

export const useGetCalls = (id: string) => {
    const client = useStreamVideoClient();
    const [calls, setCalls] = useState<Call[]>();
    const [isLoading, setIsLoading] = useState(false);

    useEffect(() => {
        const loadCalls = async () => {
            if (!client || !id) return;

            setIsLoading(true);

            try {
                const { calls } = await client.queryCalls({
                    sort: [{ field: "starts_at", direction: 1 }],
                    filter_conditions: {
                        starts_at: { $exists: true },
                        $or: [{ created_by_user_id: id }, { members: { $in: [id] } }],
 },
 });
   setCalls(calls);
 } catch (error) {
                console.error(error);
 } finally {
                setIsLoading(false);
 }
 };

        loadCalls();
 }, [client, id]);

    const now = new Date();

    const upcomingCalls = calls?.filter(({ state: { startsAt } }: Call) => {
        return startsAt && new Date(startsAt) > now;
 });

    const ongoingCalls = calls?.filter(
 ({ state: { startsAt, endedAt } }: Call) => {
            return startsAt && new Date(startsAt) < now && !endedAt;
 }
 );

    return { upcomingCalls, isLoading, ongoingCalls };
};

Next, to create, join, and retrieve calls, wrap the pages that require access to the calls with the StreamVideo component.

Add a providers/StreamVideoProvider component inside the (stream) folder to do this. Then, copy the following code snippet into the file:

"use client";
import { tokenProvider } from "../../../../actions/stream.action";
import { StreamVideo, StreamVideoClient } from "@stream-io/video-react-sdk";
import { useState, ReactNode, useEffect, useCallback } from "react";
import { onAuthStateChanged, User } from "firebase/auth";
import { auth } from "@/lib/firebase";
import db from "@/lib/firebase";
import { doc, getDoc } from "firebase/firestore";
import { useRouter } from "next/navigation";
import { Loader2 } from "lucide-react";

const apiKey = process.env.NEXT_PUBLIC_STREAM_API_KEY!;

export const StreamVideoProvider = ({ children }: { children: ReactNode }) => {
    const [videoClient, setVideoClient] = useState<StreamVideoClient | null>(
        null
 );

    const [user, setUser] = useState<User | null>(null);
    const router = useRouter();

    // 👉🏻 auth functions placeholder

    return <StreamVideo client={videoClient}>{children}</StreamVideo>;
};

Update the component with the authentication functions:

//👇🏻 get the Firebase user object
useEffect(() => {
    const unsubscribe = onAuthStateChanged(auth, async (user) => {
        if (user?.uid) {
            setUser(user);
 } else {
            return router.push("/applicant/login");
 }
 });

    return () => unsubscribe();
}, [router]);

//👇🏻 get the Firebase user collection and returns the Stream video client
const getUser = useCallback(async () => {
    if (!user) return null;

    const [jobSeekerSnap, recruiterSnap] = await Promise.all([
        getDoc(doc(db, "jobSeekers", user.uid)),
        getDoc(doc(db, "recruiters", user.uid)),
 ]);

    if (!jobSeekerSnap.exists() && !recruiterSnap.exists()) {
        console.warn("User data not found in Firestore");
        return null;
 }

    return new StreamVideoClient({
        apiKey,
        user: {
            id: user.uid,
            name: jobSeekerSnap.data()?.name || recruiterSnap.data()?.name,
            image: jobSeekerSnap.data()?.image || recruiterSnap.data()?.image,
 },
        tokenProvider: () => tokenProvider(user.uid),
 });
}, [user]);

//👇🏻 update the video client

useEffect(() => {
    const result = getUser();
    if (result) {
        result.then((client) => setVideoClient(client));
 }
}, [getUser]);

if (!videoClient)
    return (
 <div className='h-screen flex items-center justify-center'>
 <Loader2 size='32' className='mx-auto animate-spin' />
 </div>
 );

The code snippet above does the following:

retrieves the authenticated Firebase user object and redirects them to the login page if they are not signed in.
fetches the user's data from the jobSeekers or recruiters Firestore collection and initializes a StreamVideoClient with their details.
updates the videoClient state once the user data is retrieved, displaying a loading spinner while waiting for the client to be set.

Finally, recruiters need to be able to schedule calls with shortlisted applicants. They can execute this function after submitting a form that accepts the meeting title and a specific date and time for the interview.

import { useStreamVideoClient } from "@stream-io/video-react-sdk";
const client = useStreamVideoClient();

const handleScheduleMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    if (!description || !dateTime || !client) return;

    try {
        const id = crypto.randomUUID(); //👉🏻 generates a random id
        const call = client.call("default", id);
        if (!call) throw new Error("Failed to create meeting");
        // 👇🏻 creates a call
        await call.getOrCreate({
            data: {
                starts_at: new Date(dateTime).toISOString(),
                custom: {
                    description,
 },
                members: [{ user_id: applicantId }, { user_id: recruiterId }],
 },
 });
 } catch (error) {
        console.error(error);
 }
};

The code snippet above creates a Stream video call with a default call type. It assigns the call a unique ID, sets the scheduled date and time, and includes a custom description.

Ensure that the <StreamVideoProvider> component wraps the recruiter's dashboard where the video call is created. You can achieve this by adding a layout.tsx file to the dashboard page and wrapping all child elements with <StreamVideoProvider>.

Stream Call UI Components

Here, you will learn how to create the interview page, where the recruiter and the applicant can communicate via video call, share screens, and seamlessly meet.

First, create an interview/[id]/page.tsx file within the (stream) folder and add the following imports to the file:

"use client";
import { useGetCallById } from "../../hooks/useGetCallById";
import {
    StreamCall,
    StreamTheme,
    PaginatedGridLayout,
    SpeakerLayout,
    CallControls,
    Call,
} from "@stream-io/video-react-sdk";
import { useParams } from "next/navigation";
import { useEffect, useState, useCallback } from "react";
import { useRouter } from "next/navigation";
import { useCallStateHooks } from "@stream-io/video-react-sdk";
import { toast } from "sonner";
import { auth } from "@/lib/firebase";
import { User, onAuthStateChanged } from "firebase/auth";

type CallLayoutType = "grid" | "speaker-left" | "speaker-right";

Copy the following code snippet into the file to ensure the user is authenticated before rendering the call component.

export default function CallPage() {
    const { id } = useParams<{ id: string }>();
    const { call, isCallLoading } = useGetCallById(id);
    const [confirmJoin, setConfirmJoin] = useState<boolean>(false);
    const [camMicEnabled, setCamMicEnabled] = useState<boolean>(false);
    const [user, setUser] = useState<User | null>(null);
    const router = useRouter();

    const authenticateUser = useCallback(async () => {
        const unsubscribe = onAuthStateChanged(auth, async (user) => {
            if (!user?.uid) {
                return router.push("/applicant/login");
     }
            setUser(user);

            if (camMicEnabled) {
                call?.camera.enable();
                call?.microphone.enable();
 } else {
                call?.camera.disable();
                call?.microphone.disable();
 }
 });

        return () => unsubscribe();
 }, [router, call, camMicEnabled]);

    useEffect(() => {
        authenticateUser();
 }, [authenticateUser]);

    const handleJoin = () => {
        call?.join();
        setConfirmJoin(true);
 };

    if (isCallLoading) return <p>Loading...</p>;

    if (!call) return <p>Call not found</p>;

    return (
        // --- Call UI component ---
 )
}

The authenticateUser function checks if a user is logged in; if not, it redirects them to the login page. If authentication is successful, it enables or disables the user's camera and microphone based on the camMicEnabled state. The handleJoin function allows users to join the call when they confirm participation.

Return the following UI elements from the CallPage component:

return (
 <main className='min-h-screen w-full items-center justify-center'>
 <StreamCall call={call}>
 <StreamTheme>
                {confirmJoin ? (
 <MeetingRoom call={call} />
 ) : (
 <div className='flex flex-col items-center justify-center gap-5 h-screen w-full'>
 <h1 className='text-3xl font-bold'>Join Call</h1>
 <p className='text-lg'>Are you sure you want to join this call?</p>
 <div className='flex gap-5'>
 <button
                                onClick={handleJoin}
                                className='px-4 py-3 bg-blue-600 text-blue-50'
 >
 Join
 </button>
 <button
                                onClick={() => router.back()}
                                className='px-4 py-3 bg-red-600 text-red-50'
 >
 Cancel
 </button>
 </div>
 </div>
 )}
 </StreamTheme>
 </StreamCall>
 </main>
)

The component displays a confirmation page where the participant can confirm their decision before joining the interview or call session.

In the code snippet above,

The StreamCall component wraps the entire call page, allowing access to various audio and video calling features. It accepts the call object as a prop.
The StreamTheme component provides UI styling for the call, enabling you to use different themes.
The confirmJoin state is initially set to false. When the user clicks the Join button, it triggers the handleJoin function, which joins the call and updates confirmJoin to true.
When confirmJoin is true, the component renders the MeetingRoom component, which includes all prebuilt and customizable UI elements for the call provided by Stream.

Add the MeetingRoom component to the interview/[id]/page.tsx file:

const MeetingRoom = ({ call }: { call: Call }) => {
    const [layout, setLayout] = useState<CallLayoutType>("grid");
    const router = useRouter();

    const handleLeave = () => {
        if (confirm("Are you sure you want to leave the call?")) {
            router.push("/");
 }
 };

    const CallLayout = () => {
        switch (layout) {
            case "grid":
                return <PaginatedGridLayout />;
            case "speaker-right":
                return <SpeakerLayout participantsBarPosition='left' />;
            default:
                return <SpeakerLayout participantsBarPosition='right' />;
 }
 };

    return (
 <section className='relative min-h-screen w-full overflow-hidden pt-4'>
 <div className='relative flex size-full items-center justify-center'>
 <div className='flex size-full max-w-[1000px] items-center'>
 <CallLayout />
 </div>
 <div className='fixed bottom-0 flex w-full items-center justify-center gap-5'>
 <CallControls onLeave={handleLeave} />
 </div>

 <div className='fixed bottom-0 right-0 flex items-center justify-center gap-5 p-5'>
 <EndCallButton call={call} />
 </div>
 </div>
 </section>
 );
};

Finally, create the EndCallButton component to enable the host (instructor) to end the call for everyone.

const EndCallButton = ({ call }: { call: Call }) => {
    const { useLocalParticipant } = useCallStateHooks();
    const localParticipant = useLocalParticipant();
    const router = useRouter();

    const participantIsHost =
        localParticipant &&
        call.state.createdBy &&
        localParticipant.userId === call.state.createdBy.id;

    if (!participantIsHost) return null;

    const handleEndCall = () => {
        call.endCall();
        toast("Call ended for everyone", {
            description: "The call has been ended for everyone",
 });
        router.push("/");
 };

    return (
 <button
            className='bg-red-500 text-white px-4 py-2 rounded-md mt-2'
            onClick={handleEndCall}
 >
 End Call for Everyone
 </button>
 );
};

The code snippet above ensures that only the call host can end the call for all participants. It first checks if the current user is the host before displaying the "End Call for Everyone" button.

Congratulations! You’ve completed the project for this tutorial. The source code for this article is also available on GitHub.

Next Steps

So far, you've learned how to build a full-stack job application and interview platform using Stream and Firebase. This platform allows recruiters to shortlist applicants, schedule virtual interviews, and communicate through real-time chat powered by Stream.

Stream helps you build engaging apps that scale to millions with performant and flexible Chat, Video, Voice, Feeds, and Moderation APIs and SDKs powered by a global edge network and enterprise-grade infrastructure.

Here are some valuable resources to help you get started:

Thank you for reading. 🎉

How to Scrape Websites in Python using Scrapy

David Asaolu — Mon, 13 Jan 2025 09:13:35 +0000

TL;DR

Web scraping helps you collect and organize data from websites. It is a great way to spot trends, gather insights, and make informed decisions. When done correctly, it can be a powerful tool for everything from research to business strategy.

In this tutorial, you will learn how to scrape data efficiently from websites in Python using Scrapy - an efficient data scraping tool that can act as a general purpose web crawler.

Prerequisites

Before we begin, you should have a basic understanding of Python. You'll also need to set up a few tools on your computer:

Python: Make sure Python (version 3.x.x or later) is installed.
A code editor: We'll use PyCharm, but you can use any Python-friendly editor.
Pip: Python's package manager for installing libraries.

To check if Python and Pip are installed, run these commands in your terminal:

python3 --version
pip3 --version

What is Scrapy?

Scrapy is a powerful framework designed for extracting data from websites. It helps you collect and organize structured data for tasks like data analysis, mining insights, or even archiving information.

While Scrapy is primarily built for web scraping, it can also handle tasks like extracting data from APIs or serving as a general-purpose web crawler.

How to create a new Scrapy project

In this section, I'll guide you through installing Scrapy, setting up a Scrapy project, and understanding the essential files and folders needed to scrape data effectively.

First, create a new pure Python project in PyCharm. It automatically activates a virtual environment for the project.

Run the following command in the terminal to install Scrapy within the virtual environment.

pip3 install scrapy

Create a new Scrapy project by running the code snippet below:

scrapy startproject <project_name>

For example:

scrapy startproject test_scrapy

This command generates a new Scrapy project with the following file structure:

test_scrapy  
├── spiders         # Contains the spiders you create for scraping websites  
│   └── __init__.py # Initializes the spiders folder  
├── __init__.py     # Initializes the project as a package  
├── items.py        # Define the structure of the data you want to scrape  
├── middlewares.py  # Customize how Scrapy processes requests and responses  
├── pipelines.py    # Process scraped data (e.g., cleaning or saving it)  
├── settings.py     # Configure your Scrapy project settings

The following explains the files and folder within the Scrapy project:

spiders (folder): This is where you define your web crawlers, called spiders. Each spider targets specific websites to scrape.
items.py: It defines the structure (or schema) of the data you want to extract.
middlewares.py: This allows you to customize how requests and responses are processed during scraping.
pipelines.py: This file cleans, validates, or saves the scraped data to storage systems like databases or files.
settings.py: This file configures your project, including user-agent strings, timeouts, and other settings to control the scraping behaviour.

How to scrape data from web pages using Scrapy

In this section, you'll learn how to scrape a single and multi-page websites using Scrapy. Therefore, we'll create two spiders that scrape each website effectively using the pages available at Scrape This Site.

Single Page Web Scraping Example

In this section, I'll walk you through scraping all the countries data on this webpage:

Create a new spider within the spiders folder using the following code snippet:

scrapy genspider countryspider scrapethissite.com

The code snippet above creates a countryspider.py file within the spiders folder.

The countryspider.py file contains the following code snippet:

import scrapy

class CountryspiderSpider(scrapy.Spider):
    name = "countryspider"
    allowed_domains = ["scrapethissite.com"]
    start_urls = ["https://scrapethissite.com"]

    def parse(self, response):
        pass

This code defines the Countryspider class - a spider designed to scrape data from websites. Here's what each part does:

name: The unique name of the spider, used when running it from the command line.
allowed_domains: Specifies the domains the spider is allowed to scrape, preventing it from accessing other websites.
start_urls: The initial URL where the spider will begin scraping.
parse() function: A placeholder function where all the web scraping logic will be written. This function processes the data extracted from the target website.

Next, let's update the parse function and scrape the webpage. Before we procee, update the start_url attribute to the exact webpage url to be scraped:

import scrapy

class CountryspiderSpider(scrapy.Spider):
    name = "countryspider"
    allowed_domains = ["scrapethissite.com"]
    start_urls = ["https://www.scrapethissite.com/pages/simple/"]

    def parse(self, response):
        pass

Next, let's scrape the webpage and identify the correct HTML elements to extract data from. Start by running the following commands in your terminal:

scrapy shell
fetch("https://www.scrapethissite.com/pages/simple/")

The scrapy shell command opens an interactive shell where you can experiment with scraping various data from the website. You can use the shell together with the browser's inspect tab to try out different elements you need to scrape from the website.

The fetch command retrieves all the webpage's data and stores it in a response variable for further analysis.

After identifying the necessary HTML attributes for scraping, you can use XPath or CSS selectors to extract the data.

Next, update the parse function within the Countryspider class as shown below:

import scrapy

class CountryspiderSpider(scrapy.Spider):
    name = "countryspider"
    allowed_domains = ["scrapethissite.com"]
    start_urls = ["https://www.scrapethissite.com/pages/simple/"]

    def parse(self, response):
        # contains a list of all the country names
        country_names = response.xpath("//h3[@class='country-name']/i/following-sibling::text()").getall()
        container = response.css("div.country")
        # removes the extra new line spacing in the text
        countries = [name.strip() for name in country_names]
        # loops through all the data on the page and returns an object containing the specified data
        for name, country_data  in zip(countries, container):
            yield {
                'country_name': name,
                'country_capital': country_data.css('div.country-info>span.country-capital::text').get(),
                'country_population': country_data.css('div.country-info>span.country-population::text').get(),
                'country_area' : country_data.css('div.country-info>span.country-area::text').get(),
           }

Finally, run the following code snippet to scrape the website, extract the needed data, and save them in a JSON file:

scrapy crawl countryspider -O countries.json

Multi-page Web Scraping Example

Here, you'll learn how to scrape multiple pages using Scrapy by crawling the Scrape This Site: Hockey Team Example.

Add a new spider within the spiders folder using the following code snippet:

scrapy genspider hockeyspider scrapethissite.com

Update the start_urls attribute within the hockeyspider.py file, as shown below:

import scrapy

class HockeyspiderSpider(scrapy.Spider):
    name = "hockeyspider"
    allowed_domains = ["scrapethissite.com"]
    #👇🏻 update the value of the start_urls
    start_urls = ["https://www.scrapethissite.com/pages/forms/?per_page=100"]

    def parse(self, response):
        pass

Run the following code snippet and extract the data within the tables using the XPath or CSS selectors.

scrapy shell
fetch("https://www.scrapethissite.com/pages/simple/")

Before scraping the web pages, define the data structure in the items.py file. The following code represents the data attributes we’ll be extracting from the web pages:

class HockeyItem(scrapy.Item):
    name = scrapy.Field()
    year = scrapy.Field()
    wins = scrapy.Field()
    losses = scrapy.Field()
    percent_win = scrapy.Field()
    goals_for = scrapy.Field()
    goals_against = scrapy.Field()
    diffs = scrapy.Field()

Next, update the hockeyspider.py file to include the newly defined HockeyItem class:

import scrapy

# import the HockeyItem class
from ..items import HockeyItem

# function that removes the extra spacing
def stripdata(data):
    return [dt.strip() for dt in data]

class HockeyspiderSpider(scrapy.Spider):
    name = "hockeyspider"
    allowed_domains = ["scrapethissite.com"]
    start_urls = ["https://www.scrapethissite.com/pages/forms/?per_page=100"]

    def parse(self, response):
        pass

Update the parse function to retrieve all the data from the table and return them using the HockeyItem class:

    def parse(self, response):
        raw_team_names = response.css("td.name::text").getall()
        raw_team_years = response.css("td.year::text").getall()
        raw_team_wins = response.css("td.wins::text").getall()
        raw_team_losses = response.css("td.losses::text").getall()
        raw_percent_win = response.css("td.pct::text").getall()
        raw_goals_for = response.css("td.gf::text").getall()
        raw_goals_against = response.css("td.ga::text").getall()
        raw_diffs = response.css("td.diff::text").getall()

        team_names = stripdata(raw_team_names)
        team_years = stripdata(raw_team_years)
        team_wins = stripdata(raw_team_wins)
        team_losses = stripdata(raw_team_losses)
        team_percent_win = stripdata(raw_percent_win)
        team_goals_for = stripdata(raw_goals_for)
        team_goals_against = stripdata(raw_goals_against)
        team_diffs = stripdata(raw_diffs)
        hockey_item = HockeyItem()

        for name, year, wins, losses, percent_win, goals_for, goals_against, diffs \
            in zip(team_names, team_years, team_wins, team_losses, team_percent_win, team_goals_for, team_goals_against, team_diffs):
            hockey_item['name'] = name
            hockey_item['year'] = year
            hockey_item['wins'] = wins
            hockey_item['losses'] = losses
            hockey_item['percent_win'] = percent_win
            hockey_item['goals_for'] = goals_for
            hockey_item['goals_against'] = goals_against
            hockey_item['diffs'] = diffs
            yield hockey_item

The code snippet above only crawls the first page and retrieves all the item from the first page.

To scrape multiple pages, we need to modify the parse function to follow the Next button and continue scraping until it reach the last page:

def parse(self, response):
##... Existing code
    for name, year, wins, losses, percent_win, goals_for, goals_against, diffs \
    #... Existing code
        yield hockey_item
    # Follow the next page if available
    next_page = response.css("ul.pagination > li:last-child a::attr(href)").get()
    if next_page:
        yield response.follow(next_page, callback=self.parse)

The next_page variable captures the URL for the next page by extracting the link from the pagination element. The response.follow() function then tells Scrapy to follow that link and continue scraping the next page.

Finally, run the following command in your terminal to crawl the webpages and save the data in a CSV file:

scrapy crawl hockeyspider -O hockey.csv

Scrapy supports several formats for output, including JSON, JSONL, CSV, XML, Marshal, and Pickle.

You’ve completed a hands-on guide to web scraping using Scrapy.

If you'll love to see Scrapy in action, check out this tutorial:

Next Steps

So far, you've learnt how to scrape a single and multiple pages using Scrapy. However, Scrapy offers many more powerful features to help you build advanced web scraping projects. Here are some resources to guide you:

Thank you for reading! 🥳

Writer's Corner

Hi, I am open to freelance technical writing gigs and remote opportunities. Let's work together. 📧: asaoludavid234 at gmail dot com

Feel free to connect with me on X and LinkedIn

Build a clone of Perplexity with LangGraph, CopilotKit, Tavily & Next.js 🪄

David Asaolu — Wed, 08 Jan 2025 14:19:06 +0000

AI-powered applications are evolving beyond just autonomous agents performing tasks. A new approach involving Human-in-the-Loop allows users to provide feedback, review results, and decide the next steps for the AI. These run-time agents are known as CoAgents.

TL;DR

In this tutorial, you'll learn how to build a Perplexity clone using LangGraph, CopilotKit, and Tavily.

Time to start building!

What is an Agentic Copilot?

Agentic copilots are how CopilotKit brings LangGraph agents into your application.

CoAgents are CopilotKit's approach to building agentic experiences!

In short, it will handle user requests by performing multiple search queries and stream the search back with status and results in real-time to the client.

Checkout CopilotKit ⭐️

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We'll also make use of the following:

Python - a popular programming language for building AI agents with LangGraph; make sure it is installed on your computer.
LangGraph - a framework for creating and deploying AI agents. It also helps to define the control flows and actions to be performed by the agent.
OpenAI API Key - to enable us to perform various tasks using the GPT models; for this tutorial, ensure you have access to the GPT-4 model.
Tavily AI - a search engine that enables AI agents to conduct research and access real-time knowledge within the application.
CopilotKit - an open-source copilot framework for building custom AI chatbots, in-app AI agents, and text areas.
Shad Cn UI - provides a collection of reusable UI components within the application.

How to Create AI Agents with LangGraph and CopilotKit

In this section, you'll learn how to create an AI agent using LangGraph and CopilotKit.

First, clone the CopilotKit CoAgents starter repository. The ui directory contains the frontend for the Next.js application, and the agent directory holds the CoAgent for the application.

Inside the agent directory, install the project dependencies using Poetry.

cd agent
poetry install

Create a .env file within the agent folder and copy your OpenAI and Tavily AI API keys into the file:

OPENAI_API_KEY=
TAVILY_API_KEY=

Copy the code snippet below into the agent.py file:

"""
This is the main entry point for the AI.
It defines the workflow graph and the entry point for the agent.
"""
# pylint: disable=line-too-long, unused-import
from langgraph.graph import StateGraph, END
from langgraph.checkpoint.memory import MemorySaver

from ai_researcher.state import AgentState
from ai_researcher.steps import steps_node
from ai_researcher.search import search_node
from ai_researcher.summarize import summarize_node
from ai_researcher.extract import extract_node

def route(state):
    """Route to research nodes."""
    if not state.get("steps", None):
        return END

    current_step = next((step for step in state["steps"] if step["status"] == "pending"), None)

    if not current_step:
        return "summarize_node"

    if current_step["type"] == "search":
        return "search_node"

    raise ValueError(f"Unknown step type: {current_step['type']}")

# Define a new graph
workflow = StateGraph(AgentState)
workflow.add_node("steps_node", steps_node)
workflow.add_node("search_node", search_node)
workflow.add_node("summarize_node", summarize_node)
workflow.add_node("extract_node", extract_node)
# Chatbot
workflow.set_entry_point("steps_node")

workflow.add_conditional_edges(
    "steps_node", 
    route,
    ["summarize_node", "search_node", END]
)

workflow.add_edge("search_node", "extract_node")

workflow.add_conditional_edges(
    "extract_node",
    route,
    ["summarize_node", "search_node"]
)

workflow.add_edge("summarize_node", END)

memory = MemorySaver()
graph = workflow.compile(checkpointer=memory)

The code snippet above defines the LangGraph agent workflow. It starts from the steps_node, searches for the results, summarizes them, and extracts the key points.

Next create a demo.py file with the code snippet below:


"""Demo"""

import os
from dotenv import load_dotenv
load_dotenv()

from fastapi import FastAPI
import uvicorn
from copilotkit.integrations.fastapi import add_fastapi_endpoint
from copilotkit import CopilotKitSDK, LangGraphAgent
from ai_researcher.agent import graph

app = FastAPI()
sdk = CopilotKitSDK(
    agents=[
        LangGraphAgent(
            name="ai_researcher",
            description="Search agent.",
            graph=graph,
        )
    ],
)

add_fastapi_endpoint(app, sdk, "/copilotkit")

# add new route for health check
@app.get("/health")
def health():
    """Health check."""
    return {"status": "ok"}

def main():
    """Run the uvicorn server."""
    port = int(os.getenv("PORT", "8000"))
    uvicorn.run("ai_researcher.demo:app", host="0.0.0.0", port=port, reload=True)

The code above creates a FastAPI endpoint that hosts the LangGraph agent and connects it to the CopilotKit SDK.

You can copy the remaining code for creating the CoAgent from the GitHub repository. In the following sections, you'll learn how to build the user interface for the Perplexity clone and handle search requests using CopilotKit.

Building the application interface with Next.js

In this section, I'll walk you through the process of building the user interface for the application.

First, create a Next.js Typescript project by running the code snippet below:

# 👉🏻 Navigate into the ui folder
npx create-next-app ./

Install the ShadCn UI library to the newly created project by running the code snippet below:

npx shadcn@latest init

Next, create a components folder at the root of the Next.js project, then copy the ui folder from this GitHub repository into that folder. Shadcn allows you to easily add various components to your application by installing them via the command line.

In addition to the Shadcn components, you'll need to create a few components representing different parts of the application interface. Run the following code snippet inside the components folder to add these components to the Next.js project:

touch ResearchWrapper.tsx ResultsView.tsx HomeView.tsx
touch AnswerMarkdown.tsx Progress.tsx SkeletonLoader.tsx

Copy the code snippet below into the app/page.tsx file:

"use client";

import { ResearchWrapper } from "@/components/ResearchWrapper";
import { ModelSelectorProvider, useModelSelectorContext } from "@/lib/model-selector-provider";
import { ResearchProvider } from "@/lib/research-provider";
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function ModelSelectorWrapper() {

  return (
      <CopilotKit runtimeUrl={useLgc ? "/api/copilotkit-lgc" : "/api/copilotkit"} agent="ai_researcher">
        <ResearchProvider>
          <ResearchWrapper />
        </ResearchProvider>
      </CopilotKit>
  );
}

In the code snippet above, ResearchProvider is a custom React context provider that shares the user's search query and results, making them accessible to all components within the application. The ResearchWrapper component contains the core application elements and manages the UI.

Create a lib folder containing a research-provider.tsx file at the root of the Next.js project and copy the code below into the file:

import { createContext, useContext, useState, ReactNode, useEffect } from "react";

type ResearchContextType = {
  researchQuery: string;
  setResearchQuery: (query: string) => void;
  researchInput: string;
  setResearchInput: (input: string) => void;
  isLoading: boolean;
  setIsLoading: (loading: boolean) => void;
  researchResult: ResearchResult | null;
  setResearchResult: (result: ResearchResult) => void;
};

type ResearchResult = {
  answer: string;
  sources: string[];
}

const ResearchContext = createContext<ResearchContextType | undefined>(undefined);

export const ResearchProvider = ({ children }: { children: ReactNode }) => {
  const [researchQuery, setResearchQuery] = useState<string>("");
  const [researchInput, setResearchInput] = useState<string>("");
  const [researchResult, setResearchResult] = useState<ResearchResult | null>(null);
  const [isLoading, setIsLoading] = useState<boolean>(false);

  useEffect(() => {
    if (!researchQuery) {
      setResearchResult(null);
      setResearchInput("");
    }
  }, [researchQuery, researchResult]);

  return (
    <ResearchContext.Provider
      value={{
        researchQuery,
        setResearchQuery,
        researchInput,
        setResearchInput,
        isLoading,
        setIsLoading,
        researchResult,
        setResearchResult,
      }}
    >
      {children}
    </ResearchContext.Provider>
  );
};

export const useResearchContext = () => {
  const context = useContext(ResearchContext);
  if (context === undefined) {
    throw new Error("useResearchContext must be used within a ResearchProvider");
  }
  return context;
};

The states are declared and saved to the ResearchContext to ensure they are properly managed across multiple components within the application.

Create a ResearchWrapper component as shown below:

import { HomeView } from "./HomeView";
import { ResultsView } from "./ResultsView";
import { AnimatePresence } from "framer-motion";
import { useResearchContext } from "@/lib/research-provider";

export function ResearchWrapper() {
  const { researchQuery, setResearchInput } = useResearchContext();

  return (
    <>
      <div className="flex flex-col items-center justify-center relative z-10">
        <div className="flex-1">
          {researchQuery ? (
            <AnimatePresence
              key="results"
              onExitComplete={() => {
                setResearchInput("");
              }}
              mode="wait"
            >
              <ResultsView key="results" />
            </AnimatePresence>
          ) : (
            <AnimatePresence key="home" mode="wait">
              <HomeView key="home" />
            </AnimatePresence>
          )}
        </div>
        <footer className="text-xs p-2">
          <a
            href="https://copilotkit.ai"
            target="_blank"
            rel="noopener noreferrer"
            className="text-slate-600 font-medium hover:underline"
          >
            Powered by CopilotKit 🪁
          </a>
        </footer>
      </div>
    </>
  );
}

The ResearchWrapper component renders the HomeView component as the default view and displays the ResultView when a search query is provided. The useResearchContext hook enables us to access the researchQuery state and update the view accordingly.

Finally, create the HomeView component to render the application home page interface.

"use client";

import { useEffect, useState } from "react";
import { Textarea } from "./ui/textarea";
import { cn } from "@/lib/utils";
import { Button } from "./ui/button";
import { CornerDownLeftIcon } from "lucide-react";
import { useResearchContext } from "@/lib/research-provider";
import { motion } from "framer-motion";
import { useCoAgent } from "@copilotkit/react-core";
import { TextMessage, MessageRole } from "@copilotkit/runtime-client-gql";
import type { AgentState } from "../lib/types";
import { useModelSelectorContext } from "@/lib/model-selector-provider";

const MAX_INPUT_LENGTH = 250;

export function HomeView() {
  const { setResearchQuery, researchInput, setResearchInput } =
    useResearchContext();
  const { model } = useModelSelectorContext();
  const [isInputFocused, setIsInputFocused] = useState(false);
  const {
    run: runResearchAgent,
  } = useCoAgent<AgentState>({
    name: "ai_researcher",
    initialState: {
      model,
    },
  });

  const handleResearch = (query: string) => {
    setResearchQuery(query);
    runResearchAgent(() => {
      return new TextMessage({
        role: MessageRole.User,
        content: query,
      });
    });
  };

  const suggestions = [
    { label: "Electric cars sold in 2024 vs 2023", icon: "🚙" },
    { label: "Top 10 richest people in the world", icon: "💰" },
    { label: "Population of the World", icon: "🌍 " },
    { label: "Weather in Seattle VS New York", icon: "⛅️" },
  ];

  return (
    <motion.div
      initial={{ opacity: 0, y: -50 }}
      animate={{ opacity: 1, y: 0 }}
      exit={{ opacity: 0 }}
      transition={{ duration: 0.4 }}
      className="h-screen w-full flex flex-col gap-y-2 justify-center items-center p-4 lg:p-0"
    >
      <h1 className="text-4xl font-extralight mb-6">
        What would you like to know?
      </h1>

      <div
        className={cn(
          "w-full bg-slate-100/50 border shadow-sm rounded-md transition-all",
          {
            "ring-1 ring-slate-300": isInputFocused,
          }
        )}
      >
        <Textarea
          placeholder="Ask anything..."
          className="bg-transparent p-4 resize-none focus-visible:ring-0 focus-visible:ring-offset-0 border-0 w-full"
          onFocus={() => setIsInputFocused(true)}
          onBlur={() => setIsInputFocused(false)}
          value={researchInput}
          onChange={(e) => setResearchInput(e.target.value)}
          onKeyDown={(e) => {
            if (e.key === "Enter" && !e.shiftKey) {
              e.preventDefault();
              handleResearch(researchInput);
            }
          }}
          maxLength={MAX_INPUT_LENGTH}
        />
        <div className="text-xs p-4 flex items-center justify-between">
          <div
            className={cn("transition-all duration-300 mt-4 text-slate-500", {
              "opacity-0": !researchInput,
              "opacity-100": researchInput,
            })}
          >
            {researchInput.length} / {MAX_INPUT_LENGTH}
          </div>
          <Button
            size="sm"
            className={cn("rounded-full transition-all duration-300", {
              "opacity-0 pointer-events-none": !researchInput,
              "opacity-100": researchInput,
            })}
            onClick={() => handleResearch(researchInput)}
          >
            Research
            <CornerDownLeftIcon className="w-4 h-4 ml-2" />
          </Button>
        </div>
      </div>
      <div className="grid grid-cols-2 w-full gap-2 text-sm">
        {suggestions.map((suggestion) => (
          <div
            key={suggestion.label}
            onClick={() => handleResearch(suggestion.label)}
            className="p-2 bg-slate-100/50 rounded-md border col-span-2 lg:col-span-1 flex cursor-pointer items-center space-x-2 hover:bg-slate-100 transition-all duration-300"
          >
            <span className="text-base">{suggestion.icon}</span>
            <span className="flex-1">{suggestion.label}</span>
          </div>
        ))}
      </div>
    </motion.div>
  );
}

How to Connect your CoAgent to a Next.js Application

In this section, you'll learn how to connect the CopilotKit CoAgent to your Next.js application to enable users to perform search operations within the application.

Install the following CopilotKit packages and the OpenAI Node.js SDK. The CopilotKit packages allow the co-agent to interact with the React state values and make decisions within the application.

npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @copilotkit/runtime-client-gql openai

Create an api folder within the Next.js app folder. Inside the api folder, create a copilotkit directory containing a route.ts file. This will create an API endpoint (/api/copilotkit) that connects the frontend application to the CopilotKit CoAgent.

cd app
mkdir api && cd api
mkdir copilotkit && cd copilotkit
touch route.ts

Copy the code snippet below into the api/copilotkit/route.ts file:

import { NextRequest } from "next/server";
import {
  CopilotRuntime,
  OpenAIAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import OpenAI from "openai";

//👇🏻 initializes OpenAI as the adapter
const openai = new OpenAI();
const serviceAdapter = new OpenAIAdapter({ openai } as any);

//👇🏻 connects the CopilotKit runtime to the CoAgent
const runtime = new CopilotRuntime({
  remoteEndpoints: [
    {
      url: process.env.REMOTE_ACTION_URL || "http://localhost:8000/copilotkit",
    },
  ],
});

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

The code snippet above sets up the CopilotKit runtime at the /api/copilotkit API endpoint, allowing CopilotKit to process user requests through the AI co-agent.

Finally, update the app/page.tsx by wrapping the entire application with the CopilotKit component which provides the copilot context to all application components.

"use client";

import { ModelSelector } from "@/components/ModelSelector";
import { ResearchWrapper } from "@/components/ResearchWrapper";
import { ModelSelectorProvider, useModelSelectorContext } from "@/lib/model-selector-provider";
import { ResearchProvider } from "@/lib/research-provider";
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function ModelSelectorWrapper() {
  return (
      <main className="flex flex-col items-center justify-between">
        <ModelSelectorProvider>
            <Home/>
          <ModelSelector />
        </ModelSelectorProvider>
      </main>
  );
}

function Home() {
  const { useLgc } = useModelSelectorContext();

  return (
      <CopilotKit runtimeUrl={useLgc ? "/api/copilotkit-lgc" : "/api/copilotkit"} agent="ai_researcher">
        <ResearchProvider>
          <ResearchWrapper />
        </ResearchProvider>
      </CopilotKit>
  );
}

The CopilotKit component wraps the entire application and accepts two props - runtimeUrl and agent. The runtimeUrl is the backend API route that hosts the AI agent and agent is the name of the agent performing the action.

Accepting Requests and Streaming Responses to the Frontend

To enable CopilotKit to access and process user inputs, it provides the useCoAgent hook, which allows access to the agent's state from anywhere within the application.

For example, the code snippet below demonstrates how to use the useCoAgent hook. The state variable allows access to the agent's current state, setState is used to modify the state, and the run function executes instructions using the agent. The start and stop functions initiate and halt the agent's execution.

const { state, setState, run, start, stop } = useCoAgent({
    name: "search_agent",
});

Update the HomeView component to execute the agent when a search query is provided.

//👇🏻 import useCoAgent hook from CopilotKit
import { useCoAgent } from "@copilotkit/react-core";

const { run: runResearchAgent } = useCoAgent({
    name: "search_agent",
});

const handleResearch = (query: string) => {
    setResearchQuery(query);
    runResearchAgent(query); //👉🏻 starts the agent execution
};

Next, you can stream the search results to the the ResultsView by accessing the state variable within the useCoAgent hook. Copy the code snippet below into the ResultsView component.

"use client";

import { useResearchContext } from "@/lib/research-provider";
import { motion } from "framer-motion";
import { BookOpenIcon, LoaderCircleIcon, SparkleIcon } from "lucide-react";
import { SkeletonLoader } from "./SkeletonLoader";
import { useCoAgent } from "@copilotkit/react-core";
import { Progress } from "./Progress";
import { AnswerMarkdown } from "./AnswerMarkdown";

export function ResultsView() {
    const { researchQuery } = useResearchContext();
    //👇🏻 agent state
    const { state: agentState } = useCoAgent({
        name: "search_agent",
    });

    console.log("AGENT_STATE", agentState);

    //👇🏻 keeps track of the current agent processing state
    const steps =
        agentState?.steps?.map((step: any) => {
            return {
                description: step.description || "",
                status: step.status || "pending",
                updates: step.updates || [],
            };
        }) || [];

    const isLoading = !agentState?.answer?.markdown;

    return (
        <motion.div
            initial={{ opacity: 0, y: -50 }}
            animate={{ opacity: 1, y: 0 }}
            exit={{ opacity: 0, y: -50 }}
            transition={{ duration: 0.5, ease: "easeOut" }}
        >
            <div className='max-w-[1000px] p-8 lg:p-4 flex flex-col gap-y-8 mt-4 lg:mt-6 text-sm lg:text-base'>
                <div className='space-y-4'>
                    <h1 className='text-3xl lg:text-4xl font-extralight'>
                        {researchQuery}
                    </h1>
                </div>

                <Progress steps={steps} />

                <div className='grid grid-cols-12 gap-8'>
                    <div className='col-span-12 lg:col-span-8 flex flex-col'>
                        <h2 className='flex items-center gap-x-2'>
                            {isLoading ? (
                                <LoaderCircleIcon className='animate-spin w-4 h-4 text-slate-500' />
                            ) : (
                                <SparkleIcon className='w-4 h-4 text-slate-500' />
                            )}
                            Answer
                        </h2>

                        <div className='text-slate-500 font-light'>
                            {isLoading ? (
                                <SkeletonLoader />
                            ) : (
                                <AnswerMarkdown markdown={agentState?.answer?.markdown} /> //👈🏼 displays search results
                            )}
                        </div>
                    </div>

                    {agentState?.answer?.references?.length && (
                        <div className='flex col-span-12 lg:col-span-4 flex-col gap-y-4 w-[200px]'>
                            <h2 className='flex items-center gap-x-2'>
                                <BookOpenIcon className='w-4 h-4 text-slate-500' />
                                References
                            </h2>
                            <ul className='text-slate-900 font-light text-sm flex flex-col gap-y-2'>
                                {agentState?.answer?.references?.map(
                                    (ref: any, idx: number) => (
                                        <li key={idx}>
                                            <a
                                                href={ref.url}
                                                target='_blank'
                                                rel='noopener noreferrer'
                                            >
                                                {idx + 1}. {ref.title}
                                            </a>
                                        </li>
                                    )
                                )}
                            </ul>
                        </div>
                    )}
                </div>
            </div>
        </motion.div>
    );
}

The code snippet above retrieves the search results from the agent's state and streams them to the frontend using the useCoAgent hook. The search results are returned in markdown format and passed into the AnswerMarkdown component, which renders the content on the page.

Finally, copy the code snippet below into the AnswerMarkdown component. This will render the markdown content as formatted text using the React Markdown library.

import Markdown from "react-markdown";

export function AnswerMarkdown({ markdown }: { markdown: string }) {
    return (
        <div className='markdown-wrapper'>
            <Markdown>{markdown}</Markdown>
        </div>
    );
}

Congratulations! You've completed the project for this tutorial. You can also watch the video recording here:

Complete Webinar Recording

Wrapping it up

LLM intelligence is the most effective when it works alongside human intelligence, and CopilotKit CoAgents allows you to integrate AI agents, copilots, and various types of assistants into your software applications in just a few minutes.

If you need to build an AI product or integrate AI agents into your app, you should consider CopilotKit.

The source code for this tutorial is available on GitHub:

https://github.com/CopilotKit/CopilotKit/tree/main/examples/coagents-ai-researcher

Thank you for reading!

How to implement drag and drop in React using dnd-kit

David Asaolu — Wed, 27 Nov 2024 10:58:10 +0000

As a developer, you will encounter various projects where you'll need to implement drag and drop functionality. Whether you're building kanban boards, e-commerce platforms with custom cart interactions or even games, drag and drop enhances the overall user experience of your application.

Despite its widespread use, implementing drag and drop can be challenging—especially when building custom interfaces that need to handle complex interactions. That’s where dnd-kit, a powerful and developer-friendly open-source library, comes in.

In this tutorial, you'll learn how to implement drag and drop easily in React or Nextjs applications, enabling you track and respond to user interactions within your application.

What is dnd-kit?

Dnd-kit is a simple, lightweight, and modular library that enables you to implement drag and drop functionality in React applications. It provides two hooks: useDraggable and useDroppable, allowing you to integrate and respond to drag and drop events.

Dnd-kit also supports various use cases such as: lists, grids, multiple containers, nested contexts, variable sized items, virtualized lists, 2D Games, and many more.

Next, let's see dnd-kit in action.

Project Set up and Installation

To demonstrate how dnd-kit works, we'll build a simple task manager app. Its interface will help the customer support team efficiently track and resolve issues within the application.

PS: The complete application, including authentication, database interactions and notifications, will be available in the coming week.

Create a Next.js Typescript project by running the code snippet below:

npx create-next-app drag-n-drop

Add a types.d.ts file at the root of the Next.js project and copy the code snippet below into the file:

type ColumnStatus = {
    status: "new" | "open" | "closed";
};
type ColumnType = {
    title: string;
    id: ColumnStatus["status"];
    issues: IssueType[];
    bg_color: string;
};
type IssueType = {
    id: string;
    title: string;
    customer_name: string;
    customer_email?: string;
    content?: string;
    attachmentURL?: string;
    messages?: Message[];
    date: string;
    status: ColumnStatus["status"];
};
interface Message {
    id: string;
}

The code snippet above defines the data structure for the variables used within the application.

Building the application interface

In this section, I'll walk you through building the application interface.

Before we proceed, create a utils folder containing a lib.ts file and copy the following code snippet into the file:


//👇🏻 default list of new issues
export const newIssuesList: IssueType[] = [
    {
        id: "1",
        customer_name: "David",
        title: "How can I access my account?",
        date: "25th December, 2025",
        status: "new",
    },
];

//👇🏻 default list of open issues
export const openIssuesList: IssueType[] = [
    {
        id: "2",
        customer_name: "David",
        title: "My password is not working and I need it fixed ASAP",
        date: "20th July, 2023",
        status: "open",
    },
    {
        id: "3",
        customer_name: "David",
        title: "First Issues",
        date: "5th February, 2023",
        status: "open",
    },
    {
        id: "4",
        customer_name: "David",
        title: "First Issues",
        date: "2nd March, 2023",
        status: "open",
    },
    {
        id: "5",
        customer_name: "David",
        title:
            "What is wrong with your network? I can't access my profile settings account",
        date: "5th August, 2024",
        status: "open",
    },
];

//👇🏻 default list of closed issues
export const closedIssuesList: IssueType[] = [
    {
        id: "6",
        customer_name: "David",
        title: "First Issues",
        date: "2nd March, 2023",
        status: "closed",
    },
    {
        id: "7",
        customer_name: "Jeremiah Chibuike",
        title:
            "What is wrong with your network? I can't access my profile settings account",
        date: "5th August, 2024",
        status: "closed",
    },
    {
        id: "8",
        customer_name: "David",
        title: "First Issues",
        date: "2nd March, 2023",
        status: "closed",
    },
    {
        id: "9",
        customer_name: "David",
        title:
            "What is wrong with your network? I can't access my profile settings account",
        date: "5th August, 2024",
        status: "closed",
    },
    {
        id: "10",
        customer_name: "David",
        title:
            "What is wrong with your network? I can't access my profile settings account",
        date: "5th August, 2024",
        status: "closed",
    },
];

//👇🏻 Helper function to find and remove an issue from a list
export const findAndRemoveIssue = (
    issues: IssueType[],
    setIssues: React.Dispatch<React.SetStateAction<IssueType[]>>,
    currentIssueId: string
): IssueType | null => {
    const issueIndex = issues.findIndex((issue) => issue.id === currentIssueId);
    if (issueIndex === -1) return null; //👈🏼 Not found

    const [removedIssue] = issues.splice(issueIndex, 1);
    setIssues([...issues]); //👈🏼 Update state after removal
    return removedIssue;
};

The code snippet above includes arrays of issues grouped by their status. The findAndRemoveIssue function accepts three arguments: an issues array, a setIssues function for updating the array, and the ID of the issue to be acted upon.

Update the app/page.tsx file to render the issues in their respective columns.

"use client";
import Link from "next/link";
import Column from "@/app/components/Column";
import { useState } from "react";
import { closedIssuesList, newIssuesList, openIssuesList } from "./utils/lib";

export default function App() {
    const [newIssues, setNewIssues] = useState<IssueType[]>(newIssuesList);
    const [openIssues, setOpenIssues] = useState<IssueType[]>(openIssuesList);
    const [closedIssues, setClosedIssues] =
        useState<IssueType[]>(closedIssuesList);

    return (
        <main>
            <nav className='w-full h-[10vh] flex items-center justify-between px-8 bg-blue-100 top-0 sticky z-10'>
                <Link href='/' className='font-bold text-2xl'>
                    Suportfix
                </Link>
                <Link
                    href='/login'
                    className='bg-blue-500 px-4 py-3 rounded-md text-blue-50'
                >
                    SUPPORT CENTER
                </Link>
            </nav>

            <div className='w-full min-h-[90vh] lg:p-8 p-6 flex flex-col lg:flex-row items-start justify-between lg:space-x-4'>
                <Column
                    bg_color='red'
                    id='new'
                    title={`New (${newIssues.length})`}
                    issues={newIssues}
                />

                <Column
                    bg_color='purple'
                    id='open'
                    title={`Open (${openIssues.length})`}
                    issues={openIssues}
                />

                <Column
                    bg_color='green'
                    id='closed'
                    title={`Closed (${closedIssues.length})`}
                    issues={closedIssues}
                />
            </div>
        </main>
    );
}

Next, let's create the Column component. Add a components folder within the Next.js app folder as shown below:

cd app
mkdir components && cd components
touch Column.tsx

Copy the following code snippet into the Column.tsx file to render the issues under their respective columns.

import { bgClasses, headingClasses } from "../utils/lib";
import IssueCard from "./IssueCard";

export default function Column({ title, id, bg_color, issues }: ColumnType) {
    return (
        <div
            className={`lg:w-1/3 w-full p-4 min-h-[50vh] rounded-md shadow-md lg:mb-0 mb-6 ${
                bgClasses[bg_color] || ""
            } `}
            key={id}
        >
            <header className='flex items-center justify-between'>
                <h2 className={`font-bold text-xl mb-4 ${headingClasses[bg_color]}`}>
                    {title}
                </h2>
                {issues?.length > 4 && (
                    <button className='text-gray-500 underline text-sm'>Show More</button>
                )}
            </header>

            <div className='flex flex-col w-full items-center space-y-4'>
                {issues?.map((item) => (
                    <IssueCard
                        item={item}
                        key={item.id}
                        bg_color={bg_color}
                        columnId={id}
                    />
                ))}
            </div>
        </div>
    );
}

From the code snippet above, the Column component accepts the following props:
- bg_color represents the column colour,
- id represents the column id,
- title is the column title, and
- issues is the array of issues under each column. They are rendered within the IssueCard component.

Next, add the IssueCard component to the components folder and copy the following code snippet into the file:

import { IoIosChatbubbles } from "react-icons/io";
import { borderClasses } from "@/app/utils/lib";

export default function IssueCard({
    item,
    bg_color,
    columnId,
}: {
    item: IssueType;
    bg_color: string;
    columnId: ColumnStatus["status"];
}) {
    return (
        <div
            className={`w-full min-h-[150px] cursor-grab rounded-md bg-white z-5 border-[2px] p-4 hover:shadow-lg ${
                borderClasses[bg_color] || ""
            }`}
        >
            <h2 className='font-bold mb-3 text-gray-700 opacity-80'>{item.title}</h2>

            <p className='text-sm opacity-50 mb-[5px]'>Date created: {item.date}</p>
            <p className='text-sm opacity-50 mb-[5px]'>
                Created by: {item.customer_name}
            </p>

            <section className='flex items-center justify-end space-x-4'>
                <button className='px-4 py-2 text-sm text-white bg-blue-400 hover:bg-blue-500 flex items-center rounded'>
                    Chat <IoIosChatbubbles className='ml-[3px]' />
                </button>
                {columnId !== "closed" ? (
                    <button className='px-4 py-2 text-sm text-white bg-red-400 rounded hover:bg-red-500'>
                        Close Ticket
                    </button>
                ) : (
                    <button className='px-4 py-2 text-sm text-white bg-green-400 rounded hover:bg-green-500'>
                        Reopen Ticket
                    </button>
                )}
            </section>
        </div>
    );
}

Congratulations! You've designed the application interface. In the upcoming sections you'll learn how to add the drag and drop functionality.

Dragging and Dropping elements easily in React

In the previous section, we created two components: Column and IssueCard. The IssueCard component represents each draggable issue within a column, while the Column component contains a list of issues.

Here, we'll use the dnd-kit package to make the issues draggable and droppable across the three columns.

Install the dnd-kit package by the running the following code snippet:

npm install @dnd-kit/core

Update the app/page.tsx file as shown below:

import { DragEndEvent, DndContext } from "@dnd-kit/core";

export default function App() {
    //👇🏻 listens for drag end events
    const handleDragEnd = (event: DragEndEvent) => {};

    return (
        <main>
            {/** -- other UI elements -- */}
            <div className='w-full min-h-[90vh] lg:p-8 p-6 flex flex-col lg:flex-row items-start justify-between lg:space-x-4'>
                <DndContext onDragEnd={handleDragEnd}>
                    <Column
                        bg_color='red'
                        id='new'
                        title={`New (${newIssues.length})`}
                        issues={newIssues}
                    />

                    <Column
                        bg_color='purple'
                        id='open'
                        title={`Open (${openIssues.length})`}
                        issues={openIssues}
                    />

                    <Column
                        bg_color='green'
                        id='closed'
                        title={`Closed (${closedIssues.length})`}
                        issues={closedIssues}
                    />
                </DndContext>
            </div>
        </main>
    );
}

From the code snippet above,
- The DndContext provider wraps the entire draggable and droppable components and enables you to access the various props required to track and respond to drag and drop events.
- The DragEndEvent enables you to trigger events after a drag action.

Next, update the handleDragEnd function to move each issue to its new column when it is dragged from its column to another column.

const handleDragEnd = (event: DragEndEvent) => {
    const { active, over } = event;
        //👇🏻 no reaction if it is not over a column
    if (!over) return;
    const issueId = active.id as string;
    const newStatus = over.id as ColumnStatus["status"];
        //logs the issue id and id of its new column
    console.log({ issueId, newStatus });
};

The handleDragEnd function logs the issue id and the id of its new column when it is dragged over any of the column.

Add the following code snippet to the handleDragEnd function:

const handleDragEnd = (event: DragEndEvent) => {
    const { active, over } = event;
    if (!over) return;
    const issueId = active.id as string;
    const newStatus = over.id as ColumnStatus["status"];

    let movedIssue: IssueType | null = null;

    //👇🏻 Find and remove the issue from its current state
    movedIssue =
        movedIssue ||
        findAndRemoveIssue(newIssues, setNewIssues, issueId) ||
        findAndRemoveIssue(openIssues, setOpenIssues, issueId) ||
        findAndRemoveIssue(closedIssues, setClosedIssues, issueId);

    //👇🏻 If an issue was successfully removed, add it to the new column
    if (movedIssue) {
        movedIssue.status = newStatus; // 👈🏼 Update the status of the issue
        if (newStatus === "new") {
            setNewIssues((prev) => [...prev, movedIssue]);
        } else if (newStatus === "open") {
            setOpenIssues((prev) => [...prev, movedIssue]);
        } else if (newStatus === "closed") {
            setClosedIssues((prev) => [...prev, movedIssue]);
        }
    }
};

The handleDragEnd function moves the selected issue (item) from its current column to the new column when it is dragged over a new column.

Within the Column component, import the useDroppable hook and initialize it with the column ID. Then, assign the returned setNodeRef function to the parent <div> as a reference to enable the droppable functionality.

import { useDroppable } from "@dnd-kit/core";

export default function Column({ title, id, bg_color, issues }: ColumnType) {
    const { setNodeRef } = useDroppable({ id });

    return (
        <div
            className={`lg:w-1/3 w-full p-4 min-h-[50vh] rounded-md shadow-md lg:mb-0 mb-6 ${
                bgClasses[bg_color] || ""
            } `}
            key={id}
            ref={setNodeRef}
        >
            {/** -- UI elements -- */}
        </div>
    );
}

To make each issue draggable, use the useDraggable hook and destructure the required props: attributes, listeners, setNodeRef, and transform. Pass the issue's unique id as an argument to the hook.

Update the IssueCard component as follows:

import { useDraggable } from "@dnd-kit/core";
import { CSS } from "@dnd-kit/utilities";

export default function IssueCard({
    item,
    bg_color,
    columnId,
}: {
    item: IssueType;
    bg_color: string;
    columnId: ColumnStatus["status"];
}) {
    //👇🏻 required props to enable each issue to be draggable
    const { attributes, listeners, setNodeRef, transform } = useDraggable({
        id: item.id,
    });

    //👇🏻 required styles to track the position of each issue
    const style = { transform: CSS.Translate.toString(transform) };

    return (
        <div
            className={`w-full min-h-[150px] cursor-grab rounded-md bg-white z-5 border-[2px] p-4 hover:shadow-lg ${
                borderClasses[bg_color] || ""
            }`}
            style={style}
            ref={setNodeRef}
            {...listeners}
            {...attributes}
        >
            {/** -- UI elements -- */}
        </div>
    );
}

The style object enables dnd-kit to track the position of the issue on the screen.

Congratulations! You've completed this tutorial. You can check out the live version.

Conclusion

So far, you've learnt how to implement drag and drop functionality in React apps using the dnd-kit package. It is a lightweight and powerful solution for adding dynamic user interactions to your applications.

If you're looking for a more in-depth explanation, be sure to check out the video tutorial here:

The source code for this tutorial is available here:
https://github.com/dha-stix/drag-n-drop-tutorial-with-dnd-kit

Thank you for reading, and happy coding!

Build an AI-powered Social Media Post Scheduler (Twitter API, Next.js & Copilotkit)

David Asaolu — Wed, 17 Jul 2024 15:15:24 +0000

TL;DR

In this tutorial, you will learn how to build an AI-powered social media content generator and scheduler that allows you to schedule posts and generate content effectively.

We will cover how to:

add Twitter authentication to a Next.js application,
create a calendar-like interface from scratch,
integrate AI assistants into software applications with CopilotKit,
create action-specific AI copilots to handle various tasks within the application, and
build a post generator and scheduling application.

This project is a great way to learn how to build AI-powered apps, master social media APIs and to develop high IQ social media game.

CopilotKit: The framework for building in-app AI copilots

CopilotKit is an open-source AI copilot platform. We make it easy to integrate powerful AI into your React apps.

Build:

ChatBot: Context-aware in-app chatbots that can take actions in-app 💬
CopilotTextArea: AI-powered textFields with context-aware autocomplete & insertions 📝
Co-Agents: In-app AI agents that can interact with your app & users 🤖

Star CopilotKit ⭐️

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We'll also make use of the following:

CopilotKit - an open-source copilot framework for building custom AI chatbots, in-app AI agents, and text areas.
Redis - an in-memory database for storing the post schedule.
BullMQ - a Node.js library that manages and processes jobs in a queue.
Node Cron - a Node.js library that schedule and runs tasks (jobs) at specific intervals.
Headless UI - for creating accessible UI components for the application.
X Client ID and Secret - for authenticating users and creating posts on their behalf.
OpenAI API Key - to enable us to perform various tasks using the GPT models.

Project Set up and Package Installation

First, create a Next.js application by running the code snippet below in your terminal:

npx create-next-app social-media-scheduler

Select your preferred configuration settings. For this tutorial, we'll be using TypeScript and Next.js App Router.

Next, install the project dependencies:

npm install @headlessui/react lodash bullmq ioredis node-cron

Finally, install the required CopilotKit packages. These packages enable us to use AI auto-completion within the application, allow the AI copilot to retrieve data from the React state, and make decisions within the application.

npm install @copilotkit/react-ui @copilotkit/react-textarea @copilotkit/react-core @copilotkit/backend

Congratulations! You're now ready to build the application.

Building the Posts Scheduler App with Next.js

In this section, you'll learn how to create the user interface for the scheduling application. The application is divided into two pages: the Login page and the Dashboard page, where users can create and schedule posts.

The Login page authenticates users using their X (Twitter) profile, while the Dashboard page allows users to create, delete, and schedule posts.

The Login Page

The Login page represents the application's home page. Users need to sign in with their Twitter account to access the dashboard.

To implement this, update the page.tsx file to display a sign-in button as shown below:

import Link from "next/link";
import { getTwitterOauthUrl } from "@/app/util";

export default function Home() {
    return (
        <main className='w-full min-h-screen flex flex-col items-center justify-center p-8'>
            <h2 className='font-semibold text-2xl mb-4'>Your AI Post Scheduler</h2>
            <Link
                href={getTwitterOauthUrl()}
                className='bg-black py-3 px-6 hover:bg-gray-700 text-gray-50 rounded-lg'
            >
                Sign in with Twitter
            </Link>
        </main>
    );
}

The code snippet above displays a Sign in with Twitter button that redirects users to Twitter Oauth2 page. You'll learn how to setup the Twitter authentication shortly.

The Dashboard Page

Before we proceed, create a types.d.ts file at the root of the Next.js project. This file will contain the type declarations for the variables within the application.

interface DelSelectedCell {
    content?: string;
    day_id?: number;
    day?: string;
    time_id?: number;
    time?: string;
    published?: boolean;
    minutes?: number;
}
interface SelectedCell {
    day_id?: number;
    day?: string;
    time_id?: number;
    time?: string;
    minutes?: number;
}

interface Content {
    minutes?: number;
    content?: string;
    published?: boolean;
    day?: number;
}

interface AvailableScheduleItem {
    time: number;
    schedule: Content[][];
}

Create a utils file within the Next.js app folder and copy this code snippet from the GitHub repository into it. It contains the necessary functions for performing various data manipulations within the application.

Next, create a dashboard folder containing a page.tsx file within the Next.js app directory.

cd app
mkdir dashboard && cd dashboard
touch page.tsx

Copy the code snippet below into the dashboard/page.tsx file. It renders an App component that accepts the application's schedule as props and displays them in a table:

"use client";
import _ from "lodash";
import { useState } from "react";
import App from "@/app/components/App";
import { availableSchedule } from "../util";

export default function Dashboard() {
    //👇🏻 saves a deep copy of the availableSchedule array into the React state
    const [yourSchedule, updateYourSchedule] = useState<AvailableScheduleItem[]>(
        _.cloneDeep(availableSchedule)
    );

    return (
        <App yourSchedule={yourSchedule} updateYourSchedule={updateYourSchedule} />
    );
}

Here is the data structure for the table above:

export const tableHeadings: string[] = [
    "Time",
    "Sunday",
    "Monday",
    "Tuesday",
    "Wednesday",
    "Thursday",
    "Friday",
    "Saturday",
];

export const availableSchedule: AvailableScheduleItem[] = [
    {
        time: 0,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 1,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 2,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 3,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 4,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 5,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 6,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 7,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 8,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 9,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 10,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 11,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 12,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 13,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 14,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 15,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 16,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 17,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 18,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 19,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 20,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 21,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 22,
        schedule: [[], [], [], [], [], [], []],
    },
    {
        time: 23,
        schedule: [[], [], [], [], [], [], []],
    },
];

The tableHeadings array contains the headings for the table columns, while the availableSchedule array holds a group of objects. Each object has a time property representing each hour of the day and a schedule property containing a nested array, with each element representing a day of the week.

For example, when a user sets a schedule for Wednesday at 8 AM, the application searches for the object with a time property of 8 and updates its schedule property by inserting the schedule into the nested array at the fourth index.

You can copy the remaining UI elements for the Dashboard page from its GitHub repository.

In the upcoming sections, you'll learn how to add Twitter OAuth and CopilotKit to the application.

How to add X Authentication to your Next.js application

In this section, you’ll learn how to create a X Developer project and add X authentication your Next.js applications.

Ensure you have an X account and visit the X Developers' Portal to create a new project.

Enter the project name and provide answers to the required questions to create a new project and an app.

Set up the user authentication settings to allow you read and write posts on behalf of the users.

Finally, fill the App info section accordingly.

After setting up the authentication process, save the OAuth 2.0 Client ID and secret into a .env.local file.

TWITTER_CLIENT_ID=<your_client_ID>
NEXT_PUBLIC_TWITTER_CLIENT_ID=<your_client_ID>
TWITTER_CLIENT_SECRET=<your_client_Secret>

Authenticating users via X

Create an api folder within the Next.js app folder. Inside the api folder, create a twitter directory containing a route.ts file. This will create an API endpoint (/api/twitter) that enables us to authenticate users.

cd app
mkdir api && cd api
mkdir twitter && cd twitter
touch route.ts

Copy the code snippet below into the route.ts file:

import { NextRequest, NextResponse } from "next/server";

const BasicAuthToken = Buffer.from(
    `${process.env.TWITTER_CLIENT_ID!}:${process.env.TWITTER_CLIENT_SECRET!}`,
    "utf8"
).toString("base64");

const twitterOauthTokenParams = {
    client_id: process.env.TWITTER_CLIENT_ID!,
    code_verifier: "8KxxO-RPl0bLSxX5AWwgdiFbMnry_VOKzFeIlVA7NoA",
    redirect_uri: `http://www.localhost:3000/dashboard`,
    grant_type: "authorization_code",
};

//👇🏻 gets user access token
export const fetchUserToken = async (code: string) => {
    try {
        const formatData = new URLSearchParams({
            ...twitterOauthTokenParams,
            code,
        });
        const getTokenRequest = await fetch(
            "https://api.twitter.com/2/oauth2/token",
            {
                method: "POST",
                body: formatData.toString(),
                headers: {
                    "Content-Type": "application/x-www-form-urlencoded",
                    Authorization: `Basic ${BasicAuthToken}`,
                },
            }
        );
        const getTokenResponse = await getTokenRequest.json();
        return getTokenResponse;
    } catch (err) {
        return null;
    }
};

//👇🏻gets user's data from the access token
export const fetchUserData = async (accessToken: string) => {
    try {
        const getUserRequest = await fetch("https://api.twitter.com/2/users/me", {
            headers: {
                "Content-type": "application/json",
                Authorization: `Bearer ${accessToken}`,
            },
        });
        const getUserProfile = await getUserRequest.json();
        return getUserProfile;
    } catch (err) {
        return null;
    }
};

//👉🏻 API endpoint utilizing the functions above

From the code snippet above,
- The BasicAuthToken variable contains the encoded version of your tokens.
- The twitterOauthTokenParams contains the parameters required for getting the users' access token.
- The fetchUserToken function sends a request containing a code to Twitter's endpoint and returns the user's access token.
- The fetchUserData function uses the token to retrieve the user's X profile.

Add this endpoint below the functions. It accepts a code from the frontend when a user signs in and stores the user ID, username, and access token in a file that can be accessed when executing jobs on the server.

import { writeFile } from "fs";

export async function POST(req: NextRequest) {
    const { code } = await req.json();
    try {
        //👇🏻 get access token and the entire response
        const tokenResponse = await fetchUserToken(code);
        const accessToken = await tokenResponse.access_token;
        //👇🏻 get user data
        const userDataResponse = await fetchUserData(accessToken);
        const userCredentials = { ...tokenResponse, ...userDataResponse };

        //👇🏻  merge the user's access token, id, and username into an object
        const userData = {
            accessToken: userCredentials.access_token,
            _id: userCredentials.data.id,
            username: userCredentials.data.username,
        };
        //👇🏻 store them in a JSON file (for server-use)
        writeFile("./src/user.json", JSON.stringify(userData, null, 2), (error) => {
            if (error) {
                console.log("An error has occurred ", error);
                throw error;
            }
            console.log("Data written successfully to disk");
        });
        //👇🏻 returns a successful response
        return NextResponse.json(
            {
                data: "User data stored successfully",
            },
            { status: 200 }
        );
    } catch (err) {
        return NextResponse.json({ error: err }, { status: 500 });
    }
}

Update the dashboard/page.tsx to send the code to the API endpoint after authenticating a user.

import { useSearchParams } from 'next/navigation'
const searchParams = useSearchParams()
    const code = searchParams.get('code')

    const fetchToken = useCallback(async () => { 
            const res = await fetch("/api/twitter", {
                method: "POST",
                body: JSON.stringify({ code }),
                headers: {
                    "Content-Type": "application/json",
                },
            });
            if (res.ok) {
                const data = await res.json();
                console.log(data);
            }
    }, [code]);

    useEffect(() => {
        fetchToken();
    }, [fetchToken]);

Congratulations! When users click the Sign in with Twitter button, it redirects them to the Twitter authorisation page to enable them access the application.

How to add CopilotKit to a Next.js application

In this section, you'll learn how to add CopilotKit to the application to enable users to schedule posts automatically using AI copilots and also add auto-completion when creating post contents.

Before we proceed, visit the OpenAI Developers' Platform and create a new secret key.

Create a .env.local file and copy the your newly created secret key into the file.

OPENAI_API_KEY=<YOUR_OPENAI_SECRET_KEY>
OPENAI_MODEL=gpt-4-1106-preview

Next, you need to create an API endpoint for CopilotKit. Within the Next.js app folder, create an api/copilotkit folder containing a route.ts file.

cd app
mkdir api && cd api
mkdir copilotkit && cd copilotkit
touch route.ts

Copy the code snippet below into the route.ts file. The CopilotKit backend accept users’ requests and make decisions using the OpenAI model.

import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/backend";

export const runtime = "edge";

export async function POST(req: Request): Promise<Response> {
    const copilotKit = new CopilotRuntime({});
    const openaiModel = process.env["OPENAI_MODEL"];

    return copilotKit.response(req, new OpenAIAdapter({model: openaiModel}));
}

To connect the application to the backend API route, copy the code snippet below into the dashboard/page.tsx file.

"use client";
import App from "@/app/components/App";
import _ from "lodash";
import {  useState } from "react";
import { availableSchedule } from "../util";

//👇🏻 CopilotKit components
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotPopup } from "@copilotkit/react-ui";

//👇🏻 CSS styles for CopilotKit components
import "@copilotkit/react-ui/styles.css";
import "@copilotkit/react-textarea/styles.css";

export default function Dashboard() {
    const [yourSchedule, updateYourSchedule] = useState<AvailableScheduleItem[]>(
        _.cloneDeep(availableSchedule)
    );

    //👉🏻 other UI states and functions

    return (
        <CopilotKit runtimeUrl='/api/copilotkit/'>
            <App
                yourSchedule={yourSchedule}
                updateYourSchedule={updateYourSchedule}
            />
            <CopilotPopup
                instructions='Help the user create and manage ad campaigns.'
                defaultOpen={true}
                labels={{
                    title: "Posts Scheduler Copilot",
                    initial:
                        "Hello there! I can help you manage your schedule. What do you want to do? You can generate posts, add, and delete scheduled posts.",
                }}
                clickOutsideToClose={false}
            ></CopilotPopup>
         </CopilotKit>
    );
}

The CopilotKit component wraps the entire application and accepts a runtimeUrl prop that contains a link to the API endpoint. The CopilotKitPopup component adds a chatbot sidebar panel to the application, enabling us to provide various instructions to CopilotKit.

How to schedule posts with CopilotKit

CopilotKit provides two hooks that enable us to handle user's request and plug into the application state: useCopilotAction and useCopilotReadable.

The useCopilotAction hook allows you to define actions to be carried out by CopilotKit. It accepts an object containing the following parameters:

name - the action's name.
description - the action's description.
parameters - an array containing the list of the required parameters.
render - the default custom function or string.
handler - the executable function that is triggered by the action.

useCopilotAction({
    name: "sayHello",
    description: "Say hello to someone.",
    parameters: [
        {
            name: "name",
            type: "string",
            description: "name of the person to say greet",
        },
    ],
    render: "Process greeting message...",
    handler: async ({ name }) => {
        alert(`Hello, ${name}!`);
    },
});

The useCopilotReadable hook provides the application state to CopilotKit.

import { useCopilotReadable } from "@copilotkit/react-core";

const myAppState = "...";
useCopilotReadable({
  description: "The current state of the app",
  value: myAppState
});

Now, let’s plug the application state into CopilotKit and create an action that helps us to schedule posts.

Within the App component, pass the schedule state into CopilotKit. You can also provide additional information (context) to enable CopilotKit make adequate and precise decisions.

//👇🏻 Application state
useCopilotReadable({
    description: "The user's Twitter post schedule",
    value: yourSchedule,
});

//👇🏻 Application context
useCopilotReadable({
    description: "Guidelines for the user's Twitter post schedule",
    value:
            "Your schedule is displayed in a table format. Each row represents an hour of the day, and each column represents a day of the week. You can add a post by clicking on an empty cell, and delete a post by clicking on a filled cell. Sunday is the first day of the week and has a day_id of 0.",
    });

Create a CopilotKit action that schedule posts based on the user’s prompts:

    useCopilotAction({
        name: "updatePostSchedule",
        description: "Update the user's Twitter post schedule",
        parameters: [
            {
                name: "update_schedule",
                type: "object",
                description: "The user's updated post schedule",
                attributes: [
                    {
                        name: "time",
                        type: "number",
                        description: "The time of the post",
                    },
                    {
                        name: "schedule",
                        type: "object[]",
                        description: "The schedule for the time",
                        attributes: [
                            {
                                name: "content",
                                type: "string",
                                description: "The content of the post",
                            },
                            {
                                name: "minutes",
                                type: "number",
                                description: "The minutes past the hour",
                            },
                            {
                                name: "published",
                                type: "boolean",
                                description: "Whether the post is published",
                            },
                            {
                                name: "day",
                                type: "number",
                                description: "The day of the week",
                            },
                        ],
                    },
                ],
            },
        ],
        handler: ({ update_schedule }) => {
            setAddEventModal(true);
            setSelectedCell({
                day_id: update_schedule.schedule[0].day + 1,
                day: tableHeadings[update_schedule.schedule[0].day + 1],
                time_id: update_schedule.time,
                time: formatTime(update_schedule.time),
            });
            setContent(update_schedule.schedule[0].content);
            setMinute(update_schedule.schedule[0].minutes);
        },
        render: "Updating schedule...",
    });

The code snippet above shows the useCopilotAction hook in action. It accepts an object containing name, description, parameters, handler, and render properties.

The name property represents the name of the action.
The description property provides a brief overview of what the function does.
The parameters array contains an update_schedule object with a time and schedule property. The schedule object includes content, minutes, published, and day attributes.
The handler function describes the action to be carried out when triggered. In the example above, the handler function opens the AddPost modal, updates its value with AI-generated inputs, and allows the user adjust the schedule accordingly.

Managing and Scheduling Posts using Redis and BullMQ

In this section, you’ll learn how to store the post schedule in a Redis database, and create a job that checks the schedule at intervals to post the content on X (Twitter).

First, you need to install Redis on your computer. If you are using MacOS and have Homebrew installed, run the code snippet in your terminal to install Redis:

brew --version
brew install redis

Once the installation process is complete, you can test your Redis server by running the following code snippet in your terminal:

redis-server

Now, you can use the Node.js Redis client within the application.

Create an /api/schedule API route on the server that accepts the entire schedule table when a user adds or deletes a scheduled post.

import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) { 
    const { schedule } = await req.json();
    try {
         console.log({schedule})

        return NextResponse.json(
            { message: "Schedule updated!", schedule },
            { status: 200 }
        );

    } catch (error) { 
        return NextResponse.json(
            { message: "Error updating schedule", error },
            { status: 500 }
        );

    }   
}

Update the API endpoint to store the entire schedule in the Redis database. Redis stores data in key/value pairs, making it super-fast for storing and retrieving data.

import { NextRequest, NextResponse } from "next/server";
import Redis from "ioredis";
const redis = new Redis();

export async function POST(req: NextRequest) { 
    const { schedule } = await req.json();
    try {
        //👇🏻 saves the schedule
        await redis.set("schedule", JSON.stringify(schedule));

        return NextResponse.json(
            { message: "Schedule updated!", schedule },
            { status: 200 }
        );
    } catch (error) { 
        return NextResponse.json(
            { message: "Error updating schedule", error },
            { status: 500 }
        );
    }
}

You can also add a GET request handler within the api/schedule/route.ts file to fetch existing scheduled posts from the Redis database and display them when a user logs into the application.

export async function GET() {
    try {
        const schedule = await redis.get("schedule");
        if (schedule) {
            return NextResponse.json(
                { message: "Schedule found", schedule: JSON.parse(schedule) },
                { status: 200 }
            );
        }
    } catch (error) {
        return NextResponse.json(
        { message: "Schedule not found" },
        { status: 500 }
    );
}
}

Finally, you need to set up a job queue that runs every minute to check for posts scheduled for the current day and post them at the appropriate time.

Create a worker.ts file within the Next.js src folder and copy the following code into the file:

import data from "./user.json";
import { Worker, Queue } from 'bullmq';
import Redis from "ioredis";

//👇🏻 initializes a job queue connected to the Redis database
const redis = new Redis({maxRetriesPerRequest: null});
const scheduleQueue = new Queue('schedule-queue', { connection: redis });

The code snippet above creates a job queue that is connected to the Redis database.

Implement a scheduleJobs function within the worker.ts file that gets the posts scheduled for the current time and adds them to the job queue.

//👇🏻 add jobs to the queue
export const scheduleJobs = async (schedule: AvailableScheduleItem[]) => {
    //👇🏻 gets current time and day
    const now = new Date();
    const currentHour = now.getHours();
    const currentMinute = now.getMinutes();
    const currentDay = now.getDay();

    //👇🏻 gets posts for the current hour
    const currentSchedule = schedule.find((item) => item.time === currentHour);
    const schedulesForTheHour = currentSchedule?.schedule[currentDay];

    //👇🏻 gets scheduled posts for the current time
    if (schedulesForTheHour && schedulesForTheHour?.length > 0) {
        const awaitingJobs = schedulesForTheHour.filter(
            (scheduleItem) =>
                scheduleItem.minutes && scheduleItem.minutes <= currentMinute
        );

        //👇🏻 add jobs to queue
        return awaitingJobs.map(async (scheduleItem) => {
            const job = await scheduleQueue.add("jobs", {
                message: scheduleItem.content
            }, {
                removeOnComplete: true,
            });
            console.log(`Job ${job.id} added to queue`);
        });
    }
};

Import the scheduleJobs function into the api/schedule endpoint and trigger the function every minute using Node Cron.

//👉🏻 api/schedule/route.ts
import cron from "node-cron";

export async function POST(req: NextRequest) { 
    const { schedule } = await req.json();
    try {
        await redis.set("schedule", JSON.stringify(schedule));
        cron.schedule('* * * * *', async() => {
            console.log('Triggering jobs...');
            await scheduleJobs(schedule);
        });

        return NextResponse.json(
            { message: "Schedule updated!", schedule },
            { status: 200 }
        );
    } catch (error) { 
        return NextResponse.json(
            { message: "Error updating schedule", error },
            { status: 500 }
        );
    }
}

Next, add a worker function within the workers.ts file that executes the jobs within the queue by sending the posts’ content to X (Twitter).

//👇🏻 processing jobs
const scheduleWorker = new Worker('schedule-queue', async (job) => {
  console.log(`Processing job ${job.id} of type ${job.name} with data: ${job.data.message}`)
    console.log("Posting content...")

    //👇🏻 post content to X
    const postTweet = await fetch("https://api.twitter.com/2/tweets", {
        method: "POST",
        headers: {
            "Content-type": "application/json",
            Authorization: `Bearer ${data.accessToken}`,
        },
        body: JSON.stringify({ text: job.data.message })
    });
    if (postTweet.ok) { 
          console.log("Content posted!")
    }
}, { connection: redis})

//👇🏻 listening for completed job
scheduleWorker.on('completed', job => {
    console.log(`${job.id} has completed!`);
});

Finally, you can execute the worker by running npm run worker after updating the scripts within the package.json file.

{
 "scripts": {
    "worker": "npx tsx --watch src/worker.ts"
  }
}

Congratulations! You’ve completed the project for this tutorial.

Conclusion

So far, you’ve learned how to authenticate users via X, store data in a Redis database, create and manage jobs with Redis and BullMQ, and integrate AI assistants into your Next.js applications using CopilotKit.

CopilotKit is an incredible tool that allows you to add AI Copilots to your products within minutes. Whether you're interested in AI chatbots and assistants or automating complex tasks, simplifies the process.

If you need to build an AI product or integrate an AI tool into your software applications, you should consider CopilotKit.

You can find the source code for this tutorial on GitHub:

https://github.com/dha-stix/ai-post-generator-and-scheduler-with-copilotkit

Thank you for reading!

How to have AI onboard your users (Next.js, OpenAI, CopilotKit)

David Asaolu — Thu, 25 Apr 2024 09:38:35 +0000

TL;DR

In this article, you'll learn how to build an AI-powered campaign manager application that allows you to create and analyze advertisement campaigns, enabling you to make the right decisions for your business.

We'll cover how to:

build web applications with Next.js,
integrate AI assistants into software applications with CopilotKit, and
create action-specific AI copilots that handle various tasks within the application.
Build a campaign manager

CopilotKit: The framework for building in-app AI copilots

CopilotKit is an open-source AI copilot platform. We make it easy to integrate powerful AI into your React apps.

Build:

ChatBot: Context-aware in-app chatbots that can take actions in-app 💬
CopilotTextArea: AI-powered textFields with context-aware autocomplete & insertions 📝
Co-Agents: In-app AI agents that can interact with your app & users 🤖

Star CopilotKit ⭐️

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We'll also make use of the following:

Radix UI - for creating accessible UI components for the application.
OpenAI API Key - to enable us to perform various tasks using the GPT models.
CopilotKit - an open-source copilot framework for building custom AI chatbots, in-app AI agents, and text areas.

Project Set up and Package Installation

First, create a Next.js application by running the code snippet below in your terminal:

npx create-next-app campaign-manager

Select your preferred configuration settings. For this tutorial, we'll be using TypeScript and Next.js App Router.

Next, install Heroicons, Radix UI, and its primitive components into the project.

npm install @heroicons/react @radix-ui/react-avatar @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-icons @radix-ui/react-label @radix-ui/react-popover @radix-ui/react-select @radix-ui/react-slot @radix-ui/react-tabs

Also, install the Recharts library - a React library for creating interactive charts - and the following utility packages:

npm install recharts class-variance-authority clsx cmdk date-fns lodash react-day-picker tailwind-merge tailwindcss-animate

Finally, install the CopilotKit packages. These packages enable the AI copilot to retrieve data from the React state and make decisions within the application.

npm install @copilotkit/react-ui @copilotkit/react-textarea @copilotkit/react-core @copilotkit/backend

Congratulations! You're now ready to build the application.

Building the Campaign Manager App with Next.js

In this section, I'll walk you through building the user interface for the campaign manager application.

First, let’s do some initial set up.

Create a components and lib folder within the src folder.

cd src
mkdir components lib

Within the lib folder, we'll declare the static types and default campaigns for the application. Therefore, create data.ts and types.ts files within the lib folder.

cd lib
touch data.ts type.ts

Copy the code snippet below into the type.ts file. It declares the campaign attributes and their data types.

export interface Campaign {
    id: string;
    objective?:
        | "brand-awareness"
        | "lead-generation"
        | "sales-conversion"
        | "website-traffic"
        | "engagement";
    title: string;
    keywords: string;
    url: string;
    headline: string;
    description: string;
    budget: number;
    bidStrategy?: "manual-cpc" | "cpa" | "cpm";
    bidAmount?: number;
    segment?: string;
}

Create the default campaign lists for the application and copy them into the data.ts file.

import { Campaign } from "./types";

export let DEFAULT_CAMPAIGNS: Campaign[] = [
    {
        id: "1",
        title: "CopilotKit",
        url: "https://www.copilotkit.ai",
        headline: "Copilot Kit - The Open-Source Copilot Framework",
        description:
            "Build, deploy, and operate fully custom AI Copilots. In-app AI chatbots, AI agents, AI Textareas and more.",
        budget: 10000,
        keywords: "AI, chatbot, open-source, copilot, framework",
    },
    {
        id: "2",
        title: "EcoHome Essentials",
        url: "https://www.ecohomeessentials.com",
        headline: "Sustainable Living Made Easy",
        description:
            "Discover our eco-friendly products that make sustainable living effortless. Shop now for green alternatives!",
        budget: 7500,
        keywords: "eco-friendly, sustainable, green products, home essentials",
    },
    {
        id: "3",
        title: "TechGear Solutions",
        url: "https://www.techgearsolutions.com",
        headline: "Innovative Tech for the Modern World",
        description:
            "Find the latest gadgets and tech solutions. Upgrade your life with smart technology today!",
        budget: 12000,
        keywords: "tech, gadgets, innovative, modern, electronics",
    },
    {
        id: "4",
        title: "Global Travels",
        url: "https://www.globaltravels.com",
        headline: "Travel the World with Confidence",
        description:
            "Experience bespoke travel packages tailored to your dreams. Luxury, adventure, relaxation—your journey starts here.",
        budget: 20000,
        keywords: "travel, luxury, adventure, tours, global",
    },
    {
        id: "5",
        title: "FreshFit Meals",
        url: "https://www.freshfitmeals.com",
        headline: "Healthy Eating, Simplified",
        description:
            "Nutritious, delicious meals delivered to your door. Eating well has never been easier or tastier.",
        budget: 5000,
        keywords: "healthy, meals, nutrition, delivery, fit",
    },
];

Since we are using Radix UI to create base UI components that can be easily customized with TailwindCSS, create a utils.ts file within the lib folder and copy the following code snippet into the file.

//👉🏻 The lib folder now contains 3 files - data.ts, type.ts, util.ts
//👇🏻 Copy the code below into the "lib/util.ts" file.
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
    return twMerge(clsx(inputs));
}

export function randomId() {
    return Math.random().toString(36).substring(2, 15);
}

Navigate into the components folder and create three other folders within it.

cd components
mkdir app dashboard ui

The components/app folder will contain various components to be used within the application, while the dashboard folder contains the UI components for some elements.

The ui folder holds multiple UI elements created using Radix UI. Copy these elements within the project repository into the folder.

Congratulations! The ui folder should contain the necessary UI elements. Now, we can use them to create the various components needed within the application.

Creating the application UI components

Here, I'll walk you through creating the user interface for the application.

First, navigate to the app/page.tsx file and paste the following code snippet into it. This file renders an App component declared within the components/app folder.

"use client";
import { App } from "@/components/app/App";

export default function DashboardPage() {
    return <App />;
}

Create the App.tsx, CampaignForm.tsx, MainNav.tsx, and UserNav.tsx files within the components/app folder.

cd components/app
touch App.tsx CampaignForm.tsx MainNav.tsx UserNav.tsx

Copy the code snippet below into the App.tsx file.

"use client";
import { DEFAULT_CAMPAIGNS } from "@/lib/data";
import { Campaign } from "@/lib/types";
import { randomId } from "@/lib/utils";
import { Dashboard } from "../dashboard/Dashboard";
import { CampaignForm } from "./CampaignForm";
import { useState } from "react";
import _ from "lodash";

export function App() {
    //👇🏻 default segments
    const [segments, setSegments] = useState<string[]>([
        "Millennials/Female/Urban",
        "Parents/30s/Suburbs",
        "Seniors/Female/Rural",
        "Professionals/40s/Midwest",
        "Gamers/Male",
    ]);

    const [campaigns, setCampaigns] = useState<Campaign[]>(
        _.cloneDeep(DEFAULT_CAMPAIGNS)
    );

    //👇🏻 updates campaign list
    function saveCampaign(campaign: Campaign) {
        //👇🏻 newly created campaign
        if (campaign.id === "") {
            campaign.id = randomId();
            setCampaigns([campaign, ...campaigns]);
        } else {
            //👇🏻 existing campaign - search for the campaign and updates the campaign list
            const index = campaigns.findIndex((c) => c.id === campaign.id);
            if (index === -1) {
                setCampaigns([...campaigns, campaign]);
            } else {
                campaigns[index] = campaign;
                setCampaigns([...campaigns]);
            }
        }
    }

    const [currentCampaign, setCurrentCampaign] = useState<Campaign | undefined>(
        undefined
    );

    return (
        <div className='relative'>
            <CampaignForm
                segments={segments}
                currentCampaign={currentCampaign}
                setCurrentCampaign={setCurrentCampaign}
                saveCampaign={(campaign) => {
                    if (campaign) {
                        saveCampaign(campaign);
                    }
                    setCurrentCampaign(undefined);
                }}
            />
            <Dashboard
                campaigns={campaigns}
                setCurrentCampaign={setCurrentCampaign}
                segments={segments}
                setSegments={setSegments}
            />
        </div>
    );
}

From the code snippet above,
- I created a list of default segments for the campaign and made a deep copy of the already defined campaign list.
- The saveCampaign function accepts a campaign as a parameter. If the campaign does not have an ID, it means it is newly created, so it adds it to the campaign list. Otherwise, it finds the campaign and updates its attributes.
- The Dashboard and the CampaignForm components accept the segments and the campaigns as props.

The Dashboard component displays various UI elements on the dashboard, while the CampaignForm component enables users to create and save a new campaign in the application.

You can also update the dashboard and app components using the code snippets from the GitHub repository.

Congratulations! You should have a working web application that allows users to view and create new campaigns.

In the upcoming section, you'll learn how to add CopilotKit to the application to analyze and make decisions based on the goals and budget of each campaign.

Analyzing ad campaigns with AI using CopilotKit

Here, you'll learn how to add AI to the application to help you analyze your campaigns and make the best decisions.

Before we proceed, visit the OpenAI Developers' Platform and create a new secret key.

Create a .env.local file and copy the your newly created secret key into the file.

OPENAI_API_KEY=<YOUR_OPENAI_SECRET_KEY>
OPENAI_MODEL=gpt-4-1106-preview

Next, you need to create an API endpoint for CopilotKit. Within the Next.js app folder, create an api/copilotkit folder containing a route.ts file.

cd app
mkdir api && cd api
mkdir copilotkit && cd copilotkit
touch route.ts

Copy the code snippet below into the route.ts file. The CopilotKit backend accept users’ requests and make decisions using the OpenAI model.

import { CopilotBackend, OpenAIAdapter } from "@copilotkit/backend";

export const runtime = "edge";

export async function POST(req: Request): Promise<Response> {
    const copilotKit = new CopilotBackend({});
    const openaiModel = process.env["OPENAI_MODEL"];

    return copilotKit.response(req, new OpenAIAdapter({ model: openaiModel }));
}

To connect your application to this API endpoint, update the app/page.tsx file as shown below:

"use client";
import { App } from "@/components/app/App";
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-ui";

export default function DashboardPage() {
    return (
        <CopilotKit url='/api/copilotkit/'>
            <CopilotSidebar
                instructions='Help the user create and manage ad campaigns.'
                defaultOpen={true}
                labels={{
                    title: "Campaign Manager Copilot",
                    initial:
                        "Hello there! I can help you manage your ad campaigns. What campaign would you like to work on?",
                }}
                clickOutsideToClose={false}
            >
                <App />
            </CopilotSidebar>
        </CopilotKit>
    );
}

The CopilotKit component wraps the entire application and accepts a url prop that contains a link to the API endpoint. The CopilotSidebar component adds a chatbot sidebar panel to the application, enabling us to provide various instructions to CopilotKit.

How to enable the AI copilot to perform various actions

CopilotKit provides two hooks that enable us to handle user's request and plug into the application state: useCopilotAction and useMakeCopilotReadable.

The useCopilotAction hook allows you to define actions to be carried out by CopilotKit. It accepts an object containing the following parameters:

name - the action's name.
description - the action's description.
parameters - an array containing the list of the required parameters.
render - the default custom function or string.
handler - the executable function that is triggered by the action.

useCopilotAction({
    name: "sayHello",
    description: "Say hello to someone.",
    parameters: [
        {
            name: "name",
            type: "string",
            description: "name of the person to say greet",
        },
    ],
    render: "Process greeting message...",
    handler: async ({ name }) => {
        alert(`Hello, ${name}!`);
    },
});

The useMakeCopilotReadable hook provides the application state to CopilotKit.

import { useMakeCopilotReadable } from "@copilotkit/react-core";

const appState = ...;
useMakeCopilotReadable(JSON.stringify(appState));

CopilotKit also allows you to provide context to the user's prompt, enabling it to make adequate and precise decisions.

Add a guidance.ts and a script.ts to the lib folder within your project, and copy this guidance and script suggestions into the file to enable CopilotKit make decisions.

Within the App component, pass the current date, script suggestions, and guidance into CopilotKit.

import { GUIDELINE } from "@/lib/guideline";
import { SCRIPT_SUGGESTION } from "@/lib/script";
import {
    useCopilotAction,
    useMakeCopilotReadable,
} from "@copilotkit/react-core";

export function App() {
    //-- 👉🏻 ...other component functions

    //👇🏻 Ground the Copilot with domain-specific knowledge for this use-case: marketing campaigns.
    useMakeCopilotReadable(GUIDELINE);
    useMakeCopilotReadable(SCRIPT_SUGGESTION);

    //👇🏻 Provide the Copilot with the current date.
    useMakeCopilotReadable("Today's date is " + new Date().toDateString());

    return (
        <div className='relative'>
            <CampaignForm
                segments={segments}
                currentCampaign={currentCampaign}
                setCurrentCampaign={setCurrentCampaign}
                saveCampaign={(campaign) => {
                    if (campaign) {
                        saveCampaign(campaign);
                    }
                    setCurrentCampaign(undefined);
                }}
            />
            <Dashboard
                campaigns={campaigns}
                setCurrentCampaign={setCurrentCampaign}
                segments={segments}
                setSegments={setSegments}
            />
        </div>
    );
}

Create a CopilotKit action within the App component that creates a new campaign or edits an existing one when the user provides such instruction.

useCopilotAction({
    name: "updateCurrentCampaign",
    description:
        "Edit an existing campaign or create a new one. To update only a part of a campaign, provide the id of the campaign to edit and the new values only.",
    parameters: [
        {
            name: "id",
            description:
                "The id of the campaign to edit. If empty, a new campaign will be created",
            type: "string",
        },
        {
            name: "title",
            description: "The title of the campaign",
            type: "string",
            required: false,
        },
        {
            name: "keywords",
            description: "Search keywords for the campaign",
            type: "string",
            required: false,
        },
        {
            name: "url",
            description:
                "The URL to link the ad to. Most of the time, the user will provide this value, leave it empty unless asked by the user.",
            type: "string",
            required: false,
        },
        {
            name: "headline",
            description:
                "The headline displayed in the ad. This should be a 5-10 words",
            type: "string",
            required: false,
        },
        {
            name: "description",
            description:
                "The description displayed in the ad. This should be a short text",
            type: "string",
            required: false,
        },

        {
            name: "budget",
            description: "The budget of the campaign",
            type: "number",
            required: false,
        },
        {
            name: "objective",
            description: "The objective of the campaign",
            type: "string",
            enum: [
                "brand-awareness",
                "lead-generation",
                "sales-conversion",
                "website-traffic",
                "engagement",
            ],
        },

        {
            name: "bidStrategy",
            description: "The bid strategy of the campaign",
            type: "string",
            enum: ["manual-cpc", "cpa", "cpm"],
            required: false,
        },
        {
            name: "bidAmount",
            description: "The bid amount of the campaign",
            type: "number",
            required: false,
        },
        {
            name: "segment",
            description: "The segment of the campaign",
            type: "string",
            required: false,
            enum: segments,
        },
    ],
    handler: (campaign) => {
        const newValue = _.assign(
            _.cloneDeep(currentCampaign),
            _.omitBy(campaign, _.isUndefined)
        ) as Campaign;

        setCurrentCampaign(newValue);
    },
    render: (props) => {
        if (props.status === "complete") {
            return "Campaign updated successfully";
        } else {
            return "Updating campaign";
        }
    },
});

Add another action that simulates an API call to allow CopilotKit to retrieve historical data from previously created campaigns.

// Provide this component's Copilot with the ability to retrieve historical cost data for certain keywords.
// Will be called automatically when needed by the Copilot.
useCopilotAction({
    name: "retrieveHistoricalData",
    description: "Retrieve historical data for certain keywords",
    parameters: [
        {
            name: "keywords",
            description: "The keywords to retrieve data for",
            type: "string",
        },
        {
            name: "type",
            description: "The type of data to retrieve for the keywords.",
            type: "string",
            enum: ["CPM", "CPA", "CPC"],
        },
    ],
    handler: async ({ type }) => {
        // fake an API call that retrieves historical data for cost for certain keywords based on campaign type (CPM, CPA, CPC)
        await new Promise((resolve) => setTimeout(resolve, 2000));

        function getRandomValue(min: number, max: number) {
            return (Math.random() * (max - min) + min).toFixed(2);
        }

        if (type == "CPM") {
            return getRandomValue(0.5, 10);
        } else if (type == "CPA") {
            return getRandomValue(5, 100);
        } else if (type == "CPC") {
            return getRandomValue(0.2, 2);
        }
    },
    render: (props) => {
        // Custom in-chat component rendering. Different components can be rendered based on the status of the action.
        let label = "Retrieving historical data ...";
        if (props.args.type) {
            label = `Retrieving ${props.args.type} for keywords ...`;
        }
        if (props.status === "complete") {
            label = `Done retrieving ${props.args.type} for keywords.`;
        }

        const done = props.status === "complete";
        return (
            <div className=''>
                <div className=' w-full relative max-w-xs'>
                    <div className='absolute inset-0 h-full w-full bg-gradient-to-r from-blue-500 to-teal-500 transform scale-[0.80] bg-red-500 rounded-full blur-3xl' />
                    <div className='relative shadow-xl bg-gray-900 border border-gray-800  px-4 py-8 h-full overflow-hidden rounded-2xl flex flex-col justify-end items-start'>
                        <h1 className='font-bold text-sm text-white mb-4 relative z-50'>
                            {label}
                        </h1>
                        <p className='font-normal text-base text-teal-200 mb-2 relative z-50 whitespace-pre'>
                            {props.args.type &&
                                `Historical ${props.args.type}: ${props.result || "..."}`}
                        </p>
                    </div>
                </div>
            </div>
        );
    },
});

Congratulations! You've completed the project for this tutorial.

Conclusion

If you need to build an AI product or integrate an AI tool into your software applications, you should consider CopilotKit.

You can find the source code for this tutorial on GitHub:

https://github.com/CopilotKit/campaign-manager-demo

Thank you for reading!