// old { issue.title = event.target.value }}/>

{ issue.description = event.target.value }}/>
            <label className="flex">
                Estimate:
                <input type="number" className="text-right min-w-0"
                    value={issue.estimate}
                    onChange={(event) => { issue.estimate = Number(event.target.value) }}/>
            </label>
            <select
                value={issue.status}
                onChange={(event) => {
                    issue.status = event.target.value as "backlog" | "in progress" | "done"
                }}
            >
                <option value="backlog">Backlog</option>
                <option value="in progress">In Progress</option>
                <option value="done">Done</option>
            </select>
        </div> // old
    ); // old
} // old
```
</CodeGroup>

<div className="text-xs uppercase text-stone-400 dark:text-stone-600 tracking-wider -mb-3">
    Preview
</div>

🏁 Now you should be able to edit the issue after creating it!

You'll immediately notice that we're doing something non-idiomatic for React: we mutate the issue directly, by assigning to its properties.

This works because CoValues

-   intercept these edits
-   update their local view accordingly (React doesn't really care after rendering)
-   notify subscribers of the change (who will receive a fresh, updated view of the CoValue)

<aside className="text-sm border border-stone-300 dark:border-stone-700 rounded px-4 my-4 max-w-3xl [&_pre]:mx-0">
    <h4 className="not-prose text-base py-2 mb-3 px-4 border-b border-stone-300 dark:border-stone-700">💡 A Quick Overview of Subscribing to CoValues</h4>

There are three main ways to subscribe to a CoValue:

1.  Directly on an instance:

<CodeGroup>
        ```ts
        const unsub = issue.subscribe([], (updatedIssue) => console.log(updatedIssue));
        ```
  </CodeGroup>

2.  If you only have an ID (this will load the issue if needed):

<CodeGroup>
        ```ts
        const unsub = Issue.subscribe(issueID, me, [], (updatedIssue) => {
            console.log(updatedIssue);
        });
        ```
  </CodeGroup>

3.  If you're in a React component, to re-render reactively:

`tsx
        const issue = useCoState(Issue, issueID);
        `

By the way, `useCoState` is basically just an optimized version of
  <CodeGroup>
            ```ts
            function useCoState<V extends CoValue>(Schema: CoValueClass<V>, id?: ID<V>): V | undefined {
                const [value, setValue] = useState<V>();

useEffect(() => Schema.subscribe(id, [], setValue), [id]);

return value;
            }
            ```
  </CodeGroup>

</aside>

We have one subscriber on our Issue, with `useCoState` in `src/App.tsx`, which will cause the `App` component and its children **to** re-render whenever the Issue changes.

### Automatic local & cloud persistence

So far our Issue CoValues just looked like ephemeral local state. We'll now start exploring the first main feature that makes CoValues special: **automatic persistence.**

Actually, all the Issue CoValues we've created so far **have already been automatically persisted** to the cloud and locally - but we lose track of their ID after a reload.

So let's store the ID in the browser's URL and make sure our useState is in sync with that.

<CodeGroup>
{/* prettier-ignore */}
```tsx
// old
function App() { // old
    const [issueID, setIssueID] = useState<ID<Issue> | undefined>(
        (window.location.search?.replace("?issue=", "") || undefined) as ID<Issue> | undefined,
    );
    // old
    const issue = useCoState(Issue, issueID); // old
    // old
    const createIssue = () => {// old
        const newIssue = Issue.create(// old
            { // old
                title: "Buy terrarium", // old
                description: "Make sure it's big enough for 10 snails.", // old
                estimate: 5, // old
                status: "backlog", // old
            }, // old
        ); // old
        setIssueID(newIssue.id); // old
        window.history.pushState({}, "", `?issue=${newIssue.id}`);
    }; // old
    // old
    if (issue) { // old
        return <IssueComponent issue={issue} />; // old
    } else { // old
        return <button onClick={createIssue}>Create Issue</button>; // old
    } // old
} // old
// old
export default App; // old
```
</CodeGroup>

🏁 Now you should be able to create an issue, edit it, reload the page, and still see the same issue.

### Remote sync

To see that sync is also already working, try the following:

-   copy the URL to a new tab in the same browser window and see the same issue
-   edit the issue and see the changes reflected in the other tab!

This works because we load the issue as the same account that created it and owns it (remember how you set `{ owner: me }`).

But how can we share an Issue with someone else?

### Simple public sharing

We'll learn more about access control in "Groups & Permissions", but for now let's build a super simple way of sharing an Issue by just making it publicly readable & writable.

All we have to do is create a new group to own each new issue and add "everyone" as a "writer":

<CodeGroup>
{/* prettier-ignore */}
```tsx
// old
function App() { // old
    const { me } = useAccount(); // old
    const [issueID, setIssueID] = useState<ID<Issue> | undefined>(// old
        (window.location.search?.replace("?issue=", "") || undefined) as ID<Issue> | undefined,// old
    ); // old
    // old
    const issue = useCoState(Issue, issueID); // old
    // old
    const createIssue = () => { // old
        const group = Group.create({ owner: me });
        group.addMember("everyone", "writer");
        // old
        const newIssue = Issue.create( // old
            { // old
                title: "Buy terrarium", // old
                description: "Make sure it's big enough for 10 snails.", // old
                estimate: 5, // old
                status: "backlog", // old
            }, // old
            { owner: group },
        ); // old
        setIssueID(newIssue.id); // old
        window.history.pushState({}, "", `?issue=${newIssue.id}`); // old
    }; // old
    // old
    if (issue) { // old
        return <IssueComponent issue={issue} />; // old
    } else { // old
        return <button onClick={createIssue}>Create Issue</button>; // old
    } // old
} // old
// old
export default App; // old
```
</CodeGroup>

🏁 Now you should be able to open the Issue (with its unique URL) on another device or browser, or send it to a friend and you should be able to **edit it together in realtime!**

This concludes our intro to the essence of CoValues. Hopefully you're starting to have a feeling for how CoValues behave and how they're magically available everywhere.

## Refs & auto-subscribe

Now let's have a look at how to compose CoValues into more complex structures and build a whole app around them.

Let's extend our two data model to include "Projects" which have a list of tasks and some properties of their own.

Using plain objects, you would probably type a Project like this:

<CodeGroup>
```ts
type Project = {
    name: string;
    issues: Issue[];
};
```
</CodeGroup>

In order to create this more complex structure in a fully collaborative way, we're going to need _references_ that allow us to nest or link CoValues.

Add the following to `src/schema.ts`:

<CodeGroup>
```ts
// old
export class Issue extends CoMap { // old
    title = co.string; // old
    description = co.string; // old
    estimate = co.number; // old
    status? = co.literal("backlog", "in progress", "done"); // old
} // old
// old
export class ListOfIssues extends CoList.Of(co.ref(Issue)) {}

export class Project extends CoMap {
    name = co.string;
    issues = co.ref(ListOfIssues);
}
```
</CodeGroup>

Now let's change things up a bit in terms of components as well.

First, we'll change `App.tsx` to create and render `Project`s instead of `Issue`s. (We'll move the `useCoState` into the `ProjectComponent` we'll create in a second).

<CodeGroup>
{/* prettier-ignore */}
```tsx
// old
function App() { // old
    const [projectID, setProjectID] = useState<ID<Project> | undefined>(
        (window.location.search?.replace("?project=", "") || undefined) as ID<Project> | undefined
    );
    // old
    const issue = useCoState(Issue, issueID); // *bin*
    // old
    const createProject = () => {
        const group = Group.create();
        group.addMember("everyone", "writer");

Now we'll actually create the `ProjectComponent` that renders a `Project` and its `Issue`s.

Create a new file `src/components/Project.tsx` and add the following:

<CodeGroup>
{/* prettier-ignore */}
```tsx

export function ProjectComponent({ projectID }: { projectID: ID<Project> }) {
    const project = useCoState(Project, projectID);

const createAndAddIssue = () => {
        project?.issues?.push(Issue.create({
            title: "",
            description: "",
            estimate: 0,
            status: "backlog",
        },  project._owner));
    };

return project ? (
        <div>
            <h1>{project.name}</h1>
            <div className="border-r border-b">
                {project.issues?.map((issue) => (
                    issue && <IssueComponent key={issue.id} issue={issue} />
                ))}
                <button onClick={createAndAddIssue}>Create Issue</button>
            </div>
        </div>
    ) : (
        <div>Loading project...</div>
    );
}
```
</CodeGroup>

🏁 Now you should be able to create a project, add issues to it, share it, and edit it collaboratively!

Two things to note here:

-   We create a new Issue like before, and then push it into the `issues` list of the Project. By setting the `owner` to the Project's owner, we ensure that the Issue has the same access rights as the project itself.
-   We only need to use `useCoState` on the Project, and the nested `ListOfIssues` and each `Issue` will be **automatically loaded and subscribed to when we access them.**
-   However, because either the `Project`, `ListOfIssues`, or each `Issue` might not be loaded yet, we have to check for them being defined.

### Precise loading depths

The load-and-subscribe-on-access is a convenient way to have your rendering drive data loading (including in nested components!) and lets you quickly chuck UIs together without worrying too much about the shape of all data you'll need.

But you can also take more precise control over loading by defining a minimum-depth to load in `useCoState`:

<CodeGroup>
{/* prettier-ignore */}
```tsx
// old
export function ProjectComponent({ projectID }: { projectID: ID<Project> }) {// old
    const project = useCoState(Project, projectID, { issues: [{}] });

The loading-depth spec `{ issues: [{}] }` means "in `Project`, load `issues` and load each item in `issues` shallowly". (Since an `Issue` doesn't have any further references, "shallowly" actually means all its properties will be available).

-   Now, we can get rid of a lot of coniditional accesses because we know that once `project` is loaded, `project.issues` and each `Issue` in it will be loaded as well.
-   This also results in only one rerender and visual update when everything is loaded, which is faster (especially for long lists) and gives you more control over the loading UX.

{/* TODO: explain about not loaded vs not set/defined and `_refs` basics */}

## Groups & permissions

We've seen briefly how we can use Groups to give everyone access to a Project,
and how we can use `{ owner: me }` to make something private to the current user.

### Groups / Accounts as permission scopes

This gives us a hint of how permissions work in Jazz: **every CoValue has an owner,
and the access rights on that CoValue are determined by its owner.**

- If the owner is an Account, only that Account can read and write the CoValue.
 - If the owner is a Group, the access rights depend on the *role* of the Account (that is trying to access the CoValue) in that Group.
    - `"reader"`s can read but not write to CoValues belonging to the Group.
    - `"writer"`s can read and write to CoValues belonging to the Group.
    - `"admin"`s can read and write to CoValues belonging to the Group *and can add and remove other members from the Group itself.*

### Creating invites

There is also an abstraction for creating *invitations to join a Group* (with a specific role) that you can use
to add people without having to know their Account ID.

Let's use these abstractions to build teams for a Project that we can invite people to.

Turns out, we're already mostly there! First, let's remove making the Project public:

<CodeGroup>
{/* prettier-ignore */}
```tsx
// old
function App() { // old
    const [projectID, setProjectID] = useState<ID<Project> | undefined>( // old
        (window.location.search?.replace("?project=", "") || undefined) as ID<Project> | undefined, // old
    ); // old
    // old
    const createProject = () => { // old
        const group = Group.create(); // old
        group.addMember("everyone", "writer"); // *bin*
        // old
        const newProject = Project.create( // old
            { // old
                name: "New Project", // old
                issues: ListOfIssues.create([], { owner: group }) // old
            }, // old
            group, // old
        ); // old
        setProjectID(newProject.id); // old
        window.history.pushState({}, "", `?project=${newProject.id}`); // old
    }; // old
    // old
    if (projectID) { // old
        return <ProjectComponent projectID={projectID} />; // old
    } else { // old
        return <button onClick={createProject}>Create Project</button>; // old
    } // old
} // old
// old
export default App; // old
```
</CodeGroup>

Now, inside ProjectComponent, let's add a button to invite guests (read-only) or members (read-write) to the Project.

<CodeGroup>
{/* prettier-ignore */}
```tsx
// old

export function ProjectComponent({ projectID }: { projectID: ID<Project> }) {// old
    const project = useCoState(Project, projectID, { issues: [{}] }); // old

const invite = (role: "reader" | "writer") => {
        const link = createInviteLink(project, role, { valueHint: "project" });
        navigator.clipboard.writeText(link);
    };

### Consuming invites

#### Example apps

#### AI tools

# Using AI to build Jazz apps

AI tools, particularly large language models (LLMs), can accelerate your development with Jazz. Searching docs, responding to questions and even helping you write code are all things that LLMs are starting to get good at.

However, Jazz is a rapidly evolving framework, so sometimes AI might get things a little wrong.

To help the LLMs, we provide the Jazz documentation in a txt file that is optimized for use with AI tools, like Cursor.

## Setting up AI tools

Every tool is different, but generally, you'll need to either paste the contents of the [llms-full.txt](https://jazz.tools/llms-full.txt) file directly in your prompt, or attach the file to the tool.

### ChatGPT and v0

Upload the txt file in your prompt.

![ChatGPT prompt with llms-full.txt attached](/chatgpt-with-llms-full-txt.jpg)

### Cursor

1. Go to Settings > Cursor Settings > Features > Docs
2. Click "Add new doc"
3. Enter the following URL:

<CodeGroup>
```
https://jazz.tools/llms-full.txt
```
</CodeGroup>

## llms.txt convention

We follow the llms.txt [proposed standard](https://llmstxt.org/) for providing documentation to AI tools at inference time that helps them understand the context of the code you're writing.

## Limitations and considerations

AI is amazing, but it's not perfect. What works well this week could break next week (or be twice as good).

We're keen to keep up with changes in tooling to help support you building the best apps, but if you need help from humans (or you have issues getting set up), please let us know on [Discord](https://discord.gg/utDMjHYg42).

#### Inspector

# Jazz Inspector

[Jazz Inspector](https://inspector.jazz.tools) is a tool to visually inspect a Jazz account or other CoValues.

For now, you can get your account credentials from the `jazz-logged-in-secret` local storage key from within your Jazz app.

[https://inspector.jazz.tools](https://inspector.jazz.tools)

## Exporting current account to Inspector from your app

In development mode, you can launch the Inspector from your Jazz app to inspect your account by pressing `Cmd+J`.

## Embedding the Inspector widget into your app

Alternatively, you can embed the Inspector directly into your app, so you don't need to open a separate window.

Install the package.

<CodeGroup>
```sh
npm install jazz-inspector
```
</CodeGroup>

Render the component within your `JazzProvider`.

<CodeGroup>
```sh

Check out the [music player app](https://github.com/garden-co/jazz/blob/main/examples/music-player/src/2_main.tsx) for a full example.

### Project setup

#### Installation

### react-native Implementation

# React Native

Jazz requires an [Expo development build](https://docs.expo.dev/develop/development-builds/introduction/) using [Expo Prebuild](https://docs.expo.dev/workflow/prebuild/) for native code. It is **not compatible** with Expo Go. Jazz also supports the [New Architecture](https://docs.expo.dev/guides/new-architecture/).

Tested with:

<CodeGroup>
  ```json
  "expo": "~51.0.0",
  "react-native": "~0.74.5",
  "react": "^18.2.0",
  ```
</CodeGroup>

## Setup

### Create a new project

(skip this step if you already have one)

<CodeGroup>
  ```bash
  npx create-expo-app -e with-router-tailwind my-jazz-app
  cd my-jazz-app
  npx expo prebuild
  ```
</CodeGroup>

### Install dependencies

<CodeGroup>
  ```bash
  npx expo install expo-linking expo-secure-store expo-file-system @react-native-community/netinfo @bam.tech/react-native-image-resizer

npm i -S @azure/core-asynciterator-polyfill react-native-url-polyfill readable-stream react-native-get-random-values @craftzdog/react-native-buffer @op-engineering/op-sqlite

npm i -S jazz-tools jazz-react-native jazz-react-native-media-images

```
</CodeGroup>

> note: Hermes has added support for `atob` and `btoa` in React Native 0.74.  If you are using earlier versions, you may also need to polyfill `atob` and `btoa` in your `package.json` . Packages to try include `text-encoding` and `base-64`, and you can drop `@bacons/text-decoder`.

### Fix incompatible dependencies

<CodeGroup>
  ```bash
  npx expo install --fix
  ```
</CodeGroup>

### Install Pods

<CodeGroup>
  ```bash
  npx pod-install
  ```
</CodeGroup>

### Configure Metro

#### Regular repositories

If you are not working within a monorepo, create a new file metro.config.js in the root of your project with the following content:

<CodeGroup>
  ```ts
  const { getDefaultConfig } = require("expo/metro-config");
  const config = getDefaultConfig(projectRoot);
  config.resolver.sourceExts = ["mjs", "js", "json", "ts", "tsx"];
  config.resolver.requireCycleIgnorePatterns = [/(^|\/|\\)node_modules($|\/|\\)/];
  module.exports = config;
  ```
</CodeGroup>

#### Monorepos

For monorepos, use the following metro.config.js:

<CodeGroup>
  ```ts
  const { getDefaultConfig } = require("expo/metro-config");
  const { FileStore } = require("metro-cache");
  const path = require("path");

// eslint-disable-next-line no-undef
  const projectRoot = __dirname;
  const workspaceRoot = path.resolve(projectRoot, "../..");

const config = getDefaultConfig(projectRoot);

config.watchFolders = [workspaceRoot];
  config.resolver.nodeModulesPaths = [
    path.resolve(projectRoot, "node_modules"),
    path.resolve(workspaceRoot, "node_modules"),
  ];
  config.resolver.sourceExts = ["mjs", "js", "json", "ts", "tsx"];
  config.resolver.requireCycleIgnorePatterns = [/(^|\/|\\)node_modules($|\/|\\)/];
  config.cacheStores = [
    new FileStore({
      root: path.join(projectRoot, "node_modules", ".cache", "metro"),
    }),
  ];

module.exports = config;
  ```
</CodeGroup>

### Additional monorepo configuration (for pnpm users)

- Add node-linker=hoisted to the root .npmrc (create this file if it doesn’t exist).
- Add the following to the root package.json:

<CodeGroup>
  ```json
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": [
        "@babel/*",
        "expo-modules-*",
        "typescript"
      ]
    }
  }
  ```
</CodeGroup>

For more information, refer to [this](https://github.com/byCedric/expo-monorepo-example#pnpm-workarounds) Expo monorepo example.

### Add polyfills

Create a file `polyfills.js` at the project root with the following content:

<CodeGroup>
  ```js

polyfillGlobal('Buffer', () => Buffer);

polyfillGlobal('ReadableStream', () => ReadableStream);

```
</CodeGroup>

Update `index.js` based on whether you are using expo-router or not:

#### If using `expo-router`

<CodeGroup>
  ```ts
  import "./polyfills";
  import "expo-router/entry";
  ```
</CodeGroup>

#### Without `expo-router`

<CodeGroup>
  ```ts
  import "./polyfills";
  import { registerRootComponent } from "expo";
  import App from "./src/App";
  registerRootComponent(App);
  ```
</CodeGroup>

Lastly, ensure that the `"main"` field in your `package.json` points to `index.js`:

<CodeGroup>
  ```json
  "main": "index.js",
  ```
</CodeGroup>

## Setting up the provider

Wrap your app components with the `JazzProvider:

<CodeGroup>
      ```tsx
      import { JazzProvider } from "jazz-react-native";
      import { MyAppAccount } from "./schema";

export function MyJazzProvider({ children }: { children: React.ReactNode }) {
          return (
              <JazzProvider
                  sync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com" }}
                  AccountSchema={MyAppAccount}
              >
                  {children}
              </JazzProvider>
          );
      }

// Register the Account schema so `useAccount` returns our custom `MyAppAccount`
      declare module "jazz-react-native" {
          interface Register {
              Account: MyAppAccount;
          }
      }
      ```
</CodeGroup>

You can optionally pass a few custom attributes to `<JazzProvider>`:
- `kvStore`
  - `ExpoSecureStoreAdapter` (default)
  - example: `MMKVStore` - roll your own, using MMKV
- `AccountSchema`
  - `Account` (default)
- `CryptoProvider`
  - `PureJSCrypto` (default)
  - `RNQuickCrypto` - C++ accelerated crypto provider

### Choosing an auth method

Refer to the Jazz + React Native demo projects for implementing authentication:

- [DemoAuth Example](https://github.com/garden-co/jazz/tree/main/examples/chat-rn)
- [ClerkAuth Example](https://github.com/garden-co/jazz/tree/main/examples/chat-rn-clerk)

In the demos, you'll find details on:

- Using JazzProvider with your chosen authentication method
- Defining a Jazz schema
- Creating and subscribing to covalues
- Handling invites

### Working with Images

Jazz provides a complete solution for handling images in React Native, including uploading, processing, and displaying them. Here's how to work with images:

#### Uploading Images

To upload images, use the `createImage` function from `jazz-react-native-media-images`. This function handles image processing and creates an `ImageDefinition` that can be stored in your Jazz covalues:

<CodeGroup>
  ```tsx
  import { createImage } from "jazz-react-native-media-images";
  import * as ImagePicker from 'expo-image-picker';

// Example: Image upload from device library
  const handleImageUpload = async () => {
    try {
      const result = await ImagePicker.launchImageLibraryAsync({
        mediaTypes: ImagePicker.MediaTypeOptions.Images,
        base64: true,  // Important: We need base64 data
        quality: 0.7,
      });

if (!result.canceled && result.assets[0].base64) {
        const base64Uri = `data:image/jpeg;base64,${result.assets[0].base64}`;

const image = await createImage(base64Uri, {
          owner: someCovalue._owner,  // Set appropriate owner
          maxSize: 2048,  // Optional: limit maximum image size
        });

// Store the image in your covalue
        someCovalue.image = image;
      }
    } catch (error) {
      console.error('Failed to upload image:', error);
    }
  };
  ```
</CodeGroup>

#### Displaying Images

To display images, use the `ProgressiveImg` component from `jazz-react-native`. This component handles both images uploaded from React Native and desktop browsers:

<CodeGroup>
  ```tsx
  import { ProgressiveImg } from "jazz-react-native";
  import { Image } from "react-native";

// Inside your render function:
  <ProgressiveImg image={someCovalue.image} maxWidth={1024}>
    {({ src, res, originalSize }) => (
      <Image
        source={{ uri: src }}
        style={{
          width: 300,  // Adjust size as needed
          height: 300,
          borderRadius: 8,
        }}
        resizeMode="cover"
      />
    )}
  </ProgressiveImg>
  ```
</CodeGroup>

The `ProgressiveImg` component:
- Automatically handles different image formats
- Provides progressive loading with placeholder images
- Supports different resolutions based on the `maxWidth` prop
- Works seamlessly with React Native's `Image` component

For a complete implementation example, see the [Chat Example](https://github.com/garden-co/jazz/blob/main/examples/chat-rn-clerk/app/chat/[chatId].tsx).

### Running your app

<CodeGroup>
  ```bash
  npx expo run:ios
  npx expo run:android
  ```
</CodeGroup>

---

### react Implementation

# <span id="react">React</span>

Wrap your application with `<JazzProvider />`, this is where you specify the sync & storage server to connect to (see [Sync and storage](/docs/react/sync-and-storage)).

<CodeGroup>
{/* prettier-ignore */}
```tsx

ReactDOM.createRoot(document.getElementById("root")!).render( // old
    <JazzProvider
        sync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com" }}
        AccountSchema={MyAppAccount}
    >
        <App />
    </JazzProvider>
);// old

// Register the Account schema so `useAccount` returns our custom `MyAppAccount`
declare module "jazz-react" {
    interface Register {
        Account: MyAppAccount;
    }
}
```
</CodeGroup>

## Next.js

### Client-side only

The easiest way to use Jazz with Next.JS is to only use it on the client side. You can ensure this by:

- marking the Jazz provider file as `"use client"`

<CodeGroup>
  {/* prettier-ignore */}
  ```tsx
    "use client"
    import { JazzProvider } from "jazz-react"; // old
    import { MyAppAccount } from "./schema"; // old

export function MyJazzProvider(props: { children: React.ReactNode }) { 
        return ( 
            <JazzProvider   
                sync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com" }}
                AccountSchema={MyAppAccount}
            >
                {props.children}
            </JazzProvider> 
        ); 
    } 
```
</CodeGroup>

- marking any file with components where you use Jazz hooks (such as `useAccount` or `useCoState`) as `"use client"`

### SSR use (experimental)

Pure SSR use of Jazz is basically just using jazz-nodejs (see [Node.JS / Server Workers](/docs/react/project-setup/server-side)) inside Server Components.

Instead of using hooks as you would on the client, you await promises returned by `CoValue.load(...)` inside your Server Components.

TODO: code example

This should work well for cases like rendering publicly-readable information, since the worker account will be able to load them.

In the future, it will be possible to use trusted auth methods (such as Clerk, Auth0, etc.) that let you act as the same Jazz user both on the client and on the server, letting you use SSR even for data private to that user.

### SSR + client-side (experimental)

You can combine the two approaches by creating

1. A pure "rendering" component that renders an already-loaded CoValue (in JSON-ified form)

TODO: code example

2. A "hydrating" component (with `"use client"`) that

- expects a pre-loaded CoValue as a prop (in JSON-ified form)
 - uses one of the client-side Jazz hooks (such as `useAccount` or `useCoState`) to subscribe to that same CoValue
 - passing the client-side subscribed state to the "rendering" component, with the pre-loaded CoValue as a fallback until the client receives the first subscribed state

TODO: code example

3. A "pre-loading" Server Component that

- pre-loads the CoValue by awaiting it's `load(...)` method (as described above)
 - renders the "hydrating" component, passing the pre-loaded CoValue as a prop

TODO: code example

---

### server-side Implementation

# Node.JS / server workers

The main detail to understand when using Jazz server-side is that Server Workers have Jazz `Accounts`, just like normal users do.

This lets you share CoValues with Server Workers, having precise access control by adding the Worker to `Groups` with specific roles just like you would with other users.

## Generating credentials

Server Workers typically have static credentials, consisting of a public Account ID and a private Account Secret.

To generate new credentials for a Server Worker, you can run:

<CodeGroup>
{/* prettier-ignore */}
```sh
npx jazz-run account create --name "My Server Worker"
```
</CodeGroup>

The name will be put in the public profile of the Server Worker's `Account`, which can be helpful when inspecting metadata of CoValue edits that the Server Worker has done.

## Storing & providing credentials

Server Worker credentials are typically stored and provided as environmental variables.

**Take extra care with the Account Secret — handle it like any other secret environment variable such as a DB password.**

## Starting a server worker

You can use `startWorker` from `jazz-nodejs` to start a Server Worker. Similarly to setting up a client-side Jazz context, it:

- takes a custom `AccountSchema` if you have one (for example, because the worker needs to store information in it's private account root)
- takes a URL for a sync & storage server

`startWorker` expects credentials in the `JAZZ_WORKER_ACCOUNT` and `JAZZ_WORKER_SECRET` environment variables by default (as printed by `npx account create ...`), but you can also pass them manually as `accountID` and `accountSecret` parameters if you get them from elsewhere.

<CodeGroup>
{/* prettier-ignore */}
```ts

const { worker } = await startWorker({
    AccountSchema: MyWorkerAccount,
    syncServer: 'wss://cloud.jazz.tools/?key=you@example.com',
});
```
</CodeGroup>

`worker` acts like `me` (as returned by `useAccount` on the client) - you can use it to:

- load/subscribe to CoValues: `MyCoValue.subscribe(id, worker, {...})`
- create CoValues & Groups `const val = MyCoValue.create({...}, { owner: worker })`

## Using CoValues instead of requests

Just like traditional backend functions, you can use Server Workers to do useful stuff (computations, calls to third-party APIs etc.) and put the results back into CoValues, which subscribed clients automatically get notified about.

What's less clear is how you can trigger this work to happen.

- One option is to define traditional HTTP API handlers that use the Jazz Worker internally. This is helpful if you need to mutate Jazz state in response to HTTP requests such as for webhooks or non-Jazz API clients
- The other option is to have the Jazz Worker subscribe to CoValues which they will then collaborate on with clients.
    - A common pattern is to implement a state machine represented by a CoValue, where the client will do some state transitions (such as `draft -> ready`), which the worker will notice and then do some work in response, feeding the result back in a further state transition (such as `ready -> success & data`, or `ready -> failure & error details`).
    - This way, client and worker don't have to explicitly know about each other or communicate directly, but can rely on Jazz as a communication mechanism - with computation progressing in a distributed manner wherever and whenever possible.

---

### svelte Implementation

# Svelte Installation

Jazz can be used with Svelte or in a SvelteKit app.

To add some Jazz to your Svelte app, you can use the following steps:

1. Install Jazz dependencies

<CodeGroup>
```sh
pnpm install jazz-tools jazz-svelte
```
</CodeGroup>

2. Write your schema

See the [schema docs](/docs/schemas/covalues) for more information.

<CodeGroup>
```ts
// src/lib/schema.ts

export class MyProfile extends Profile {
  name = co.string;
  counter = co.number; // This will be publically visible
}

export class MyAccount extends Account {
  profile = co.ref(MyProfile);

// ...
}
```
</CodeGroup>

3. Set up the Provider in your root layout

<CodeGroup>
```svelte

 <script lang="ts" module>
  // Register the Account schema so `useAccount` returns our custom `MyAppAccount`
  declare module 'jazz-svelte' {
    interface Register {
      Account: MyAccount;
    }
  }
</script>

// Example configuration for authentication and peer connection
  let sync = { peer: "wss://cloud.jazz.tools/?key=you@example.com" };
  let AccountSchema = MyAccount;
</script>

4. Use Jazz hooks in your components

<CodeGroup>
```svelte

<script lang="ts">
  import { useCoState, useAccount } from 'jazz-svelte';
  import { MyProfile } from './schema';

const { me } = useAccount();

const profile = $derived(useCoState(MyProfile, me._refs.profile.id));

function increment() {
    if (!profile.current) return;
    profile.current.counter = profile.current.counter + 1;
  }
</script>

<button on:click={increment}>
  Count: {profile.current?.counter}
</button>
```
</CodeGroup>

For a complete example of Jazz with Svelte, check out our [file sharing example](https://github.com/gardencmp/jazz/tree/main/examples/file-share-svelte) which demonstrates, Passkey authentication, file uploads and access control.

---

### vue Implementation

# VueJS demo todo app guide

This guide provides step-by-step instructions for setting up and running a Jazz-powered Todo application using VueJS.

See the full example [here](https://github.com/garden-co/jazz/tree/main/examples/todo-vue).

---

## Setup

### Create a new app

Run the following command to create a new VueJS application:

<CodeGroup>
```bash
❯ pnpm create vue@latest

✔ Project name: … vue-setup-guide
✔ Add TypeScript? … Yes
✔ Add JSX Support? … No
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … No
✔ Add Vitest for Unit Testing? … No
✔ Add an End-to-End Testing Solution? › No
✔ Add ESLint for code quality? › Yes
✔ Add Prettier for code formatting? … Yes
```
</CodeGroup>

### Install dependencies

Run the following command to install Jazz libraries:

<CodeGroup>
```bash
pnpm install jazz-tools jazz-browser jazz-vue
```
</CodeGroup>

### Implement `schema.ts`

Define the schema for your application.

Example schema inside `src/schema.ts` for a todo app:

<CodeGroup>
```typescript

export class ToDoItem extends CoMap {
  name = co.string;
  completed = co.boolean;
}

export class ToDoList extends CoList.Of(co.ref(ToDoItem)) {}

export class Folder extends CoMap {
  name = co.string;
  items = co.ref(ToDoList);
}

export class FolderList extends CoList.Of(co.ref(Folder)) {}

export class ToDoAccountRoot extends CoMap {
  folders = co.ref(FolderList);
}

export class ToDoAccount extends Account {
  profile = co.ref(Profile);
  root = co.ref(ToDoAccountRoot);

migrate() {
    if (!this._refs.root) {
      const group = Group.create({ owner: this });
      const firstFolder = Folder.create(
        {
          name: "Default",
          items: ToDoList.create([], { owner: group }),
        },
        { owner: group },
      );

this.root = ToDoAccountRoot.create(
        {
          folders: FolderList.create([firstFolder], {
            owner: this,
          }),
        },
        { owner: this },
      );
    }
  }
}
```
</CodeGroup>

### Refactor `main.ts`

Update the `src/main.ts` file to integrate Jazz:

<CodeGroup>
```typescript

declare module "jazz-vue" {
  interface Register {
    Account: ToDoAccount;
  }
}

const RootComponent = defineComponent({
  name: "RootComponent",
  setup() {
    return () => [
      h(
        JazzProvider,
        {
          AccountSchema: ToDoAccount,
          auth: authMethod.value,
          peer: "wss://cloud.jazz.tools/?key=vue-todo-example-jazz@garden.co",
        },
        {
          default: () => h(App),
        },
      ),
    ];
  },
});

const app = createApp(RootComponent);

app.use(router);

app.mount("#app");
```
</CodeGroup>

### Set up `router/index.ts`:

Create a basic Vue router configuration. For example:

<CodeGroup>
```typescript

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: "/",
      name: "Home",
      component: HomeView,
    },
  ],
});

export default router;
```
</CodeGroup>

### Implement `App.vue`

Update the `App.vue` file to include logout functionality:

<CodeGroup>
```typescript
<template>
  <div class="app-container">
    <header v-if="me" class="app-header">
      <h1>Todo App</h1>
      <div class="user-section">
        <span>{{ me.profile?.name }}</span>
        <button class="logout-btn" @click="logOut">Log out</button>
      </div>
    </header>
    <main>
      <router-view />
    </main>
  </div>
</template>

const { me, logOut } = useAccount();
</script>
```
</CodeGroup>

## Subscribing to a CoValue

Subscribe to a CoValue inside `src/views/HomeView.vue`:

<CodeGroup>
```typescript
<script setup lang="ts">

const { me } = useAccount();

// Computed ID for the folders list
const computedFoldersId = computed(() => me.value?.root?.folders?.id);

// Load folders and nested values
const folders = useCoState(FolderList, computedFoldersId, [{ items: [{}] }]);
```
</CodeGroup>

See the full example [here](https://github.com/garden-co/jazz/tree/main/examples/todo-vue).

## Mutating a CoValue

Here's how to create a new folder:

<CodeGroup>
```typescript
// continues previous example

const createFolder = async (name: string) => {
  // Create a group owned by the current user
  const group = Group.create({ owner: me.value });

// Create the folder
  const newFolder = Folder.create(
    {
      name,
      items: ToDoList.create([], { owner: group }),
    },
    { owner: group },
  );

// Add the folder to the list of folders.
  // This change is sent to all connected clients and will be synced in real time.
  folders.value?.push(newFolder);
  newFolderName.value = "";
};

```
</CodeGroup>

See the full example [here](https://github.com/garden-co/jazz/tree/main/examples/todo-vue).

#### Sync and storage

# Sync and storage

## Using Jazz Cloud

Simply use `wss://cloud.jazz.tools/?key=...` as the sync server URL.

Jazz Cloud will
- sync CoValues in real-time between users and devices
- safely persist CoValues on redundant storage nodes with additional backups
- make use of geographically distributed cache nodes for low latency

### Free public alpha

- Jazz Cloud is free during the public alpha, with no strict usage limits
- We plan to keep a free tier, so you'll always be able to get started with zero setup
- See [Jazz Cloud pricing](/cloud#pricing) for more details
- ⚠️ Please use a valid email address as your API key.

Your full sync server URL should look something like

```wss://cloud.jazz.tools/?key=you@example.com```

Once we support per-app API keys, we'll email you an API key you can use instead.

## Running your own sync server

You can run your own sync server using:

And then use `ws://localhost:4200` as the sync server URL.

You can also run this simple sync server behind a proxy that supports WebSockets, for example to provide TLS.
In this case, provide the WebSocket endpoint your proxy exposes as the sync server URL.

### Command line options:

- `--port` / `-p` - the port to run the sync server on. Defaults to 4200.
- `--in-memory` - keep CoValues in-memory only and do sync only, no persistence. Persistence is enabled by default.
- `--db` - the path to the file where to store the data (SQLite). Defaults to `sync-db/storage.db`.

### Source code

The implementation of this simple sync server is available open-source [on GitHub](https://github.com/garden-co/jazz/blob/main/packages/jazz-run/src/startSyncServer.ts).

#### Node.JS / server workers

# Node.JS / server workers

The main detail to understand when using Jazz server-side is that Server Workers have Jazz `Accounts`, just like normal users do.

This lets you share CoValues with Server Workers, having precise access control by adding the Worker to `Groups` with specific roles just like you would with other users.

## Generating credentials

Server Workers typically have static credentials, consisting of a public Account ID and a private Account Secret.

To generate new credentials for a Server Worker, you can run:

<CodeGroup>
{/* prettier-ignore */}
```sh
npx jazz-run account create --name "My Server Worker"
```
</CodeGroup>

The name will be put in the public profile of the Server Worker's `Account`, which can be helpful when inspecting metadata of CoValue edits that the Server Worker has done.

## Storing & providing credentials

Server Worker credentials are typically stored and provided as environmental variables.

**Take extra care with the Account Secret — handle it like any other secret environment variable such as a DB password.**

## Starting a server worker

You can use `startWorker` from `jazz-nodejs` to start a Server Worker. Similarly to setting up a client-side Jazz context, it:

- takes a custom `AccountSchema` if you have one (for example, because the worker needs to store information in it's private account root)
- takes a URL for a sync & storage server

<CodeGroup>
{/* prettier-ignore */}
```ts

const { worker } = await startWorker({
    AccountSchema: MyWorkerAccount,
    syncServer: 'wss://cloud.jazz.tools/?key=you@example.com',
});
```
</CodeGroup>

`worker` acts like `me` (as returned by `useAccount` on the client) - you can use it to:

- load/subscribe to CoValues: `MyCoValue.subscribe(id, worker, {...})`
- create CoValues & Groups `const val = MyCoValue.create({...}, { owner: worker })`

## Using CoValues instead of requests

What's less clear is how you can trigger this work to happen.

### Upgrade guides

#### 0.10.0 - New authentication flow

# Jazz 0.10.0 is out!

For Jazz 0.10.0 we have been focusing on enhancing authentication to make it optional, more flexible and easier to use.

The default is now anonymous auth, which means that you can build the functionality of your app first and figure out auth later. For users this means that they can start using your app right away on one device -- and once you integrate an auth method, users can sign up and their anonymous accounts are transparently upgraded to authenticated accounts that work across devices.

There are also some other minor improvements that will make your Jazz experience even better!

## What's new?
Here is what's changed in this release:
- [New authentication flow](#new-authentication-flow): Now with anonymous auth, redesigned to make Jazz easier to start with and be more flexible.
- [Local-only mode](#local-only-mode): Users can now explore your app in local-only mode before signing up.
- [Improvements on the loading APIs](#improved-loading-api); `ensureLoaded` now always returns a value and `useCoState` now returns `null` if the value is not found.
- [Jazz Workers on native WebSockets](#native-websocket-for-jazz-workers): Improves compatibility with a wider set of Javascript runtimes.
- [Group inheritance with role mapping](#group-inheritance): Groups can now inherit members from other groups with a fixed role.
- Support for Node 14 dropped on cojson.
- Bugfix: `Group.removeMember` now returns a promise.
- Now `cojson` and `jazz-tools` don't export directly the crypto providers anymore. Replace the import with `cojson/crypto/WasmCrypto` or `cojson/crypto/PureJSCrypto` depending on your use case.

## New authentication flow
    Up until now authentication has been the first part to figure out when building a Jazz app, and this was a stumbling block for many.

Now it is no longer required and setting up a Jazz app is as easy as writing this:
<CodeGroup>
{/* prettier-ignore */}
```tsx
<JazzProvider
    auth={authMethod} // removed  // *bin*
    peer="wss://cloud.jazz.tools/?key=you@example.com"  // moved into sync // *bin*
    sync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com" }}  // *add*
>
    <App />
</JazzProvider>
```
</CodeGroup>

New users are initially authenticated as "anonymous" and you can sign them up later with the hooks/providers of your chosen auth method.

Your auth code can now blend into your component tree:
<ContentByFramework framework="react">
<CodeGroup>
{/* prettier-ignore */}
```tsx
export function AuthModal({ open, onOpenChange }: AuthModalProps) {
  const [username, setUsername] = useState("");
  const [isSignUp, setIsSignUp] = useState(true);

const auth = usePasskeyAuth({ // Must be inside the JazzProvider!
    appName: "My super-cool web app",
  });

const handleViewChange = () => {
    setIsSignUp(!isSignUp);
  };

const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

if (isSignUp) {
      await auth.signUp(username);
    } else {
      await auth.logIn();
    }
    onOpenChange(false);
};
```
</CodeGroup>
</ContentByFramework>
<ContentByFramework framework="react-native">
<CodeGroup>
{/* prettier-ignore */}
```tsx
export function AuthModal({ open, onOpenChange }: AuthModalProps) {
  const [username, setUsername] = useState("");
  const [isSignUp, setIsSignUp] = useState(true);
  const [loginPassphrase, setLoginPassphrase] = useState("");

const auth = usePassphraseAuth({ // Must be inside the JazzProvider!
    wordlist,
  });

const handleViewChange = () => {
    setIsSignUp(!isSignUp);
  };

const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

if (isSignUp) {
      await auth.signUp();
    } else {
      await auth.logIn(loginPassphrase);
    }
    onOpenChange(false);
};
```
</CodeGroup>
</ContentByFramework>
<ContentByFramework framework="svelte">
<CodeGroup>
{/* prettier-ignore */}
```tsx

const auth = usePasskeyAuth({ appName: "My super-cool web app" });

let error = $state<string | undefined>(undefined);

function signUp(e: Event) {
  const formData = new FormData(e.currentTarget as HTMLFormElement);
  const name = formData.get('name') as string;

if (!name) {
    error = 'Name is required';
    return;
  }
  e.preventDefault();
  error = undefined;
  auth.current.signUp(name).catch((e) => {
    error = e.message;
  });
}

const auth = usePasskeyAuth({ appName: "My super-cool web app" });
const error = ref<string | undefined>(undefined);

function signUp(e: Event) {
  const formData = new FormData(e.currentTarget as HTMLFormElement);
  const name = formData.get('name') as string;

if (!name) {
    error.value = 'Name is required';
    return;
  }
  e.preventDefault();
  error.value = undefined;
  auth.value.signUp(name).catch((e) => {
    error.value = e.message;
  });
}

function logIn(e: Event) {
  error.value = undefined;
  e.preventDefault();
  auth.value.logIn().catch((e) => {
    error.value = e.message;
  });
}
```
</CodeGroup>
</ContentByFramework>

When a user signs up with one of the auth methods we upgrade the current anonymous account to an authenticated account by storing the account's secret keys in the auth method.

<ContentByFramework framework={["react"]}>
To check if the user has registered you can use the new `useIsAuthenticated` hook:
<CodeGroup>
{/* prettier-ignore */}
```tsx
export function AuthButton() {
  const isAuthenticated = useIsAuthenticated();
  const { logOut } = useAccount();
  const [open, setOpen] = useState(false);

if (isAuthenticated) {
    return (
      <Button
        variant="outline"
        onClick={logOut}
      >
        Sign out
      </Button>
    );
  }

return (
    <>
      <Button onClick={() => setOpen(true)}>
        Sign up
      </Button>
      <AuthModal open={open} onOpenChange={setOpen} />
    </>
  );
}
```
</CodeGroup>
</ContentByFramework>
<ContentByFramework framework={["react-native"]}>
To check if the user has registered you can use the new `useIsAuthenticated` hook:
<CodeGroup>
{/* prettier-ignore */}
```tsx
export function AuthButton() {
  const isAuthenticated = useIsAuthenticated();
  const { logOut } = useAccount();
  const [open, setOpen] = useState(false);

if (isAuthenticated) {
    return (
      <Button
        variant="outline"
        onPress={logOut}
      >
        Sign out
      </Button>
    );
  }

return (
    <>
      <Button onPress={() => setOpen(true)}>
        Sign up
      </Button>
      <AuthModal open={open} onOpenChange={setOpen} />
    </>
  );
}
```
</CodeGroup>
</ContentByFramework>

<ContentByFramework framework={["react"]}>
If you do want to require your users to register before using your app, you can do it by moving the auth code outside of your app and conditionally rendering your app as a child -- or apply this pattern for specific parts of the app you'd like to gate behind authentication.

Our provided "Basic UIs" for the different auth methods render their children conditionally by default, so you can either nest them in your app without children, or nest your app or gated parts of your app inside *them*, depending on the desired behavior.
<CodeGroup>
{/* prettier-ignore */}
```tsx

ReactDOM.createRoot(document.getElementById("root")!).render(
    <JazzProvider
      sync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com" }}
    >
      <PasskeyAuthBasicUI appName="My super-cool web app">
        <App />
      </PasskeyAuthBasicUI>
    </JazzProvider>
);
```
</CodeGroup>
</ContentByFramework>

For the changes related to the specific auth providers see the updated [authentication docs](/docs/authentication/overview).

## Local-only mode

If you are ok with data not being persisted on the sync server for anonymous users, you can now set your app to local-only depending on the user's authentication state.

With `sync.when` set to `"signedUp"` the app will work in local-only mode when the user is anonymous and unlock the multiplayer/multi-device features and cloud persistence when they sign up:
<CodeGroup>
```tsx
<JazzProvider
  sync={{
    peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
     // This makes the app work in local mode when the user is anonymous
    when: "signedUp",
  }}
>
  <App />
</JazzProvider>
```
</CodeGroup>

You can control when Jazz will sync by switching the `when` config to `"always"` or `"never"`.

## Improvements on the loading APIs

Before 0.10.0 `ensureLoaded` was returning a nullable value forcing the Typescript code to always include null checks:
<CodeGroup>
```ts
export async function updateActiveTrack(track: MusicTrack) { // No need to pass the account
  const me = await MusicaAccount.getMe().ensureLoaded({
    root: {},
  });

if (!me) { // Technically can never happen
    throw new Error("User not found");
  }

me.root.activeTrack = track;
}
```
</CodeGroup>

Now `ensureLoaded` always returns a value, making it's usage leaner:
<CodeGroup>
```ts
export async function updateActiveTrack(track: MusicTrack) { // No need to pass the account
  const { root } = await MusicaAccount.getMe().ensureLoaded({
    root: {},
  });

// Null checks are no more required
  root.activeTrack = track;
}
```
</CodeGroup>

It will throw if the value is not found, which can happen if the user tries to resolve a value that is not available.

`useCoState` now returns `null` if the value is not found, making it now possible to check against not-found values:
<CodeGroup>
```ts
const value = useCoState(MusicTrack, id, {});

if (value === null) {
  return <div>Track not found</div>;
}
```
</CodeGroup>

## Jazz Workers on native WebSockets

We have removed the dependency on `ws` and switched to the native WebSocket API for Jazz Workers.

This improves the compatibility with a wider set of Javascript runtimes adding drop-in support for Deno, Bun, Browsers and Cloudflare Durable Objects.

If you are using a Node.js version lower than 22 you will need to install the `ws` package and provide the WebSocket constructor:

<CodeGroup>
```ts

const { worker } = await startWorker({
  WebSocket,
});
```
</CodeGroup>

## Group inheritance with role mapping
You can override the inherited role by passing a second argument to `extend`.

This can be used to give users limited access to a child group:
<CodeGroup>
```ts
const organization = Group.create();
const billing = Group.create();

billing.extend(organization, "reader");
```
</CodeGroup>

This way the members of the organization can only read the billing data, even if they are admins in the organization group.

More about the group inheritance can be found in the [dedicated docs page](/docs/groups/inheritance).

#### 0.9.8 - Without me!

# Jazz 0.9.8 - Without me!

We have simplified the API to make the "me" value always optional!

This removes the need of using `useAccount` like the 90% of the time!

<CodeGroup>
    {/* prettier-ignore */}
    ```ts
    import { useState } from "react";
    import { Issue } from "./schema";
    import { IssueComponent } from "./components/Issue.tsx";

function App() {
        const [issue, setIssue] = useState<Issue>();

const createIssue = () => {
            setIssue(Issue.create(
                {
                    title: "Buy terrarium",
                    description: "Make sure it's big enough for 10 snails.",
                    estimate: 5,
                    status: "backlog",
                }, // The owner defaults now to a group managed by the current user!
            ));
        };

if (issue) {
            return <IssueComponent issue={issue} />;
        } else {
            return <button onClick={createIssue}>Create Issue</button>;
        }
    }
    ```
</CodeGroup>

This also applies to the load API:

<CodeGroup>
  {/* prettier-ignore */}
  ```ts
  const issue = Issue.load(issueId, {})
  ```
</CodeGroup>

And `Group.create`:

<CodeGroup>
    {/* prettier-ignore */}
    ```tsx
    const group = Group.create()
    const sharedIssue = Issue.create(payload, group)
    group.addMember('everyone', 'reader')
    ```
</CodeGroup>

Everything is backward compatible, so no upgrade steps are required.

With this Jazz API becomes way more lean and more is coming!

#### 0.9.2 - Local persistence on React Native

# Enable local persistence

Version 0.9.2 introduces local persistence for React Native apps using SQLite.

If you are upgrading from a version before 0.9.2, you need to enable local persistence by following the steps below.

Local persistence will become the default in 0.10.0.

## Add the required dependencies

As SQLite package we now use `@op-engineering/op-sqlite`.

To get local persistence working, you need to add `@op-engineering/op-sqlite` as a direct dependency to your project and run `npx pod-install`.

## Update your JazzProvider to enable local persistence

Local persistence is now disabled by default.

To enable it, you need to pass the `storage` option to the `JazzProvider` component:

#### 0.9.0 - Top level imports

### react-native Implementation

# Upgrade to Jazz 0.9.0

Version 0.9.0 simplifies the application setup and makes Jazz more intellisense friendly by
replacing the `createJazzRNApp` API with top-level imports.

We have also introduced some new API to make testing Jazz components a breeze. 🌬️

## New provider setup

The `JazzProvider` is now imported from `jazz-react-native` instead of `createJazzRNApp`.

While `createJazzRNApp` was originally designed to setup strong typing for custom Account schemas in `useAccount`,
we found that this approach made the Jazz setup awkward and confusing for some users.

So we decided to remove `createJazzRNApp` step and to provide the types through namespace declarations:

<CodeGroup>
      {/* prettier-ignore */}
      ```tsx
      import { JazzProvider, useDemoAuth, DemoAuthBasicUI } from "jazz-react-native";
      import { MyAppAccount } from "./schema";

// Remove these lines  // *bin*
      const Jazz = createJazzRNApp({ AccountSchema: MyAppAccount }); // *bin*
      export const { useAccount, useCoState } = Jazz; // *bin*

export function JazzAndAuth({ children }: { children: React.ReactNode }) {  // old
          const [auth, state] = useDemoAuth();  // old

return (
              <>
                  {/* Replace Jazz.Provider with provider from jazz-react */}
                  <JazzProvider
                      auth={auth} // old
                      peer="wss://cloud.jazz.tools/?key=you@example.com" // old
                      AccountSchema={MyAppAccount} {/* The custom Account schema is passed here */}
                  >
                      {children} // old
                  </JazzProvider>
                  <DemoAuthBasicUI appName="My App" state={state} /> // old
              </> // old
          );
      }

## Top level imports for hooks

All Jazz hooks are now available as top-level imports from the `jazz-react-native` package.

This change improves IDE intellisense support and simplifies imports:

<CodeGroup>
    {/* prettier-ignore */}
    ```tsx
    // Replace local imports with "jazz-react-native" imports
    import { useAccount } from "./main"; // *bin*
    import { useAccount } from "jazz-react-native"; // *add*

export function Hello() {
        const { me } = useAccount();

return (
            <>
              Hello {me.profile?.name}
            </>
        );
    }
    ```
  </CodeGroup>

## New testing utilities

<div>
    Removing `createJazzRNApp` also makes testing way easier!

We can now use `createJazzTestAccount` to setup accounts and testing data and pass it to
    your components and hooks using `JazzTestProvider`:
  </div>

<CodeGroup>
      {/* prettier-ignore */}
      ```tsx
      import { createJazzTestAccount, JazzTestProvider } from "jazz-react-native/testing";
      import { renderHook } from "@testing-library/react-native"; // old
      import { usePlaylist } from "./usePlaylist"; // old
      import { Playlist, MusicAccount } from "./schema"; // old

test("should load the playlist", async () => {
        // ✅ Create a test account with your schema
        const account = await createJazzTestAccount({ AccountSchema: MusicAccount });

// ✅ Set up test data
        const playlist = Playlist.create({
          name: "My playlist",
        }, account);

// ✅ Use JazzTestProvider in your tests
        const { result } = renderHook(() => usePlaylist(playlist.id), {
          wrapper: ({ children }) => (
            <JazzTestProvider account={account}>
              {children}
            </JazzTestProvider>
          ),
        });

// The result is resolved synchronously, so you can assert the value immediately
        expect(result.current?.name).toBe("My playlist");
      });
      ```
  </CodeGroup>

---

### react Implementation

# Upgrade to Jazz 0.9.0

Version 0.9.0 simplifies the application setup and makes Jazz more intellisense friendly by
replacing the `createJazzReactApp` API with top-level imports.

We have also introduced some new API to make testing Jazz components a breeze. 🌬️

## New provider setup

The `JazzProvider` is now imported from `jazz-react` instead of `createJazzReactApp`.

While `createJazzReactApp` was originally designed to setup strong typing for custom Account schemas in `useAccount`,
we found that this approach made the Jazz setup awkward and confusing for some users.

So we decided to remove `createJazzReactApp` step and to provide the types through namespace declarations:

<CodeGroup>
      {/* prettier-ignore */}
      ```tsx
      import { JazzProvider, usePasskeyAuth, PasskeyAuthBasicUI } from "jazz-react";
      import { MyAppAccount } from "./schema";

// Remove these lines  // *bin*
      const Jazz = createJazzReactApp({ AccountSchema: MyAppAccount }); // *bin*
      export const { useAccount, useCoState } = Jazz; // *bin*

export function JazzAndAuth({ children }: { children: React.ReactNode }) {  // old
          const [passkeyAuth, passKeyState] = usePasskeyAuth({ appName });  // old

return (
              <>
                  {/* Replace Jazz.Provider with provider from jazz-react */}
                  <JazzProvider
                      auth={passkeyAuth} // old
                      peer="wss://cloud.jazz.tools/?key=you@example.com" // old
                      AccountSchema={MyAppAccount} {/* The custom Account schema is passed here */} // *add*
                  >
                      {children} // old
                  </JazzProvider>
                  <PasskeyAuthBasicUI state={passKeyState} /> // old
              </> // old
          );
      }

// Register the Account schema so `useAccount` returns our custom `MyAppAccount`
      declare module "jazz-react" { // *add*
          interface Register { // *add*
              Account: MyAppAccount; // *add*
          } // *add*
      } // *add*
      ```
  </CodeGroup>

## Top level imports for hooks

All Jazz hooks are now available as top-level imports from the `jazz-react` package.

This change improves IDE intellisense support and simplifies imports:

<CodeGroup>
    {/* prettier-ignore */}
    ```tsx
    // Replace local imports with "jazz-react" imports
    import { useAccount } from "./main"; // *bin*
    import { useAccount } from "jazz-react"; // *add*

export function Hello() {
        const { me } = useAccount();

return (
            <>
              Hello {me.profile?.name}
            </>
        );
    }
    ```
  </CodeGroup>

## New testing utilities

Removing `createJazzReactApp` also makes testing way easier!

We can now use `createJazzTestAccount` to setup accounts and testing data and pass it to
your components and hooks using `JazzTestProvider`:

<CodeGroup>
      {/* prettier-ignore */}
      ```tsx
      import { createJazzTestAccount, JazzTestProvider } from "jazz-react/testing";
      import { renderHook } from "@testing-library/react"; // old
      import { usePlaylist } from "./usePlaylist"; // old
      import { Playlist, MusicAccount } from "./schema"; // old

test("should load the playlist", async () => {
        // ✅ Create a test account with your schema
        const account = await createJazzTestAccount({ AccountSchema: MusicAccount });

// ✅ Set up test data
        const playlist = Playlist.create({
          name: "My playlist",
        }, account);

// The result is resolved synchronously, so you can assert the value immediately
        expect(result.current?.name).toBe("My playlist");
      });
      ```
  </CodeGroup>

---

### svelte Implementation

# Upgrade to Jazz 0.9.0

Version 0.9.0 simplifies the application setup and makes Jazz more intellisense friendly by
replacing the `createJazzApp` API with top-level imports.

We have also introduced some new API to make testing Jazz components a breeze. 🌬️

## New provider setup

The `JazzProvider` is now imported from `jazz-svelte` instead of `createJazzApp`.

While `createJazzApp` was originally designed to setup strong typing for custom Account schemas in `useAccount`,
we found that this approach made the Jazz setup awkward and confusing for some users.

So we decided to remove `createJazzApp` step and to provide the types through namespace declarations:

<CodeGroup>
      {/* prettier-ignore */}
        ```svelte
        
        <script lang="ts" module>
          // Register the Account schema so `useAccount` returns our custom `MyAppAccount`
          declare module 'jazz-svelte' {
            interface Register {
              Account: MyAccount;
            }
          }
        </script>

// Example configuration for authentication and peer connection
          let auth = null; // Replace with your auth implementation
          let peer = "wss://your-peer-endpoint";

// The custom Account schema is passed now as a prop
          let AccountSchema = MyAccount;
        </script>

## Top level imports for hooks

<div>
    All Jazz hooks are now available as top-level imports from the `jazz-svelte` package.

This change improves IDE intellisense support and simplifies imports:
  </div>

<CodeGroup>
    {/* prettier-ignore */}
```svelte

const { me } = useAccount();
</script>

<div>
  Hello {me.profile?.name}
</div>

```
  </CodeGroup>

## New testing utilities

Removing `createJazzApp` also makes testing way easier!

We can now use `createJazzTestAccount` to setup accounts and testing data and pass it to
your components and hooks using `JazzTestProvider`:

<CodeGroup>
      {/* prettier-ignore */}
      ```ts
      import { useCoState } from "jazz-svelte";
      import { createJazzTestAccount, JazzTestProvider } from "jazz-svelte/testing";
      import { render } from "@testing-library/svelte"; // old
      import { Playlist, MusicAccount } from "./schema"; // old

test("should load the playlist", async () => {
        // ✅ Create a test account with your schema
        const account = await createJazzTestAccount({ AccountSchema: MusicAccount });

// ✅ Set up test data
        const playlist = Playlist.create({
          name: "My playlist",
        }, account);

// ✅ Use createJazzTestContext in your tests
        render(PlaylistComponent, {
          context: createJazzTestContext({ account: options.account }),
          props: {
            id: playlist.id,
          },
        });

expect(await screen.findByRole("heading", { name: "My playlist" })).toBeInTheDocument();
      });
      ```
  </CodeGroup>

---

### vue Implementation

# Upgrade to Jazz 0.9.0

Version 0.9.0 simplifies the application setup and makes Jazz more intellisense friendly by
replacing the `createJazzVueApp` API with top-level imports.

We have also introduced some new API to make testing Jazz components a breeze. 🌬️

## New provider setup

The `JazzProvider` is now imported from `jazz-vue` instead of `createJazzVueApp`.

So we decided to remove `createJazzReactApp` step and to provide the types through namespace declarations:

<CodeGroup>
      {/* prettier-ignore */}
```typescript

// Remove these lines  // *bin*
const Jazz = createJazzVueApp<ToDoAccount>({ AccountSchema: ToDoAccount }); // *bin*
export const { useAccount, useCoState } = Jazz; // *bin*
const { JazzProvider } = Jazz; // *bin*

// Register the Account schema so `useAccount` returns our custom `MyAppAccount`
declare module "jazz-vue" {
  interface Register {
    Account: ToDoAccount;
  }
}

const app = createApp(RootComponent); // old
app.use(router); // old
app.mount("#app"); // old
```
  </CodeGroup>

## Top level imports for hooks

All Jazz hooks are now available as top-level imports from the `jazz-vue` package.

This change improves IDE intellisense support and simplifies imports:

<CodeGroup>
    {/* prettier-ignore */}
```typescript
<template>
  Hello {{ me.profile?.name }}
</template>

const { me, logOut } = useAccount();
</script>
```
  </CodeGroup>

## New testing utilities

Removing `createJazzTestApp` also makes testing way easier!

We can now use `createJazzTestAccount` to setup accounts and testing data and pass it to
your components and hooks using `JazzTestProvider`:

<CodeGroup>
      {/* prettier-ignore */}
      ```tsx
      import { createJazzTestAccount, JazzTestProvider } from "jazz-vue/testing";
      import { createApp, defineComponent, h } from "vue";
      import { usePlaylist } from "./usePlaylist";
      import { Playlist, MusicAccount } from "./schema"; // old

// This can be reused on other tests!
      export const renderComposableWithJazz = <C extends (...args: any[]) => any>(
        composable: C,
        { account }: { account: Account | { guest: AnonymousJazzAgent } },
      ) => {
        let result;

const wrapper = defineComponent({
          setup() {
            result = composable();
            // suppress missing template warning
            return () => {};
          },
        });

// ✅ Use JazzTestProvider in your tests
        const app = createApp({
          setup() {
            return () =>
              h(
                JazzTestProvider,
                {
                  account,
                },
                {
                  default: () => h(wrapper),
                },
              );
          },
        });

app.mount(document.createElement("div"));
        return [result, app] as [ReturnType<C>, ReturnType<typeof createApp>];
      };

test("should load the playlist", async () => {
        // ✅ Create a test account with your schema
        const account = await createJazzTestAccount({ AccountSchema: MusicAccount });

// ✅ Set up test data
        const playlist = Playlist.create({
          name: "My playlist",
        }, account);

// ✅ Set up test data
        const { result } = renderComposableWithJazz(() => usePlaylist(playlist.id), {
          account,
        });

// The result is resolved synchronously, so you can assert the value immediately
        expect(result?.name).toBe("My playlist");
      });
      ```
  </CodeGroup>

### Defining schemas

#### CoValues

# Defining schemas: CoValues

**CoValues ("Collaborative Values") are the core abstraction of Jazz.** They're your bread-and-butter datastructures that you use to represent everything in your app.

As their name suggests, CoValues are inherently collaborative, meaning **multiple users and devices can edit them at the same time.**

**Think of CoValues as "super-fast Git for lots of tiny data."**

- CoValues keep their full edit histories, from which they derive their "current state".
- The fact that this happens in an eventually-consistent way makes them [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).
- Having the full history also means that you often don't need explicit timestamps and author info - you get this for free as part of a CoValue's [edit metadata](/docs/using-covalues/metadata).

CoValues model JSON with CoMaps and CoLists, but also offer CoFeeds for simple per-user value feeds, and let you represent binary data with FileStreams.

## Start your app with a schema

Fundamentally, CoValues are as dynamic and flexible as JSON, but in Jazz you use them by defining fixed schemas to describe the shape of data in your app.

This helps correctness and development speed, but is particularly important...
- when you evolve your app and need migrations
- when different clients and server workers collaborate on CoValues and need to make compatible changes

Thinking about the shape of your data is also a great first step to model your app.

Even before you know the details of how your app will work, you'll probably know which kinds of objects it will deal with, and how they relate to each other.

Jazz makes it quick to declare schemas, since they are simple TypeScript classes:

<CodeGroup>
{/* prettier-ignore */}
```ts
export class TodoProject extends CoMap {
    title = co.string;
    tasks = co.ref(ListOfTasks);
}
```
</CodeGroup>

Here you can see how we extend a CoValue type and use `co` for declaring (collaboratively) editable fields. This means that schema info is available for type inference *and* at runtime.

Classes might look old-fashioned, but Jazz makes use of them being both types and values in TypeScript, letting you refer to either with a single definition and import.

<CodeGroup>
{/* prettier-ignore */}
```ts

const project: TodoProject = TodoProject.create(
    {
        title: "New Project",
        tasks: ListOfTasks.create([], Group.create()),
    },
    Group.create()
);
```
</CodeGroup>

## Types of CoValues

### `CoMap` (declaration)

CoMaps are the most commonly used type of CoValue. They are the equivalent of JSON objects. (Collaborative editing follows a last-write-wins strategy per-key.)

You can either declare struct-like CoMaps:

<CodeGroup>
{/* prettier-ignore */}
```ts
class Person extends CoMap {
    name = co.string;
    age = co.number;
    pet = co.optional.ref(Pet);
}
```
</CodeGroup>

Or record-like CoMaps (key-value pairs, where keys are always `string`):

<CodeGroup>
{/* prettier-ignore */}
```ts
class ColorToHex extends CoMap.Record(co.string) {}

class ColorToFruit extends CoMap.Record(co.ref(Fruit)) {}
```
</CodeGroup>

See the corresponding sections for [creating](/docs/using-covalues/creation#comap-creation),
[subscribing/loading](/docs/using-covalues/subscription-and-loading),
[reading from](/docs/using-covalues/reading#comap-reading) and
[writing to](/docs/using-covalues/writing#comap-writing) CoMaps.

### `CoList` (declaration)

CoLists are ordered lists and are the equivalent of JSON arrays. (They support concurrent insertions and deletions, maintaining a consistent order.)

You define them by specifying the type of the items they contain:

<CodeGroup>
{/* prettier-ignore */}
```ts
class ListOfColors extends CoList.Of(co.string) {}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}
```
</CodeGroup>

See the corresponding sections for [creating](/docs/using-covalues/creation#colist-creation),
[subscribing/loading](/docs/using-covalues/subscription-and-loading),
[reading from](/docs/using-covalues/reading#colist-reading) and
[writing to](/docs/using-covalues/writing#colist-writing) CoLists.

### `CoFeed` (declaration)

CoFeeds are a special CoValue type that represent a feed of values for a set of users / sessions. (Each session of a user gets its own append-only feed.)

They allow easy access of the latest or all items belonging to a user or their sessions. This makes them particularly useful for user presence, reactions, notifications, etc.

You define them by specifying the type of feed item:

<CodeGroup>
{/* prettier-ignore */}
```ts
class FeedOfTasks extends CoFeed.Of(co.ref(Task)) {}
```
</CodeGroup>

See the corresponding sections for [creating](/docs/using-covalues/creation#cofeed-creation),
[subscribing/loading](/docs/using-covalues/subscription-and-loading),
[reading from](/docs/using-covalues/reading#cofeed-reading) and
[writing to](/docs/using-covalues/writing#cofeed-writing) CoFeeds.

### `FileStream` (declaration)

FileStreams are a special type of CoValue that represent binary data. (They are created by a single user and offer no internal collaboration.)

They allow you to upload and reference files, images, etc.

You typically don't need to declare or extend them yourself, you simply refer to the built-in `FileStream` from another CoValue:

<CodeGroup>
{/* prettier-ignore */}
```ts

class UserProfile extends CoMap {
    name = co.string;
    avatar = co.ref(FileStream);
}
```
</CodeGroup>

See the corresponding sections for [creating](/docs/using-covalues/creation#filestream-creation),
[subscribing/loading](/docs/using-covalues/subscription-and-loading),
[reading from](/docs/using-covalues/reading#filestream-reading) and
[writing to](/docs/using-covalues/writing#filestream-writing) FileStreams.

### `SchemaUnion` (declaration)

SchemaUnion is a helper type that allows you to load and refer to multiple subclasses of a CoMap schema, distinguished by a discriminating field.

You declare them with a base class type and discriminating lambda, in which you have access to the `RawCoMap`, on which you can call `get` with the field name to get the discriminating value.

<CodeGroup>
{/* prettier-ignore */}
```ts

class BaseWidget extends CoMap {
  type = co.string;
}

class ButtonWidget extends BaseWidget {
  type = co.literal("button");
  label = co.string;
}

class SliderWidget extends BaseWidget {
  type = co.literal("slider");
  min = co.number;
  max = co.number;
}

const WidgetUnion = SchemaUnion.Of<BaseWidget>((raw) => {
  switch (raw.get("type")) {
    case "button": return ButtonWidget;
    case "slider": return SliderWidget;
    default: throw new Error("Unknown widget type");
  }
});
```
</CodeGroup>

See the corresponding sections for [creating](/docs/using-covalues/creation#schemaunion-creation),
[subscribing/loading](/docs/using-covalues/subscription-and-loading) and
[narrowing](/docs/using-covalues/reading#schemaunion-narrowing) SchemaUnions.

## CoValue field/item types

Now that we've seen the different types of CoValues, let's see more precisely how we declare the fields or items they contain.

### Primitive fields

You can declare primitive field types using the `co` declarer:

<CodeGroup>
{/* prettier-ignore */}
```ts

export class Person extends CoMap {
    title = co.string;
}

export class ListOfColors extends CoList.Of(co.string) {}
```
</CodeGroup>

Here's a quick overview of the primitive types you can use:

<CodeGroup>
{/* prettier-ignore */}
```ts
co.string;
co.number;
co.boolean;
co.null;
co.Date;
co.literal("waiting", "ready");
```
</CodeGroup>

Finally, for more complex JSON data, that you *don't want to be collaborative internally* (but only ever update as a whole), you can use `co.json<T>()`:

<CodeGroup>
{/* prettier-ignore */}
```ts
co.json<{ name: string }>();
```
</CodeGroup>

For more detail, see the API Reference for the [`co` field declarer](/api-reference/jazz-tools#co).

### Refs to other CoValues

To represent complex structured data with Jazz, you form trees or graphs of CoValues that reference each other.

Internally, this is represented by storing the IDs of the referenced CoValues in the corresponding fields, but Jazz abstracts this away, making it look like nested CoValues you can get or assign/insert.

The important caveat here is that **a referenced CoValue might or might not be loaded yet,** but we'll see what exactly that means in [Subscribing and Deep Loading](/docs/using-covalues/subscription-and-loading).

In Schemas, you declare Refs using the `co.ref<T>()` declarer:

<CodeGroup>
{/* prettier-ignore */}
```ts
class Company extends CoMap {
    members = co.ref(ListOfPeople);
}

class ListOfPeople extends CoList.Of(co.ref(Person)) {}
```
</CodeGroup>

#### Optional Refs

⚠️ If you want to make a referenced CoValue field optional, you *have to* use `co.optional.ref<T>()`: ⚠️

<CodeGroup>
{/* prettier-ignore */}
```ts
class Person extends CoMap {
    pet = co.optional.ref(Pet);
}
```
</CodeGroup>

### Computed fields & methods

Since CoValue schemas are based on classes, you can easily add computed fields and methods:

<CodeGroup>
{/* prettier-ignore */}
```ts
class Person extends CoMap {
    firstName = co.string;
    lastName = co.string;
    dateOfBirth = co.Date;

get name() {
        return `${this.firstName} ${this.lastName}`;
    }

ageAsOf(date: Date) {
        return differenceInYears(date, this.dateOfBirth);
    }
}
```
</CodeGroup>

#### Accounts & migrations

# Accounts & Migrations

## CoValues as a graph of data rooted in accounts

Compared to traditional relational databases with tables and foreign keys,
Jazz is more like a graph database, or GraphQL APIs —
where CoValues can arbitrarily refer to each other and you can resolve references without having to do a join.
(See [Subscribing & deep loading](/docs/using-covalues/subscription-and-loading)).

To find all data related to a user, the account acts as a root node from where you can resolve all the data they have access to.
These root references are modeled explicitly in your schema, distinguishing between data that is typically public
(like a user's profile) and data that is private (like their messages).

### `Account.root` - private data a user cares about

Every Jazz app that wants to refer to per-user data needs to define a custom root `CoMap` schema and declare it in a custom `Account` schema as the `root` field:

<CodeGroup>
{/* prettier-ignore */}
```ts

export class MyAppAccount extends Account {
  root = co.ref(MyAppRoot);
}

export class MyAppRoot extends CoMap {
  myChats = co.ref(ListOfChats);
  myContacts = co.ref(ListOfAccounts);
}
```
</CodeGroup>

### `Account.profile` - public data associated with a user

The built-in `Account` schema class comes with a default `profile` field, which is a CoMap (in a Group with `"everyone": "reader"` - so publicly readable permissions)
that is set up for you based on the username the `AuthMethod` provides on account creation.

Their pre-defined schemas roughly look like this:

<CodeGroup>
{/* prettier-ignore */}
```ts
// ...somehwere in jazz-tools itself...
export class Account extends Group {
  profile = co.ref(Profile);
}

export class Profile extends CoMap {
  name = co.string;
}
```
</CodeGroup>

If you want to keep the default `Profile` schema, but customise your account's private `root`, all you have to do is define a new `root` field in your account schema:

(You don't have to explicitly re-define the `profile` field, but it makes it more readable that the Account contains both `profile` and `root`)

<CodeGroup>
{/* prettier-ignore */}
```ts

export class MyAppAccount extends Account {
  profile = co.ref(Profile);
  root = co.ref(MyAppRoot);
}
```
</CodeGroup>
If you want to extend the `profile` to contain additional fields (such as an avatar `ImageDefinition`), you can declare your own profile schema class that extends `Profile`:

<CodeGroup>
{/* prettier-ignore */}
```ts

export class MyAppAccount extends Account {
  profile = co.ref(MyAppProfile);
  root = co.ref(MyAppRoot);// old
}

export class MyAppRoot extends CoMap {// old
  myChats = co.ref(ListOfChats);// old
  myContacts = co.ref(ListOfAccounts);// old
}// old

export class MyAppProfile extends Profile {
  name = co.string; // compatible with default Profile schema
  avatar = co.optional.ref(ImageDefinition);
}
```
</CodeGroup>

## Resolving CoValues starting at `profile` or `root`

<ContentByFramework framework="react">
To use per-user data in your app, you typically use `useAccount` somewhere in a high-level component, specifying which references to resolve using a depth-spec (see [Subscribing & deep loading](/docs/using-covalues/subscription-and-loading)).

<CodeGroup>
{/* prettier-ignore */}
```tsx

function DashboardPageComponent() {
  const { me } = useAccount({ profile: {}, root: { myChats: {}, myContacts: {}}});

return <div>
    <h1>Dashboard</h1>
    {me ? <div>
      <p>Logged in as {me.profile.name}</p>
      <h2>My chats</h2>
      {me.root.myChats.map((chat) => <ChatPreview key={chat.id} chat={chat} />)}
      <h2>My contacts</h2>
      {me.root.myContacts.map((contact) => <ContactPreview key={contact.id} contact={contact} />)}
    </div> : "Loading..."}
  </div>
}

```
</CodeGroup>
</ContentByFramework>

## Populating and evolving `root` and `profile` schemas with migrations

As you develop your app, you'll likely want to

- initialise data in a user's `root` and `profile`
- add more data to your `root` and `profile` schemas

You can achieve both by overriding the `migrate()` method on your `Account` schema class.

### When migrations run

Migrations are run after account creation and every time a user logs in.
Jazz waits for the migration to finish before passing the account to your app's context.

### Initialising user data after account creation

<CodeGroup>
{/* prettier-ignore */}
```ts
export class MyAppAccount extends Account {
  root = co.ref(MyAppRoot);

async migrate() {
    // we specifically need to check for undefined, 
    // because the root might simply be not loaded (`null`) yet
    if (this.root === undefined) {
      this.root = MyAppRoot.create({
        // Using a group to set the owner is always a good idea.
        // This way if in the future we want to share 
        // this coValue we can do so easily.
        myChats: ListOfChats.create([], Group.create()),
        myContacts: ListOfAccounts.create([], Group.create())
      });
    }
  }
}
```
</CodeGroup>

### Adding/changing fields to `root` and `profile`

To add new fields to your `root` or `profile` schemas, amend their corresponding schema classes with new fields,
and then implement a migration that will populate the new fields for existing users (by using initial data, or by using existing data from old fields).

To do deeply nested migrations, you might need to use the asynchronous `ensureLoaded()` method before determining whether the field already exists, or is simply not loaded yet.

Now let's say we want to add a `myBookmarks` field to the `root` schema:

<CodeGroup>
{/* prettier-ignore */}
```ts
export class MyAppAccount extends Account {
    root = co.ref(MyAppRoot);// old

async migrate() { // old
      if (this.root === undefined) {  // old
        this.root = MyAppRoot.create({  // old
          myChats: ListOfChats.create([], Group.create()),  // old
          myContacts: ListOfAccounts.create([], Group.create()) // old
        }); // old
      } // old

// We need to load the root field to check for the myContacts field
      const result = await this.ensureLoaded({
        root: {},
      });

const { root } = result;

// we specifically need to check for undefined, 
      // because myBookmarks might simply be not loaded (`null`) yet 
      if (root.myBookmarks === undefined) {
        root.myBookmarks = ListOfBookmarks.create([], Group.create());
      }
    }
  }
```
</CodeGroup>

{/* 
 TODO: Add best practice: only ever add fields

Note: explain and reassure that there will be more guardrails in the future 
 https://github.com/garden-co/jazz/issues/1160
*/}

### Groups, permissions & sharing

#### Groups as permission scopes

# Groups as permission scopes

Every CoValue has an owner, which can be a `Group` or an `Account`.

You can use a `Group` to grant access to a CoValue to multiple users. These users can
have different roles, such as "writer", "reader" or "admin".

...more docs coming soon

## Creating a Group

Here's how you can create a `Group`.

<CodeGroup>
```tsx

const group = Group.create({ owner: me });
```
</CodeGroup>

The `Group` itself is a CoValue, and whoever owns it is the initial admin.

You typically add members using [public sharing](/docs/groups/sharing#public-sharing) or [invites](/docs/groups/sharing#invites).
But if you already know their ID, you can add them directly (see below).

## Adding group members by ID

You can add group members by ID by using `Account.load` and `Group.addMember`.

<CodeGroup>
```tsx

const group = Group.create();

const bob = await Account.load(bobsID, []);
group.addMember(bob, "writer");
```
</CodeGroup>

Note: if the account ID is of type `string`, because it comes from a URL parameter or something similar, you need to cast it to `ID<Account>` first:

<CodeGroup>
```tsx

const bob = await Account.load(bobsID as ID<Account>, []);
group.addMember(bob, "writer");
```
</CodeGroup>
...more docs coming soon

## Getting the Group of an existing CoValue

You can get the group of an existing CoValue by using `coValue._owner`.

<CodeGroup>
```tsx
const group = existingCoValue._owner;
const newValue = MyCoMap.create(
  { color: "red"},
  { owner: group }
);
```
</CodeGroup>

Because `._owner` can be an `Account` or a `Group`, in cases where you specifically need to use `Group` methods (such as for adding members or getting your own role), you can cast it to assert it to be a Group:

<CodeGroup>
```tsx

const group = existingCoValue._owner.castAs(Group);
group.addMember(bob, "writer");
group.myRole();
```
</CodeGroup>
...more docs coming soon

#### Public sharing & invites

# Public sharing and invites

...more docs coming soon

## Public sharing

You can share CoValues publicly by setting the `owner` to a `Group`, and granting
access to "everyone".

<CodeGroup>
  ```ts
  const group = Group.create();
  group.addMember("everyone", "writer"); // *highlight*
  ```
</CodeGroup>

This is done in the [chat example](https://github.com/garden-co/jazz/tree/main/examples/chat) where anyone can join the chat, and send messages.

You can also [add members by Account ID](/docs/groups/intro#adding-group-members-by-id).

## Invites

You can grant users access to a CoValue by sending them an invite link.

This is used in the [pet example](https://github.com/garden-co/jazz/tree/main/examples/pets)
and the [todo example](https://github.com/garden-co/jazz/tree/main/examples/todo).

<ContentByFramework  framework="react">
<CodeGroup>
```ts

createInviteLink(organization, "writer"); // or reader, or admin
```
</CodeGroup>
</ContentByFramework>

<ContentByFramework  framework="react-native">
<CodeGroup>
```ts

createInviteLink(organization, "writer"); // or reader, or admin
```
</CodeGroup>
</ContentByFramework>

<ContentByFramework  framework="vue">
<CodeGroup>
```ts

createInviteLink(organization, "writer"); // or reader, or admin
```
</CodeGroup>
</ContentByFramework>

<ContentByFramework  framework="svelte">
<CodeGroup>
```ts

createInviteLink(organization, "writer"); // or reader, or admin
```
</CodeGroup>
</ContentByFramework>

It generates a URL that looks like `.../invite/[CoValue ID]/[inviteSecret]`

In your app, you need to handle this route, and let the user accept the invitation,
as done [here](https://github.com/garden-co/jazz/tree/main/examples/pets/src/2_main.tsx).

<CodeGroup>
```ts
useAcceptInvite({
  invitedObjectSchema: PetPost,
  onAccept: (petPostID) => navigate("/pet/" + petPostID),
});
```
</CodeGroup>

#### Group inheritance

# Group Inheritance

Groups can inherit members from other groups using the `extend` method.

When a group extends another group, members of the parent group will become automatically part of the child group.

## Basic Usage

Here's how to extend a group:

<CodeGroup>
```typescript
const playlistGroup = Group.create();
const trackGroup = Group.create();

// This way track becomes visible to the members of playlist
trackGroup.extend(playlistGroup);
```
</CodeGroup>

When you extend a group:
- Members of the parent group get access to the child group
- Their roles are inherited (with some exceptions, see [below](#role-inheritance-rules))
- Removing a member from the parent group also removes their access to child groups

## Inheriting members but overriding their role

In some cases you might want to inherit all members from a parent group but override/flatten their roles to the same specific role in the child group. You can do so by passing an "override role" as a second argument to `extend`:

<CodeGroup>
```typescript
const organizationGroup = Group.create();
organizationGroup.addMember(bob, "admin");

const billingGroup = Group.create();

// This way the members of the organization can only read the billing data
billingGroup.extend(organizationGroup, "reader"); 
```
</CodeGroup>

The "override role" works in both directions:

<CodeGroup>
```typescript
const parentGroup = Group.create();
parentGroup.addMember(bob, "reader");
parentGroup.addMember(alice, "admin");

const childGroup = Group.create();
childGroup.extend(parentGroup, "writer");

// Bob and Alice are now writers in the child group
```
</CodeGroup>

## Multiple Levels of Inheritance

Groups can be extended multiple levels deep:

<CodeGroup>
```typescript
const grandParentGroup = Group.create();
const parentGroup = Group.create();
const childGroup = Group.create();

childGroup.extend(parentGroup);
parentGroup.extend(grandParentGroup);
```
</CodeGroup>

Members of the grandparent group will get access to all descendant groups based on their roles.

## Permission Changes

When you remove a member from a parent group, they automatically lose access to all child groups. We handle key rotation automatically to ensure security.

<CodeGroup>
```typescript
// Remove member from parent
await parentGroup.removeMember(bob);

// Bob loses access to both parent and child groups
```
</CodeGroup>

## Role Inheritance Rules

If the account is already a member of the child group, it will get the more permissive role:
<CodeGroup>
```typescript
const parentGroup = Group.create();
parentGroup.addMember(bob, "reader");

const childGroup = Group.create();
parentGroup.addMember(bob, "writer");
childGroup.extend(parentGroup);

// Bob stays a writer because his role is higher
// than the inherited reader role.
```
</CodeGroup>

When extending groups, only admin, writer and reader roles are inherited:
<CodeGroup>
```typescript
const parentGroup = Group.create();
parentGroup.addMember(bob, "writeOnly");

const childGroup = Group.create();
childGroup.extend(parentGroup);

// Bob does not become a member of the child group
```
</CodeGroup>

To extend a group:

1. The current account must be an admin in the child group
2. The current account must be a member of the parent group

<CodeGroup>
```typescript
const companyGroup = company._owner.castAs(Group)
const teamGroup = Group.create();

// Works only if I'm a member of companyGroup
teamGroup.extend(companyGroup); 
```
</CodeGroup>

## Example: Team Hierarchy

Here's a practical example of using group inheritance for team permissions:

<CodeGroup>
```typescript
// Company-wide group
const companyGroup = Group.create();
companyGroup.addMember(CEO, "admin");

// Team group with elevated permissions
const teamGroup = Group.create();
teamGroup.extend(companyGroup); // Inherits company-wide access
teamGroup.addMember(teamLead, "admin");
teamGroup.addMember(developer, "writer");

// Project group with specific permissions
const projectGroup = Group.create();
projectGroup.extend(teamGroup); // Inherits team permissions
projectGroup.addMember(client, "reader"); // Client can only read project items
```
</CodeGroup>

This creates a hierarchy where:
- The CEO has admin access to everything
- Team members get writer access to team and project content
- Team leads get admin access to team and project content
- The client can only read project content

### Authentication

#### Overview

# Authentication in Jazz

Jazz authentication is based on cryptographic keys ("Account keys"). Their public part represents a user's identity, their secret part lets you act as that user.

When a user loads a Jazz application for the first time, we create a new Account by generating keys and storing them locally.

Without any additional steps the user can use Jazz normally, but they would be limited to use on only one device.

To make Accounts work across devices, you can store/retrieve the account keys from an authentication method by using the corresponding hooks and providers.

<ContentByFramework framework={["react", "vue", "svelte"]}>
## Authentication with passkeys

Passkey authentication is fully local-first and the most secure of the auth methods that Jazz provides (because keys are managed by the device/operating system itself).

It is based on the [Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) and is both very easy to use (using familiar FaceID/TouchID flows) and widely supported.

<ContentByFramework framework="react">
Using passkeys in Jazz is as easy as this:
<CodeGroup>
{/* prettier-ignore */}
```tsx
export function AuthModal({ open, onOpenChange }: AuthModalProps) {
  const [username, setUsername] = useState("");

const auth = usePasskeyAuth({ // Must be inside the JazzProvider!
    appName: "My super-cool web app",
  });

if (auth.state === "signedIn") { // You can also use `useIsAuthenticated()`
    return <div>You are already signed in</div>;
  }

const handleSignUp = async () => {
    await auth.signUp(username);
    onOpenChange(false);
  };

const handleLogIn = async () => {
    await auth.logIn();
    onOpenChange(false);
  };

return (
    <div>
      <button onClick={handleLogIn}>Log in</button>
      <input type="text" value={username} onChange={(e) => setUsername(e.target.value)} />
      <button onClick={handleSignUp}>Sign up</button>
    </div>
  );
}
```
</CodeGroup>
</ContentByFramework>

You can try our passkey authentication using our [passkey example](https://passkey-demo.jazz.tools/) or the [music player demo](https://music-demo.jazz.tools/).

</ContentByFramework>

## Passphrase-based authentication

Passphrase authentication lets users log into any device using a Bitcoin-style passphrase. This means users are themselves responsible for storing the passphrase safely.

The passphrase is generated from the local account certificate using a wordlist of your choice.

You can find a set of ready-to-use wordlists in the [bip39](https://github.com/bitcoinjs/bip39/tree/a7ecbfe2e60d0214ce17163d610cad9f7b23140c/src/wordlists) repository.

<ContentByFramework framework="react">
For example:
<CodeGroup>
{/* prettier-ignore */}
```tsx

export function AuthModal({ open, onOpenChange }: AuthModalProps) {
  const [loginPassphrase, setLoginPassphrase] = useState("");

const auth = usePassphraseAuth({ // Must be inside the JazzProvider!
    wordlist: englishWordlist,
  });

if (auth.state === "signedIn") { // You can also use `useIsAuthenticated()`
    return <div>You are already signed in</div>;
  }

const handleSignUp = async () => {
    await auth.signUp();
    onOpenChange(false);
  };

const handleLogIn = async () => {
    await auth.logIn(loginPassphrase);
    onOpenChange(false);
  };

return (
    <div>
      <label>
        Your current passphrase
        <textarea
          readOnly
          value={auth.passphrase}
          rows={5}
        />
      </label>
      <button onClick={handleSignUp}>I have stored my passphrase</button>
      <label>
        Log in with your passphrase
        <textarea
          value={loginPassphrase}
          onChange={(e) => setLoginPassphrase(e.target.value)}
          placeholder="Enter your passphrase"
          rows={5}
          required
        />
      </label>
      <button onClick={handleLogIn}>Log in</button>
    </div>
  );
}
```
</CodeGroup>
</ContentByFramework>

<ContentByFramework framework="react-native">
For example:
<CodeGroup>
{/* prettier-ignore */}
```tsx

export function AuthModal({ open, onOpenChange }: AuthModalProps) {
  const [loginPassphrase, setLoginPassphrase] = useState("");

const auth = usePassphraseAuth({
    wordlist: englishWordlist,
  });

if (auth.state === "signedIn") {
    return <Text>You are already signed in</Text>;
  }

const handleSignUp = async () => {
    await auth.signUp();
    onOpenChange(false);
  };

const handleLogIn = async () => {
    await auth.logIn(loginPassphrase);
    onOpenChange(false);
  };

return (
    <View>
      <View>
        <Text>Your current passphrase</Text>
        <TextInput
          editable={false}
          value={auth.passphrase}
          multiline
          numberOfLines={5}
        />
      </View>

<View>
        <Text>Log in with your passphrase</Text>
        <TextInput
          value={loginPassphrase}
          onChangeText={setLoginPassphrase}
          placeholder="Enter your passphrase"
          multiline
          numberOfLines={5}
          required
        />
      </View>

You can try our passphrase authentication using our [passphrase example](https://passphrase-demo.jazz.tools/) or the [todo list demo](https://todo-demo.jazz.tools/).

<ContentByFramework framework={["react", "react-native"]}>
## Integration with Clerk

Jazz can be used with [Clerk](https://clerk.com/) to authenticate users.

This authentication method is not fully local-first, because the login and signup need to be done while online. Clerk and anyone who is an admin in the app's Clerk org are trusted with the user's key secret and could impersonate them.

However, once authenticated, your users won't need to interact with Clerk anymore, and are able to use all of Jazz's features without needing to be online.

<ContentByFramework framework="react">
The clerk provider is not built into `jazz-react` and needs the `jazz-react-auth-clerk` package to be installed.
</ContentByFramework>

<ContentByFramework framework="react-native">
The clerk provider is not built into `jazz-react-native` and needs the `jazz-react-native-auth-clerk` package to be installed.
</ContentByFramework>

After installing the package you can use the `JazzProviderWithClerk` component to wrap your app:
<ContentByFramework framework="react">
<CodeGroup>
```tsx

function JazzProvider({ children }: { children: React.ReactNode }) {
  const clerk = useClerk();

return (
    <JazzProviderWithClerk
      clerk={clerk}
      sync={{
        peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
      }}
    >
      {children}
    </JazzProviderWithClerk>
  );
}

createRoot(document.getElementById("root")!).render(
  <ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/">
    <JazzProvider>
      <App />
    </JazzProvider>
  </ClerkProvider>
);
```
</CodeGroup>
</ContentByFramework>
<ContentByFramework framework="react-native">
<CodeGroup>
```tsx

function JazzAndAuth({ children }: { children: React.ReactNode }) {
  const clerk = useClerk();

return (
    <JazzProviderWithClerk
      clerk={clerk}
      sync={{
        peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
      }}
    >
      {children}
    </JazzProviderWithClerk>
  );
}

export default function RootLayout() {
  const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY;

if (!publishableKey) {
    throw new Error(
      "Missing Publishable Key. Please set EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY in your .env",
    );
  }

return (
    <ClerkProvider tokenCache={tokenCache} publishableKey={publishableKey}>
      <ClerkLoaded>
        <JazzAndAuth>
          <Slot />
        </JazzAndAuth>
      </ClerkLoaded>
    </ClerkProvider>
  );
}
```
</CodeGroup>
</ContentByFramework>

<ContentByFramework framework="react">
Then you can use the [Clerk auth methods](https://clerk.com/docs/references/react/overview) to log in and sign up:
<CodeGroup>
{/* prettier-ignore */}
```tsx

export function AuthButton() {
  const { logOut } = useAccount();

const isAuthenticated = useIsAuthenticated();

if (isAuthenticated) {
    return <button onClick={() => logOut()}>Logout</button>;
  }

return <SignInButton />;
}
```
</CodeGroup>
</ContentByFramework>

<ContentByFramework framework="react-native">
Then you can use the [Clerk auth methods](https://clerk.com/docs/references/expo/overview) to log in and sign up:
<CodeGroup>
{/* prettier-ignore */}
```tsx

export function AuthButton() {
  const { logOut } = useAccount();
  const { signIn, setActive, isLoaded } = useSignIn();

const isAuthenticated = useIsAuthenticated();

if (isAuthenticated) {
    return <button onClick={() => logOut()}>Logout</button>;
  }

// Login code with Clerk Expo
}
```
</CodeGroup>
</ContentByFramework>
</ContentByFramework>

## Migrating data from anonymous to authenticated account

You may want allow your users to use your app without authenticating (a poll response for example). When *signing up* their anonymous account is transparently upgraded using the provided auth method, keeping the data stored in the account intact.

However, a user may realise that they already have an existing account *after using the app anonymously and having already stored data in the anonymous account*.

When they now *log in*, by default the anonymous account will be discarded and this could lead to unexpected data loss.

To avoid this situation we provide the `onAnonymousAccountDiscarded` handler to migrate the data from the anonymous account to the existing authenticated one.

This is an example from our [music player](https://github.com/garden-co/jazz/tree/main/examples/music-player):
<CodeGroup>
```ts
export async function onAnonymousAccountDiscarded(
  anonymousAccount: MusicaAccount,
) {
  const { root: anonymousAccountRoot } = await anonymousAccount.ensureLoaded({
    root: {
      rootPlaylist: {
        tracks: [{}],
      },
    },
  });

const me = await MusicaAccount.getMe().ensureLoaded({
    root: {
      rootPlaylist: {
        tracks: [],
      },
    },
  });

for (const track of anonymousAccountRoot.rootPlaylist.tracks) {
    if (track.isExampleTrack) continue;

const trackGroup = track._owner.castAs(Group);
    trackGroup.addMember(me, "admin");

me.root.rootPlaylist.tracks.push(track);
  }
}
```
</CodeGroup>

To see how this works in reality we suggest you to try 
to upload a song in the [music player demo](https://music-demo.jazz.tools/) and then
try to log in with an existing account.

## Disable network sync for anonymous users

You can disable network sync to make your app local-only under specific circumstances.

For example, you may want to give the opportunity to non-authenticated users to try your app locally-only (incurring no sync traffic), then enable the network sync only when the user is authenticated:
<CodeGroup>
```tsx
<JazzProvider
  sync={{
    peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
     // This makes the app work in local mode when the user is anonymous
    when: "signedUp",
  }}
>
  <App />
</JazzProvider>
```
</CodeGroup>

For more complex behaviours, you can manually control sync by statefully switching when between `"always"` and `"never"`.

### Design patterns

#### Form

# Creating and updating CoValues in a form

Normally, we implement forms using
[the onSubmit handler](https://react.dev/reference/react-dom/components/form#handle-form-submission-on-the-client),
or by making [a controlled form with useState](https://christinakozanian.medium.com/building-controlled-forms-with-usestate-in-react-f9053ad255a0),
or by using special libraries like [react-hook-form](https://www.react-hook-form.com).

In Jazz, we can do something simpler and more powerful, because CoValues give us reactive,
persisted state which we can use to directly edit live objects, and represent auto-saved drafts.

[See the full example here.](https://github.com/garden-co/jazz/tree/main/examples/form)

## Updating a CoValue

To update a CoValue, we simply assign the new value directly as changes happen. These changes are synced to the server, so
we don't need to handle form submissions either.

<CodeGroup>
```tsx
<input
  type="text"
  value={order.name}
  onChange={(e) => order.name = e.target.value}
/>
```
</CodeGroup>

This means we can write update forms in fewer lines of code.

## Creating a CoValue

However, when creating a CoValue, the CoValue does not exist yet, so we don't have the advantages previously mentioned.

There's a way around this, and it provides unexpected benefits too.

### Using a Draft CoValue

Let's say we have a CoValue called `BubbleTeaOrder`. We can create a "draft" CoValue,
which is an empty version of a `BubbleTeaOrder`, that we can then modify when we are "creating"
a new CoValue.

A `DraftBubbleTeaOrder` is essentially a copy of `BubbleTeaOrder`, but with all the fields made optional.

<CodeGroup>
```tsx
// schema.ts
export class BubbleTeaOrder extends CoMap {
  name = co.string;
}

export class DraftBubbleTeaOrder extends CoMap {
  name = co.optional.string;
}
```
</CodeGroup>

## Writing the components in React

Let's write the form component that will be used for both create and update.

<CodeGroup>
```tsx
// OrderForm.tsx
export function OrderForm({
  order,
  onSave,
}: {
  order: BubbleTeaOrder | DraftBubbleTeaOrder;
  onSave?: (e: React.FormEvent<HTMLFormElement>) => void;
}) {
  return (
    <form onSubmit={onSave}>
      <label>
        Name
        <input
          type="text"
          value={order.name}
          onChange={(e) => (order.name = e.target.value)}
          required
        />
      </label>

{onSave && <button type="submit">Submit</button>}
    </form>
  );
}
```
</CodeGroup>

### Writing the edit form

To make the edit form, simply pass the `BubbleTeaOrder`.

<CodeGroup>
```tsx
// EditOrder.tsx
export function EditOrder(props: { id: ID<BubbleTeaOrder> }) {
  const order = useCoState(BubbleTeaOrder, props.id, []);

if (!order) return;

return <OrderForm order={order} />;
}
```
</CodeGroup>

### Writing the create form

For the create form, we need to:
1. Create a draft order.
2. Edit the draft order.
3. Convert the draft order to a "real" order on submit.

Here's how that looks like:

<CodeGroup>
```tsx
// CreateOrder.tsx
export function CreateOrder() {
  const { me } = useAccount();
  const [draft, setDraft] = useState<DraftBubbleTeaOrder>();

useEffect(() => {
    setDraft(DraftBubbleTeaOrder.create({}));
  }, [me?.id]);

const onSave = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    if (!draft) return;

const order = draft as BubbleTeaOrder;

console.log("Order created:", order);
  };

if (!draft) return;

return <OrderForm order={draft} onSave={onSave} />;
}
```
</CodeGroup>

## Validation

In a `BubbleTeaOrder`, the `name` field is required, so it would be a good idea to validate this before turning the draft into a real order.

Update the schema to include a `validate` method.

<CodeGroup>
```ts
// schema.ts
export class DraftBubbleTeaOrder extends CoMap { // old
  name = co.optional.string; // old

validate() {
    const errors: string[] = [];

if (!this.name) {
      errors.push("Please enter a name.");
    }

return { errors };
  }
} // old
```
</CodeGroup>

Then perform the validation on submit.

<CodeGroup>
```tsx
// CreateOrder.tsx
export function CreateOrder() { // old
  const { me } = useAccount(); // old
  const [draft, setDraft] = useState<DraftBubbleTeaOrder>(); // old

useEffect(() => { // old
    setDraft(DraftBubbleTeaOrder.create({})); // old
  }, [me?.id]); // old

const onSave = (e: React.FormEvent<HTMLFormElement>) => { // old
    e.preventDefault(); // old
    if (!draft) return; // old

const validation = draft.validate();
    if (validation.errors.length > 0) {
      console.log(validation.errors);
      return;
    }

const order = draft as BubbleTeaOrder; // old

console.log("Order created:", order); // old
  }; // old

if (!draft) return; // old

return <OrderForm order={draft} onSave={onSave} />; // old
} // old
```
</CodeGroup>

## Saving the user's work-in-progress

It turns out that using this pattern also provides a UX improvement.

By storing the draft in the user's account, they can come back to it anytime without losing their work. 🙌

<CodeGroup>
```ts
// schema.ts
export class BubbleTeaOrder extends CoMap { // old
  name = co.string; // old
} // old

export class DraftBubbleTeaOrder extends CoMap { // old
  name = co.optional.string; // old
} // old

export class AccountRoot extends CoMap {
  draft = co.ref(DraftBubbleTeaOrder);
}

export class JazzAccount extends Account {
  root = co.ref(AccountRoot);

migrate(this: JazzAccount, creationProps?: { name: string }) {
    if (this.root === undefined) {
      const draft = DraftBubbleTeaOrder.create({});

this.root = AccountRoot.create({ draft });
    }
  }
}
```
</CodeGroup>

Let's not forget to update the `AccountSchema`.

<CodeGroup>
```ts

export function MyJazzProvider({ children }: { children: React.ReactNode }) { // old
    return ( // old
        <JazzProvider // old
            sync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com" }}
            AccountSchema={JazzAccount}
        >// old
            {children} // old
        </JazzProvider> // old
    ); // old
} // old

// Register the Account schema so `useAccount` returns our custom `JazzAccount`
declare module "jazz-react" {
    interface Register {
        Account: JazzAccount;
    }
}
  ```
</CodeGroup>

Instead of creating a new draft every time we use the create form, let's use the draft from the account root.

<CodeGroup>
```tsx
// CreateOrder.tsx
export function CreateOrder() {// old
  const { me } = useAccount({ root: { draft: {} } });

if (!me?.root) return;

const onSave = (e: React.FormEvent<HTMLFormElement>) => {// old
    e.preventDefault();// old

const draft = me.root.draft;
    if (!draft) return;

const validation = draft.validate();// old
    if (validation.errors.length > 0) {// old
      console.log(validation.errors);// old
      return;// old
    }// old

const order = draft as BubbleTeaOrder;// old
    console.log("Order created:", order);// old

// create a new empty draft
    me.root.draft = DraftBubbleTeaOrder.create(
      {},
    );
  };// old

return <CreateOrderForm id={me.root.draft.id} onSave={onSave} />
} // old

function CreateOrderForm({
  id,
  onSave,
}: {
  id: ID<DraftBubbleTeaOrder>;
  onSave: (e: React.FormEvent<HTMLFormElement>) => void;
}) {
  const draft = useCoState(DraftBubbleTeaOrder, id);

if (!draft) return;

return <OrderForm order={draft} onSave={onSave} />;
}
```
</CodeGroup>

When the new draft is created, we need to call `useCoState` again, so that we are passing the new draft to `<OrderForm/>`.

There you have it! Notice that when you refresh the page, you will see your unsaved changes.

## Draft indicator

To improve the UX even further, in just a few more steps, we can tell the user that they currently have unsaved changes.

Simply add a `hasChanges` checker to your schema.

<CodeGroup>
```ts
// schema.ts
export class DraftBubbleTeaOrder extends CoMap { // old
  name = co.optional.string; // old

validate() { // old
    const errors: string[] = []; // old

if (!this.name) { // old
      errors.push("Plese enter a name."); // old
    } // old

return { errors }; // old
  } // old

get hasChanges() {
    return Object.keys(this._edits).length;
  }
} // old
```
</CodeGroup>

In the UI, you can choose how you want to show the draft indicator.

<CodeGroup>
```tsx
// DraftIndicator.tsx
export function DraftIndicator() {
  const { me } = useAccount({
    root: { draft: {} },
  });

if (me?.root.draft?.hasChanges) {
    return (
      <p>You have a draft</p>
    );
  }
}
```
</CodeGroup>

A more subtle way is to show a small dot next to the Create button.

<div className="not-prose border p-5 text-center">
  <button type="button" className="relative border rounded-md py-2 px-4 text-center shadow-sm">
    Create order
    <span
      title="You have a draft"
      className="absolute -top-1 -right-1 bg-blue-500 border-2 border-white w-3 h-3 rounded-full dark:border-stone-925"
    >
    </span>
  </button>
</div>

## Handling different types of data

Forms can be more complex than just a single string field, so we've put together an example app that shows you
how to handle single-select, multi-select, date, and boolean inputs.

[See the full example here.](https://github.com/garden-co/jazz/tree/main/examples/form)

<CodeGroup>
```tsx
export class BubbleTeaOrder extends CoMap {
  baseTea = co.literal(...BubbleTeaBaseTeaTypes);
  addOns = co.ref(ListOfBubbleTeaAddOns);
  deliveryDate = co.Date;
  withMilk = co.boolean;
  instructions = co.optional.string;
}
  ```
</CodeGroup>

#### Organization/Team

# Sharing data through Organizations

Organizations are a way to share a set of data between users.
Different apps have different names for this concept, such as "teams" or "workspaces".

We'll use the term Organization.

[See the full example here.](https://github.com/garden-co/jazz/tree/main/examples/organization)

## Defining the schema for an Organization

Create a CoMap shared by the users of the same organization to act as a root (or "main database") for the shared data within an organization.

For this example, users within an `Organization` will be sharing `Project`s.

<CodeGroup>
```ts
// schema.ts
export class Project extends CoMap {
  name = co.string;
}

export class ListOfProjects extends CoList.Of(co.ref(Project)) {}

export class Organization extends CoMap {
  name = co.string;

// shared data between users of each organization
  projects = co.ref(ListOfProjects);
}

export class ListOfOrganizations extends CoList.Of(co.ref(Organization)) {}
```
</CodeGroup>

Learn more about [defining schemas](/docs/schemas/covalues).

## Adding a list of Organizations to the user's Account

Let's add the list of `Organization`s to the user's Account `root` so they can access them.

<CodeGroup>
```ts
// schema.ts
export class JazzAccountRoot extends CoMap {
  organizations = co.ref(ListOfOrganizations);
}

export class JazzAccount extends Account {
  root = co.ref(JazzAccountRoot);

async migrate() {
    if (this.root === undefined) {
      // Using a Group as an owner allows you to give access to other users
      const organizationGroup = Group.create();

const organizations = ListOfOrganizations.create(
        [
          // Create the first Organization so users can start right away
          Organization.create(
            {
              name: "My organization",
              projects: ListOfProjects.create([], organizationGroup),
            },
            organizationGroup,
          ),
        ],
      );

this.root = JazzAccountRoot.create(
        { organizations },
      );
    }
  }
}
```
</CodeGroup>

This schema now allows users to create `Organization`s and add `Project`s to them.

[See the schema for the example app here.](https://github.com/garden-co/jazz/blob/main/examples/organization/src/schema.ts)

## Adding other users to an Organization

To give users access to an `Organization`, you can either send them an invite link, or
add their `Account` manually.

### Adding users through invite links

Here's how you can generate an [invite link](/docs/groups/sharing#invites).

When the user accepts the invite, add the `Organization` to the user's `organizations` list.

<CodeGroup>
```ts
const onAccept = async (organizationId: ID<Organization>) => {
  const me = await MusicaAccount.getMe().ensureLoaded({
    root: {
      organizations: [],
    },
  });

const organization = await Organization.load(organizationId, []);

if (!organization) throw new Error("Failed to load organization data");

const ids = me.root.organizations.map(
    (organization) => organization?.id,
  );

if (ids.includes(organizationId)) return;

me.root.organizations.push(organization);
  navigate("/organizations/" + organizationId);
};

useAcceptInvite({
  invitedObjectSchema: Organization,
  onAccept,
});
```
</CodeGroup>

### Adding users through their Account ID

...more on this coming soon

## API Reference

## Resources

- [Documentation](https://jazz.tools/docs): Detailed documentation about Jazz

- [Examples](https://jazz.tools/examples): Code examples and tutorials

{issue.title}

Buy terrarium