Tools - Next.js Starter Kit

The Next.js Starter Kit is an open-source template that showcases all aspects of Liveblocks in a single, modern application.

Features

The Next.js Starter Kit includes the following

• Documents dashboard with pagination, drafts, groups, auto-revalidation
• Collaborative whiteboard app with a fully-featured share menu
• Authentication compatible with GitHub, Google, Auth0, and more
• Document permissions can be scoped to users, groups, and the public

Set up the Next.js Starter Kit

create-liveblocks-app

You can get started by running the following command:

$npx create-liveblocks-app@latest --next

This will run an installer that allows you to download, configure, and deploy, your project:

Give your project a name, and select the authentication method you’d like to use in your app. If you are trying to generate a proof of concept quickly, opting to use demo authentication may be a great option—you can still add other authentication providers later on.

Deploy with Vercel Integration

If you would like to set up CI/CD with your application, we’ve made that process straightforward for you as well. When prompted, you can select "deploy to Vercel" to enable building and deploying the starter kit. The Vercel Integration will open in a new browser window for you to complete the process of adding your repository.

If by clicking "Create" you receive "An unexpected internal error occurred" you should validate within your code hosting platform of choice (GitHub, GitLab, Bitbucket) that the Vercel integration has permission to access your repository. In GitHub, permissions can be found can be found under Settings > Integrations > Vercel.

Connect to Liveblocks and retrieve your secret key

If you prefer to work locally, you can tell the installer you would not like to "deploy to Vercel." After declining the deployment option, the installer will prompt adding your Liveblocks Key to the application automatically. If you forwent deployment or indicated that you would like to get your Liveblocks secret key automatically, the Liveblocks integration page will open in a new browser tab. Once the integration page appears, you can sign up/sign in to Liveblocks, create a new project, and import your API key into the installer.

After finishing up, check the installer and follow the commands recommended to get you started.

Authentication

The Liveblocks starter kit uses NextAuth.js for authentication, meaning many authentication providers can be configured with minimal code changes. A demo authentication system is used by default, but it’s easy to add real providers, such as GitHub, Auth0, and more.

Take a look at the guide for your chosen authentication method:

• GitHub authentication
• Auth0 authentication
• Demo authentication

GitHub authentication

To use GitHub auth, make sure you selected "GitHub authentication" when running the installer (or you’ve set up the provider manually). This is how to set up your GitHub secret key and client id.

1. Go to Developer Settings on GitHub and click "New GitHub App".
2. Enter an app name (e.g. Liveblocks Starter Kit (dev)). You’ll need a new app for each environment, so it’s helpful to place "dev" in the name.
3. Add a homepage URL—this isn’t important now, so a placeholder will do.
4. Find the "Callback URL" input just below, and add your local development URL (e.g. http://localhost:3000).
5. Look for the "Webhook" section and make sure to uncheck "Active".
6. Use the remaining default settings and press "Create GitHub App".

7. On the next page under "Client secrets", press the "Generate a new client secret" button (note that this is different to generating a private key!).
8. Copy this secret into the /.env.local file as GITHUB_CLIENT_SECRET
9. Go back to the previous page and find the "Client ID" near the top. Copy this into your .env.local file as GITHUB_CLIENT_ID

Almost there! .env.local should now contain lines similar to this:

GITHUB_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXGITHUB_CLIENT_ID=XXXXXXXXXXXXXXXXXXXX

GitHub authentication is now complete! Next, add yourself as a user to test out your authentication.

Auth0 authentication

To use Auth0 auth, make sure you selected "Auth0 authentication" when running the installer (or you’ve set up the provider manually). This is how to set up your Auth0 secret key and client information.

1. Go to your Auth0 Dashboard and click "Create Application".
2. Enter an app name (e.g. Liveblocks Starter Kit (dev)). You’ll need a new app for each environment, so it’s helpful to place "dev" in the name.
3. Select "Single Page Web Applications", and press "Create".
4. Copy your "Client ID" from the top of the page, and place it within .env.local as AUTH0_CLIENT_ID.
5. Click the "Settings" tab— we’ll be making a number of changes here.
6. Find the "Client Secret" input field, and copy the value into .env.local as AUTH0_CLIENT_SECRET.
7. Copy your "Domain" from the input field, add "https://" to the start, and place it within .env.local as AUTH0_ISSUER_BASE_URL.
8. Add the following to the "Allowed Callback URLs" textarea: http://localhost:3000/api/auth/callback/auth0.
9. Add the following to the "Allowed Logout URLs" textarea: http://localhost:3000.
10. Scroll to the bottom and press "Save changes".

.env.local should now contain these three lines, along with anything previously there:

AUTH0_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXAUTH0_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXAUTH0_ISSUER_BASE_URL=https://XXXXXXXXXXXXXXXXXX.com

Auth0 authentication is now set up! Next, add yourself a user to test out your authentication.

Demo authentication

For quickly testing out your app, the demo authentication method can be used. This method uses a NextAuth CredentialsProvider to simulate a real sign in system. To replace it with your own authentication method, you can add any other NextAuth Provider to /auth.config.ts.

Read the next section to learn how to add a new user to your demo application.

How to sign up - add yourself as a user

We haven’t set up a database, so we’re temporarily using the /data folder instead. Before any user can sign in, they need to be added to /data/users.ts. Navigate there and add your details, for example, if you’re signing in with yourname@example.com:

{  id: "yourname@example.com",  name: "Your Name",  avatar: "https://liveblocks.io/avatars/avatar-0.png",  groupIds: ["product", "engineering", "design"],},

Note that this is replacing the sign-up process, so you must enter the email of any new user. If, for example, you’re using GitHub authentication, you can enter the email address of any valid GitHub account.

Ready to go

The Next.js Starter Kit is now ready to use! After setting up authentication, make sure to restart the dev server to see your authentication in action.

$npm run dev

Assorted info

Structure

The starter kit has the following structure:

appcomponentsdataiconslayoutslib └─ actions └─ database └─ hooks └─ utilsprimitivesstylestypesauth.tsauth.config.tsliveblocks.config.tsliveblocks.server.config.tspackage.json

The important thing to note is that there are primitives, which are base level components such as buttons (think of these as the small building blocks of a page), components, which you can think of as multiplayer implementations (cursors, badges, etc), app, which renders document level experiences and a library (lib) of both server side and client side methods which contain the logic to create and modify documents.

Async fetching and error handling

This starter kit makes extensive use of the following programming pattern for fetching async resources:

const { data, error } = await getDocument({  /* ... */});
// An error has occuredif (error) {  // { code: 400, message: "Document not found", suggestion: "Please check the URL is..." }  console.log(error);  return;}
// Success, but result is emptyif (!data) {  return;}
// Success// { name: "my-document", id: "hIas7GuihgHF8Fhv8Sskg",  ... }console.log(data);

Document functions

Much of the starter kit’s power is in the /lib/actions directory. The functions in these files allow you to edit your documents easily and return type-safe objects. For example in an API endpoint:

import { createDocument } from "@/lib/actions";
export async function POST() {  // Create a new document  const { data, error } = await createDocument({    name: "My document",    type: "whiteboard",    userId: "charlie.layne@example.com",  });
  // ...}

Because these functions are server actions, they can be leveraged on both client and server.

import { createDocument } from "@/lib/actions";
export function CreateDocumentButton() {  async function handleCreateDocument() {    // Create a new document    const { data, error } = await createDocument({      name: "My document",      type: "whiteboard",      userId: "charlie.layne@example.com",    });  }
  return <button onClick={handleCreateDocument}>New document</button>;}

Functions that return data can be used with SWR hooks that automatically update your data in components. For example, getDocumentUsers returns a list of users with access to the room:

// Convert from thisconst { data, error } = await getDocumentUsers({  documentId: "my-document-id",});
// To thisconst { data, error } = useDocumentsFunctionSWR([  getDocumentUsers,  {    documentId: "my-document-id",  },]);

Here’s a working example:

import { getDocumentUsers, useDocumentsFunctionSWR } from "../../lib/client";
export function ListUsers() {  // Get users attached to a document and update every 1000ms  const { data: users, error: usersError } = useDocumentsFunctionSWR(    [      getDocumentUsers,      {        documentId: "my-document-id",      },    ],    { refreshInterval: 1000 }  );
  if (usersError) {    return <div>Error</div>;  }
  if (!users) {    return <div>Loading...</div>;  }
  return (    <ul>      {users.map((user) => (        <li>user.name</li>      ))}    </ul>  );}

How to extend the Document type

If you’d like to add a new property to Document, it’s simple. First, edit the Document type in /types/documents.ts:

export type Document = {  // Your new property  randomNumber: number;  //...};

Then modify the return value in /lib/utils/buildDocuments.ts. This is a function that converts a Liveblocks room into your custom document format:

// Return our custom Document formatconst document: Document = {  randomNumber: Math.random(),  // ...};

Next, run the following command to check for problems:

$npm run typecheck

If no errors are returned, the document properties were successfully extended.

How to extend the User & Session type

Similar to the way we extend the Document type, we can also extend the User and Session type.

Adding a new property to User/Session is simple. First, edit the User type in /types/data.ts.

export type User = {  // Your new property  randomNumber: number;  // ...};

Then make sure to return this new property in /lib/database/getUser.ts.

return { randomNumber: Math.random() /* ... */ };

The new property will now be available to use in your app:

// randomNumber: Math.random(),console.log(session.user.info.randomNumber);

Adding this to your Liveblocks app (optional)

Liveblocks presence is a way of displaying online presence between users, helpful for live avatars, realtime cursors, etc., and it’s possible to attach a properties to it for each user. To make a property accessible in presence (and within the React hooks used in whiteboard), you must modify UserInfo in /liveblocks.config.ts.

export type UserInfo = Pick<User, "randomNumber" /* ... */>;

In this example Pick creates the UserInfo type based off of the User type and adds additional keys based on the properties you provide. After this, modify /lib/actions/authorizeLiveblocks.ts. First, we’ll give an anonymous user a property:

// Anonymous user infoconst anonymousUser: User = {  randomNumber: Math.random(),  // ...};

Next, we’ll get the signed-in user’s property:

// Get current user info from session (defined in /auth.config.ts)// If no session found, this is a logged out/anonymous userconst {  randomNumber,  // ...} = session?.user.info ?? anonymousUser;

And then pass this info to authorize:

// Get Liveblocks access tokenconst { data, error } = await authorize({  userInfo: { randomNumber /* ... */ },  // ...});

To make sure to check everything’s hooked up correctly:

$npm run typecheck

Once that’s working, the new property can then be used in your app:

// My random numberconst myRandomNumber = useSelf((me) => me.info.randomNumber);
// An array of everyone else’s random numbersconst everyonesRandomNumbers = useOthersMapped(  (other) => other.info.randomNumber);

Adding multiple authentication providers

It’s possible to add multiple authentication providers to the starter kit using NextAuth Providers. Open /auth.config.ts and place your providers in the object:

import GithubProvider from "next-auth/providers/github";import Auth0Provider from "next-auth/providers/auth0";
export const authOptions = {  // ...  providers: {    GithubProvider({      clientId: process.env.GITHUB_CLIENT_ID as string,      clientSecret: process.env.GITHUB_CLIENT_SECRET as string,    }),    Auth0Provider({      clientId: process.env.AUTH0_CLIENT_ID as string,      clientSecret: process.env.AUTH0_CLIENT_SECRET as string,      issuer: process.env.AUTH0_ISSUER_BASE_URL as string,    }),  }};

It’s not only possible with GitHub and Auth0, any NextAuth provider will work, such as Google, X, Reddit, or more. You can find more information about getting the necessary secrets on the NextAuth documentation, or on the provider’s website.

Note that if you’re using CredentialsProvider (for example, as used in the demo authentication), CredentialsProvider must be removed before any other authentication methods will appear.

Switching themes

The starter kit comes with both a dark mode and light mode. By default, the user sees the theme that corresponds to their system setting, but it’s easy to switch your whole app to just dark or light mode by modifying styles/globals.css.

• To use only light mode, remove the entire @media (prefers-color-scheme: dark) media query.
• To use only dark mode, copy the "Dark mode" CSS variables into the "Light mode" section, then remove the entire @media (prefers-color-scheme: dark) media query.

Adding a database

To add a database you need to modify the following async functions to return the correct properties:

• /lib/database/getGroup.ts
• /lib/database/getGroups.ts
• /lib/database/getUser.ts

You can then remove the /data folder. Everything else should work as expected.