Get started with Jazz in 10 minutes

This quickstart guide will take you from an empty project to a working app with a simple data model and components to create and display your data.

#Create your App

We'll be using Next.js and TypeScript with pnpm for this guide, but Jazz works great with vanilla React too.

You can accept the defaults for all the questions, or customise the project as you like.

Note: Requires Node.js 20+

#Install Jazz

The jazz-tools package includes everything you're going to need to build your first Jazz app.

#Get your free API key

Sign up for a free API key at dashboard.jazz.tools for higher limits or production use, or use your email address as a temporary key to get started quickly.

#Define your schema

Jazz uses Zod for more simple data types (like strings, numbers, booleans), and its own schemas to create collaborative data structures known as CoValues. CoValues are automatically persisted across your devices and the cloud and synced in real-time. Here we're defining a schema made up of both Zod types and CoValues.

Adding a root to the user's account gives us a container that can be used to keep a track of all the data a user might need to use the app. The migration runs when the user logs in, and ensures the account is properly set up before we try to use it.

import { co, z } from "jazz-tools";

export const Band = co.map({
  name: z.string(), // Zod primitive type
});

export const Festival = co.list(Band);

export const JazzFestAccountRoot = co.map({
  myFestival: Festival,
});

export const JazzFestAccount = co
  .account({
    root: JazzFestAccountRoot,
    profile: co.profile(),
  })
  .withMigration((account) => {
    if (!account.$jazz.has('root')) {
      account.$jazz.set('root', {
        myFestival: [],
      });
    }
  });

#Add the Jazz Provider

Wrap your app with a provider so components can use Jazz.

"use client"; // tells Next.js that this component can't be server-side rendered. If you're not using Next.js, you can remove it.
import { JazzReactProvider } from "jazz-tools/react";
import { JazzFestAccount } from "@/app/schema";

const apiKey = process.env.NEXT_PUBLIC_JAZZ_API_KEY;

export function JazzWrapper({ children }: { 
  children: React.ReactNode 
}) {
  return (
    <JazzReactProvider
      sync={{ 
        peer: `wss://cloud.jazz.tools/?key=${apiKey}` 
      }}
      AccountSchema={JazzFestAccount}
    >
      {children}
    </JazzReactProvider>
  );
}

#Start your app

Moment of truth — time to start your app and see if it works.

If everything's going according to plan, you should see the default Next.js welcome page!

#Not loading?

If you're not seeing the welcome page:

• Check you wrapped your app with the Jazz Provider in app/layout.tsx
• Check your schema is properly defined in app/schema.ts

#Create data

Let's create a simple form to add a new band to the festival. We'll use the useAccount hook to get the current account and tell Jazz to load the myFestival CoValue by passing a resolve query.

#Display your data

Now we've got a way to create data, so let's add a component to display it.

#Put it all together

You've built all your components, time to put them together.

You should now be able to add a band to your festival, and see it appear in the list!

Congratulations! 🎉 You've built your first Jazz app!

You've begun to scratch the surface of what's possible with Jazz. Behind the scenes, your local-first JazzFest app is already securely syncing your data to the cloud in real-time, ready for you to build more and more powerful features.

Psst! Got a few more minutes and want to add Server Side Rendering to your app? We've got you covered!

#Next steps

• Add authentication to your app so that you can log in and view your data wherever you are!
• Dive deeper into the collaborative data structures we call CoValues
• Learn how to share and collaborate on data using groups and permissions
• Complete the server-side quickstart to learn more about Jazz on the server