Get started with Server Workers in 10 minutes

This quickstart guide will take you from an empty project to a server worker which can interact with your Jazz application.

• You'll get the most out of this guide if you complete the frontend quickstart guide first.
• If you've already completed the frontend quickstart, you can skip straight to extending your schema.

#Create your Next.js App

We'll be using Next.js for simplicity, but you can use any framework you like.

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

#Install Jazz

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

#Set your 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

We're going to define a simple schema for our server worker. We'll use the root on the worker to store a list of bands. We're also going to add a migration to initialise the root if it doesn't exist.

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

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

export const BandList = co.list(Band);

export const JazzFestWorkerAccount = co
  .account({
    root: co.map({
      bandList: BandList,
    }),
    profile: co.profile(),
  })
  .withMigration((account) => {
    if (!account.$jazz.has("root")) {
      account.$jazz.set("root", {
        bandList: [],
      });
      account.root?.$jazz.owner.makePublic();
    }
  });

#Create a Server Worker

Jazz provides a CLI to create server workers. You can create a server worker using the following command:

You can copy the output of this command and paste it directly into your .env file:

#Defining your HTTP request schema

Next, we're going to set up an HTTP request schema to define our request and response. Here, we tell Jazz that we will send a Band under the key band and expect a bandList in response, which is a list of Bands.

We also need to tell Jazz which keys should be treated as loaded in the request and response using the resolve query.

#Configure your Server Worker

We're going to use the startWorker function to start our server worker, and register a POST handler, which will listen for the requests being sent to our server worker.

We'll also use a resolve query here to make sure that the bandList is loaded on the worker's root.

#Start your server worker

We can now start our development server to make sure everything is working.

If you open your browser, you should see the default Next.js welcome page.

#Not working?

• Check you set up your .env file correctly with NEXT_PUBLIC_ where necessary

• Check you're importing startWorker from jazz-tools/worker

#Send requests to your server worker

#Creating a Jazz Client

If you already have a working provider from the frontend quickstart, you can skip this step.

We're going to wrap our Next.js app in a JazzReactProvider so that we can use Jazz on our client.

#Creating your page component

We're going to send a request to our server worker to announce a new band. Our worker will respond with a list of bands that we can display on our page.

#Try it out!

Your browser should now be showing you a page with an input field and a button. If you enter a band name and click the button, your server worker will receive the request and add the band to the list.

Congratulations! 🎉 You've just built your first Jazz server worker!

This simple pattern is the foundation for building powerful, real-time applications.

Here are some ideas about what you could use your server worker for:

• integrating with payment providers
• sending emails/SMSes
• gathering data from external APIs
• managing authoritative state

Looking forward to seeing what you build!

#Next steps

• Complete the front-end quickstart to learn more about how to build real-time UIs using Jazz
• Find out how to handle errors gracefully in your server worker
• Learn how to share and collaborate on data in groups with complex permissions