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're going to use a bare-bones Vite + TS app to get started. This allows us to import modules easily and allows us to use TypeScript from the start. It's not strictly necessary to use Vite and TypeScript, but this gives the minimal set-up for a modern web development workflow, and we strongly recommend it.

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.

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: [],
      });
    }
  });

#Create a Jazz context

Jazz needs to have a 'context' in order to run. Once created, you can use Jazz to create, read, and update data. You can delete all the boilerplate in the src/main.ts file and replace it with the code below:

#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 a blank page!

#Not loading?

If you're not seeing the welcome page:

#Create data

Let's create a simple form to add a new band to the festival. We'll use the getCurrentAccount function we defined above to get the current account. Then, we'll load it using our custom schema and trigger the migration manually.

#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.

#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