{ 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> 
    ); 
} 
```
</CodeGroup>

<div className="text-xs uppercase text-muted 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-muted 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-muted">💡 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({ resolve: true }, (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, { resolve: true }, (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, { resolve: true }, 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

export default App; 
```
</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

export default App; 
```
</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

export class Issue extends CoMap { 
    title = co.string; 
    description = co.string; 
    estimate = co.number; 
    status? = co.optional.literal("backlog", "in progress", "done"); 
}

export class ListOfIssues extends CoList.Of(co.ref(Issue)) {} // [!code ++:6]

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

function App() { 
    const [projectID, setProjectID] = useState<ID<Project> | undefined>( // [!code ++:3]
        (window.location.search?.replace("?project=", "") || undefined) as ID<Project> | undefined
    );
    
    const issue = useCoState(Issue, issueID); // [!code --]
    
    const createProject = () => { // [!code ++:14]
        const group = Group.create();
        group.addMember("everyone", "writer");

export default App; 
```
</CodeGroup>

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>
    ) : project === null ? (
        <div>Project not found or access denied</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 resolve queries

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

export function ProjectComponent({ projectID }: { projectID: ID<Project> }) {
    const project = useCoState(
      Project,
      projectID,
      { resolve: { issues: { $each: true } } } // [!code ++]
    );

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) => (
                    <IssueComponent key={issue.id} issue={issue} />
                ))}
                <button onClick={createAndAddIssue}>Create Issue</button>
            </div>
        </div>
    ) : (
        <div>Loading project...</div>
    );
}
```
</CodeGroup>

The resolve query `{ resolve: { issues: { $each: true } } }` means "in `Project`, load `issues` and load each item in `issues` deeply". (Since an `Issue` doesn't have any further references, "deeply" actually means all its properties will be available).

-   Now, we can get rid of a lot of conditional 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

export default App; 
```
</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

export function ProjectComponent({ projectID }: { projectID: ID<Project> }) {
    const project = useCoState(Project, projectID, { resolve: { issues:  { $each: true } } });

const { me } = useAccount(); // [!code ++:6]

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

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

return project ? (
        <div>
            <h1>{project.name}</h1>
            {me.canAdmin(project) && ( // [!code ++:6]
                <>
                    <button onClick={() => invite("reader")}>Invite Guest</button>
                    <button onClick={() => invite("writer")}>Invite Member</button>
                </>
            )}
            <div className="border-r border-b">
                {project.issues.map((issue) => ( 
                    <IssueComponent key={issue.id} issue={issue} /> 
                ))}
                <button onClick={createAndAddIssue}>Create Issue</button>
            </div>
        </div>
    ) : (
        <div>Loading project...</div>
    );
}
```
</CodeGroup>

### Consuming invites

#### Example apps

#### FAQs

# Frequently Asked Questions

## How established is Jazz?

Jazz is backed by fantastic angel and institutional investors with experience and know-how in devtools and has been in development since 2020.

## Will Jazz be around long-term?

We're committed to Jazz being around for a long time! We understand that when you choose Jazz for your projects, you're investing time and making a significant architectural choice, and we take that responsibility seriously.
That's why we've designed Jazz with longevity in mind from the start:

- The open source nature of our sync server means you'll always be able to run your own infrastructure
- Your data remains accessible even if our cloud services change
- We're designing the protocol as an open specification

This approach creates a foundation that can continue regardless of any single company's involvement. The local-first architecture means your apps will always work, even offline, and your data remains yours.

### Project setup

#### Installation

### react-native-expo Implementation

# React Native (Expo) Installation and Setup

Jazz supports Expo through the dedicated `jazz-expo` package, which is specifically designed for Expo applications. If you're building for React Native without Expo, please refer to the [React Native](/docs/react-native/project-setup) guide instead.

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": "~52.0.0", 
"react-native": "0.76.7", 
"react": "18.3.1"
```
</CodeGroup>

## Installation

### 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
# Expo dependencies
npx expo install expo-linking expo-secure-store expo-file-system @react-native-community/netinfo @bam.tech/react-native-image-resizer

# React Native polyfills
npm i -S @azure/core-asynciterator-polyfill react-native-url-polyfill readable-stream react-native-get-random-values @craftzdog/react-native-buffer

# Jazz dependencies
npm i -S jazz-tools jazz-expo 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`, `base-64`, and you can drop `@bacons/text-decoder`.

#### Fix incompatible dependencies

If you encounter incompatible dependencies, you can try to fix them with the following command:

<CodeGroup>
```bash
npx expo install --fix
```
</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 twoslash
// @noErrors: 2304
// metro.config.js
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 twoslash
// @noErrors: 2304
// metro.config.js
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)

If you're using `pnpm`, you'll need to make sure that your expo app's `package.json` has this:

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

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

## Authentication

Jazz provides authentication to help users access their data across multiple devices. For details on implementing authentication with Expo, check our [Authentication Overview](/docs/authentication/overview) guide and see the [Expo Chat Demo](https://github.com/garden-co/jazz/tree/main/examples/chat-rn-expo-clerk) for a complete example.

## Next Steps

Now that you've set up your Expo project for Jazz, you'll need to:

1. [Set up the Jazz Provider](/docs/react-native-expo/project-setup/providers) - Configure how your app connects to Jazz
2. [Add authentication](/docs/authentication/overview) (optional) - Enable users to access data across devices
3. Define your schema - See the [schema docs](/docs/schemas/covalues) for more information
4. Run your app:

<CodeGroup>
```sh
npx expo run:ios
# or
npx expo run:android
```
</CodeGroup>

## Verification

Ready to see if everything's working? Let's fire up your app:

<CodeGroup>
```sh
npx expo run:ios
# or
npx expo run:android
```
</CodeGroup>

If all goes well, your app should start up without any angry red error screens. Take a quick look at the Metro console too - no Jazz-related errors there means you're all set! If you see your app's UI come up smoothly, you've nailed the installation.

If you run into any issues that aren't covered in the Common Issues section, [drop by our Discord for help](https://discord.gg/utDMjHYg42).

## Common Issues

- **Metro bundler errors**: If you see errors about missing polyfills, ensure all polyfills are properly imported.
- **iOS build failures**: Make sure you've run `pod install` after adding the dependencies.
- **Android build failures**: Ensure you've run `npx expo prebuild` to generate native code.
- **Expo Go incompatibility**: Remember that Jazz requires a development build and won't work with Expo Go.

### Install CocoaPods

If you're compiling for iOS, you'll need to install CocoaPods for your project. If you need to install it, we recommend using [`pod-install`](https://www.npmjs.com/package/pod-install):

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

---

### react-native Implementation

# React Native Installation and Setup

This guide covers setting up Jazz for React Native applications from scratch. If you're using Expo, please refer to the [React Native - Expo](/docs/react-native-expo/project-setup) guide instead. If you just want to get started quickly, you can use our [React Native Chat Demo](https://github.com/garden-co/jazz/tree/main/examples/chat-rn) as a starting point.

Jazz supports the [New Architecture](https://reactnative.dev/architecture/landing-page) for React Native.

Tested with:

<CodeGroup>
```json 
"react-native": "0.78.22",
"react": "18.3.1" 
```
</CodeGroup>

## Installation

### Create a new project

(Skip this step if you already have one)

<CodeGroup>
```bash
npx @react-native-community/cli init myjazzapp
cd myjazzapp
```
</CodeGroup>

If you intend to build for iOS, you can accept the invitation to install CocoaPods. If you decline, or you get an error, [you can install it with `pod-install`](#install-cocoapods).

### Install dependencies

<CodeGroup>
```bash
# React Native dependencies
npm install @react-native-community/netinfo @bam.tech/react-native-image-resizer

# React Native polyfills
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 react-native-mmkv

# Jazz dependencies
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`.

### 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 twoslash
// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');

const config = {
  resolver: {
    sourceExts: ["mjs", "js", "json", "ts", "tsx"],
    requireCycleIgnorePatterns: [/(^|\/|\\)node_modules($|\/|\\)/]
  }
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);
```
</CodeGroup>

#### Monorepos

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

<CodeGroup>
```ts twoslash
// metro.config.js
const path = require("path");
const { makeMetroConfig } = require("@rnx-kit/metro-config");
const MetroSymlinksResolver = require("@rnx-kit/metro-resolver-symlinks");

// Define workspace root
const projectRoot = __dirname;
const workspaceRoot = path.resolve(projectRoot, "../..");

// Add packages paths
const extraNodeModules = {
  modules: path.resolve(workspaceRoot, "node_modules"),
};

const watchFolders = [
  path.resolve(workspaceRoot, "node_modules"),
  path.resolve(workspaceRoot, "packages"),
];

const nodeModulesPaths = [
  path.resolve(projectRoot, "node_modules"),
  path.resolve(workspaceRoot, "node_modules"),
];

module.exports = makeMetroConfig({
  resolver: {
    resolveRequest: MetroSymlinksResolver(),
    extraNodeModules,
    nodeModulesPaths,
  },
  sourceExts: ["mjs", "js", "json", "ts", "tsx"],
  watchFolders,
});
```
</CodeGroup>

### Additional monorepo configuration (for pnpm)

- 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
// package.json
"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@babel/*",
      "typescript"
    ]
  }
}
```
</CodeGroup>

### Add polyfills

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

<CodeGroup>
```ts twoslash
// @noErrors: 7016
// polyfills.js
polyfillGlobal("Buffer", () => Buffer); // polyfill Buffer

polyfillGlobal("ReadableStream", () => ReadableStream); // polyfill ReadableStream

```
</CodeGroup>

Update `index.js`:

<CodeGroup>
```ts twoslash
// @noErrors: 2307
// index.js

AppRegistry.registerComponent(appName, () => App);
```
</CodeGroup>

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

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

## Authentication

Jazz provides authentication to help users access their data across multiple devices. For details on implementing authentication, check our [Authentication Overview](/docs/authentication/overview) guide and see the [React Native Chat Demo](https://github.com/garden-co/jazz/tree/main/examples/chat-rn) for a complete example.

## Next Steps

Now that you've set up your React Native project for Jazz, you'll need to:

1. [Set up the Jazz Provider](/docs/react-native/project-setup/providers) - Configure how your app connects to Jazz
2. [Add authentication](/docs/authentication/overview) (optional) - Enable users to access data across devices
3. Define your schema - See the [schema docs](/docs/schemas/covalues) for more information
4. Run your app:

<CodeGroup>
```sh
npx react-native run-ios
npx react-native run-android
```
</CodeGroup>

## Verification

Ready to see if everything's working? Let's fire up your app:

<CodeGroup>
```sh
npx react-native run-ios
# or
npx react-native run-android
```
</CodeGroup>

If you run into any issues that aren't covered in the Common Issues section, [drop by our Discord for help](https://discord.gg/utDMjHYg42).

## Common Issues

- **Metro bundler errors**: If you see errors about missing polyfills, ensure all polyfills are properly imported in your `polyfills.js` file.
- **iOS build failures**: Make sure you've run `pod install` after adding the dependencies.
- **Android build failures**: Ensure your Android SDK and NDK versions are compatible with the native modules.

### Install CocoaPods

If you're compiling for iOS, you'll need to install CocoaPods for your project. If you need to install it, we recommend using [`pod-install`](https://www.npmjs.com/package/pod-install):

<CodeGroup>
```bash
npx pod-install
```
</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(
    <JazzProvider // [!code ++:6]
        sync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com" }}
        AccountSchema={MyAppAccount}
    >
        <App />
    </JazzProvider>
);

// [!code ++:6]
// 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" // [!code ++]

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.

#### Providers

### react-native-expo Implementation

# Providers

## Introduction

`<JazzProvider />` is the core component that connects your Expo application to Jazz. It handles:

- **Data Synchronization**: Manages connections to peers and the Jazz cloud
- **Local Storage**: Persists data locally between app sessions
- **Schema Types**: Provides APIs for the [AccountSchema](/docs/schemas/accounts-and-migrations)
- **Authentication**: Connects your authentication system to Jazz

## Setting up the provider

Wrap your app components with the `<JazzProvider />` component:

<CodeGroup>
```tsx twoslash
// @noErrors: 2307 7031 2304 2686 2664
// App.tsx

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-expo" {
  interface Register {
    Account: MyAppAccount;
  }
}
```
</CodeGroup>

## Provider Options

- `kvStore`
  - `ExpoSecureStoreAdapter` (default)
- `AccountSchema`
  - `Account` (default)
- `CryptoProvider`
  - `PureJSCrypto` (default) - Pure JavaScript crypto provider
  - `RNQuickCrypto` - C++ accelerated crypto provider

## Authentication in the Provider

`<JazzProvider />` works with various authentication methods, with PassphraseAuth being the easiest way to get started for development and testing. For authentication details, refer to our [Authentication Overview](/docs/authentication/overview) guide.

The authentication hooks must always be used inside the `<JazzProvider />` component.

Implementing PassphraseAuth is straightforward:

1. Import the [wordlist](https://github.com/bitcoinjs/bip39/tree/a7ecbfe2e60d0214ce17163d610cad9f7b23140c/src/wordlists) for generating recovery phrases
2. Use the `usePassphraseAuth` hook to handle authentication 
3. Create simple registration and sign-in screens

<CodeGroup>
```tsx twoslash
// @noErrors: 2307
function SignInScreen({ auth }: { auth: any }) {
  return null;
}
// ---cut-before---
// Example with PassphraseAuth

function JazzAuthentication({ children }: { children: ReactNode }) {
  const auth = usePassphraseAuth({
    wordlist: englishWordlist,
  });

// If the user is already signed in, render the App
  if (auth.state === "signedIn") {
    return children
  }
  
  // Otherwise, show a sign-in screen
  return <SignInScreen auth={auth} />;
}

function AuthenticatedProvider({ children }: { children: ReactNode }) {
  return (
    <JazzProvider
      sync={{ peer: "wss://cloud.jazz.tools/?key=your-api-key" }}
    >
      <JazzAuthentication>
        {children}
      </JazzAuthentication>
    </JazzProvider>
  );
}
```
</CodeGroup>

For a complete example, see the [Expo Chat Demo](https://github.com/garden-co/jazz/tree/main/examples/chat-rn-expo).

## Local Persistence

Jazz for Expo includes built-in local persistence using SQLite. Following Expo's best practices, the Expo implementation uses:

- **Database Storage**: `expo-sqlite` - Expo's official SQLite module
- **Key-Value Storage**: `expo-secure-store` - Expo's secure storage system

Local persistence is enabled by default with no additional configuration required. Your data will automatically persist across app restarts.

---

### react-native Implementation

# Providers

## Introduction

`<JazzProvider />` is the core component that connects your React Native application to Jazz. It handles:

## Setting up the provider

Wrap your app components with the `<JazzProvider />` component:

<CodeGroup>
```tsx twoslash
// @noErrors: 2307 2686 2664
// App.tsx

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

## Provider Options

- `kvStore`
  - `MMKVStoreAdapter` (default)
- `AccountSchema`
  - `Account` (default)
- `CryptoProvider`
  - `PureJSCrypto` (default) - Pure JavaScript crypto provider
  - `RNQuickCrypto` - C++ accelerated crypto provider

## Authentication in the Provider

The authentication hooks must always be used inside the `<JazzProvider />` component.

Implementing PassphraseAuth is straightforward:

<CodeGroup>
```tsx twoslash
// @noErrors: 2307
function SignInScreen({ auth }: { auth: any }) {
  return null;
}
// ---cut-before---
// Example with PassphraseAuth

function JazzAuthentication({ children }: { children: ReactNode }) {
  const auth = usePassphraseAuth({
    wordlist: englishWordlist,
  });

// If the user is already signed in, render the App
  if (auth.state === "signedIn") {
    return children
  }
  
  // Otherwise, show a sign-in screen
  return <SignInScreen auth={auth} />;
}

## Local Persistence

Jazz for React Native includes built-in local persistence using SQLite. This implementation uses:

- **Database Storage**: `@op-engineering/op-sqlite` - A high-performance SQLite implementation
- **Key-Value Storage**: `react-native-mmkv` - A fast key-value storage system

Local persistence is enabled by default with no additional configuration required. Your data will automatically persist across app restarts.

### Tools

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

#### create-jazz-app

# create-jazz-app

Jazz comes with a CLI tool that helps you quickly scaffold new Jazz applications. There are two main ways to get started:

1. **Starter templates** - Pre-configured setups to start you off with your preferred framework
2. **Example apps** - Extend one of our [example applications](https://jazz.tools/examples) to build your project

## Quick Start with Starter Templates

Create a new Jazz app from a starter template in seconds:

<CodeGroup>
```bash
npx create-jazz-app@latest --api-key you@example.com
```
</CodeGroup>

This launches an interactive CLI that guides you through selecting:
- Pre-configured frameworks and authentication methods (See [Available Starters](#available-starters))
- Package manager
- Project name
- Jazz Cloud API key (optional) - Provides seamless sync and storage for your app

## Command Line Options

If you know what you want, you can specify options directly from the command line:

<CodeGroup>
```bash
# Basic usage with project name
npx create-jazz-app@latest my-app --framework react --api-key you@example.com

# Specify a starter template
npx create-jazz-app@latest my-app --starter react-passkey-auth --api-key you@example.com

# Specify example app
npx create-jazz-app@latest my-app --example chat --api-key you@example.com
```
</CodeGroup>

### Available Options

- `directory` - Directory to create the project in (defaults to project name)
- `-f, --framework` - Framework to use (React, React Native, Svelte, Vue)
- `-s, --starter` - Starter template to use
- `-e, --example` - Example project to use
- `-p, --package-manager` - Package manager to use (npm, yarn, pnpm, bun, deno)
- `-k, --api-key` - Jazz Cloud API key (during our [free public alpha](/docs/react/sync-and-storage#free-public-alpha), you can use your email as the API key)
- `-h, --help` - Display help information

## Start From an Example App

Want to start from one of [our example apps](https://jazz.tools/examples)? Our example apps include specific examples of features and use cases. They demonstrate real-world patterns for building with Jazz. Use one as your starting point:

<CodeGroup>
```bash
npx create-jazz-app@latest --example chat
```
</CodeGroup>

## Available Starters

Starter templates are minimal setups that include the basic configuration needed to get started with Jazz. They're perfect when you want a clean slate to build on.

Choose from these ready-to-use starter templates:

- `react-passkey-auth` - React with Passkey authentication (easiest to start with)
- `react-clerk-auth` - React with Clerk authentication
- `vue-demo-auth` - Vue with Demo authentication
- `svelte-passkey-auth` - Svelte with Passkey authentication
- `rn-clerk-auth` - React Native with Clerk authentication

Run `npx create-jazz-app --help` to see the latest list of available starters.

## What Happens Behind the Scenes

When you run `create-jazz-app`, we'll:

1. Ask for your preferences (or use your command line arguments)
2. Clone the appropriate starter template
3. Update dependencies to their latest versions
4. Install all required packages
5. Set up your project and show next steps

## Requirements

- Node.js 14.0.0 or later
- Your preferred package manager (npm, yarn, pnpm, bun, or deno)

#### 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>
```tsx

This will show the Inspector launch button on the right of your page.

### Positioning the Inspector button

You can also customize the button position with the following options:

- right (default)
- left
- bottom right
- bottom left
- top right
- top left

For example:
<CodeGroup>
```tsx
<JazzInspector position="bottom left"/>
```
</CodeGroup>

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.

### Upgrade guides

#### 0.13.0 - React Native Split

### react-native-expo Implementation

# Upgrade to Jazz 0.13.0 for React Native Expo

Version 0.13.0 introduces a significant architectural change in how Jazz supports React Native applications. We've separated the React Native implementation into two distinct packages to better serve different React Native development approaches:

1. **jazz-expo**: Dedicated package for Expo applications
2. **jazz-react-native**: Focused package for framework-less React Native applications
3. **jazz-react-native-core**: Shared core functionality used by both implementations (probably not imported directly)

This guide focuses on upgrading **Expo applications**. If you're using framework-less React Native, please see the [React Native upgrade guide](/docs/react-native/upgrade/0-13-0).

## Migration Steps for Expo

1. **Update Dependencies**

Remove the old packages and install the new `jazz-expo` package.

<CodeGroup>
```bash
# Remove the old package
npm uninstall jazz-react-native

# Install the new Expo-specific packages
npx expo install expo-sqlite expo-secure-store expo-file-system @react-native-community/netinfo

# Install the new packages
npm install jazz-expo jazz-react-native-media-images
```
</CodeGroup>

2. **Update Imports**

Update your imports to use the new `jazz-expo` package.

<CodeGroup>
```tsx twoslash
// @noErrors: 2300 2307
// Before

// After
```
</CodeGroup>

3. **Update Type Declarations**

Update your type declarations to use the new `jazz-expo` package.

<CodeGroup>
```tsx twoslash
// @noErrors: 2664 2304
// Before
declare module "jazz-react-native" { // [!code --:5]
  interface Register {
    Account: MyAppAccount;
  }
}

// After
declare module "jazz-expo" { // [!code ++:5]
  interface Register {
    Account: MyAppAccount;
  }
}
```
</CodeGroup>

## Clerk Authentication

Clerk authentication has been moved inside the `jazz-expo` package. This is a breaking change that requires updating both your imports and providers.

If you're using Clerk auth in your Expo application, you'll need to:

<CodeGroup>
```tsx twoslash
// @noErrors: 2300 2307
// Before

// After
```
</CodeGroup>

Since Clerk only supports Expo applications, this consolidation makes sense and simplifies your dependency structure. You'll need to completely remove the `jazz-react-native-clerk` package from your dependencies and use the Clerk functionality that's now built into `jazz-expo`.

## Storage Adapter Changes

The `jazz-expo` package now uses:
- `ExpoSQLiteAdapter` for database storage (using `expo-sqlite`)
- `ExpoSecureStoreAdapter` for key-value storage (using `expo-secure-store`)

These are now the default storage adapters in the `JazzProvider` for Expo applications, so you don't need to specify them explicitly.

## Example Provider Setup

<CodeGroup>
```tsx twoslash
// @noErrors: 2300 2307 2686 2664 2435 1005

// Register the Account schema
declare module "jazz-react-native" { // [!code --:5]
  interface Register {
    Account: MyAppAccount;
  }
}
declare module "jazz-expo" { // [!code ++:5]
  interface Register {
    Account: MyAppAccount;
  }
}
```
</CodeGroup>

## New Architecture Support

The `jazz-expo` implementation supports the Expo New Architecture.

## For More Information

For detailed setup instructions, refer to the [React Native Expo Setup Guide](/docs/react-native-expo/project-setup)

---

### react-native Implementation

# Jazz 0.13.0 - React Native Split

1. **[jazz-react-native](https://www.npmjs.com/package/jazz-react-native)**: Focused package for framework-less React Native applications
2. **[jazz-expo](https://www.npmjs.com/package/jazz-expo)**: Dedicated package for Expo applications
3. **[jazz-react-native-core](https://www.npmjs.com/package/jazz-react-native-core)**: Shared core functionality used by both implementations

This guide focuses on upgrading **React Native without Expo** applications. If you're using Expo, please see the [Expo upgrade guide](/docs/react-native-expo/upgrade/0-13-0).

## Migration Steps for React Native

1. **Update Dependencies**
<CodeGroup>
```bash
# Ensure you have the required dependencies
npm install @op-engineering/op-sqlite react-native-mmkv @react-native-community/netinfo

# Remove the old packages
npm install jazz-react-native-expo  # [!code --]

# Install the new packages
npm install jazz-react-native jazz-react-native-media-images # [!code ++]

# Run pod install for iOS
npx pod-install
```
</CodeGroup>
2. **No Import Changes Required**
Your existing imports from `jazz-react-native` should continue to work, but the implementation now uses a different storage solution (op-sqlite and MMKV).
## Storage Adapter Changes
The `jazz-react-native` package now uses:
- `OpSQLiteAdapter` for database storage (using `@op-engineering/op-sqlite`)
- `MMKVStoreAdapter` for key-value storage (using `react-native-mmkv`)
These are now the default storage adapters in the `JazzProvider` for framework-less React Native applications.
## Example Provider Setup
<CodeGroup>
```tsx twoslash
// @noErrors: 2307 2686 2664
// App.tsx
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
declare module "jazz-react-native" {
  interface Register {
    Account: MyAppAccount;
  }
}
```
</CodeGroup>

## New Architecture Support

The `jazz-react-native` implementation fully supports [the React Native New Architecture](https://reactnative.dev/docs/the-new-architecture/landing-page). This includes compatibility with:

- JavaScript Interface (JSI) for more efficient JavaScript-to-native communication
- Fabric rendering system for improved UI performance
- TurboModules for better native module management
- Codegen for type-safe interfaces

No additional configuration is needed to use Jazz with the New Architecture.

## Potential Podfile Issues

If you encounter pod installation issues in a pnpm workspace environment (such as `undefined method '[]' for nil` in the Podfile at the line `config = use_native_modules!`), replace the problematic line with a manual path reference:
<CodeGroup>
```ts
react_native_path = "../node_modules/react-native"
config = { :reactNativePath => react_native_path }
```
</CodeGroup>
This approach bypasses issues with dependency resolution in workspace setups where packages may be hoisted to the root `node_modules`.
## For More Information
For detailed setup instructions, refer to the [React Native Setup Guide](/docs/react-native/project-setup)

#### 0.12.0 - Deeply Resolved Data

# Jazz 0.12.0 - Deeply resolved data

Jazz 0.12.0 makes it easier and safer to load nested data. You can now specify exactly which nested data you want to load, and Jazz will check permissions and handle missing data gracefully. This helps catch errors earlier during development and makes your code more reliable.

## What's new?

- New resolve API for a more type-safe deep loading
- A single, consistent load option for all loading methods
- Improved permission checks on deep loading
- Easier type safety with the `Resolved` type helper

## Breaking changes

### New Resolve API

We're introducing a new resolve API for deep loading, more friendly to TypeScript, IDE autocompletion and LLMs.

**Major changes:**

1. Functions and hooks for loading now take the resolve query as an explicit nested `resolve` prop
2. Shallowly loading a collection is now done with `true` instead of `[]` or `{}`

<CodeGroup>
```tsx twoslash
// @noErrors: 2451
class AccountRoot extends CoMap { friends = co.ref(ListOfAccounts); }
class ListOfAccounts extends CoList.Of(co.ref(Account)) {}
class MyAppAccount extends Account { root = co.ref(AccountRoot);}
declare module "jazz-react" { interface Register { Account: MyAppAccount; } }
// ---cut-before---
// Before
// @ts-expect-error
const { me } = useAccount({ root: { friends: [] } }); // [!code --]

// After
const { me } = useAccount({ // [!code ++]
  resolve: { root: { friends: true } } // [!code ++]
}); // [!code ++]
```
</CodeGroup>

3. For collections, resolving items deeply is now done with a special `$each` key.

For a `CoList`:

<CodeGroup>
```tsx twoslash
// @noErrors: 2451

// ---cut-before---
class Task extends CoMap { }
class ListOfTasks extends CoList.Of(co.ref(Task)) {}

const id = "co_123" as ID<Task>;

// Before
// @ts-expect-error
const tasks = useCoState(ListOfTasks, id, [{}]); // [!code --]

// After
const tasks = useCoState(ListOfTasks, id, { resolve: { $each: true } }); // [!code ++]
```
</CodeGroup>

For a `CoMap.Record`:

<CodeGroup>
```tsx twoslash
// @noErrors: 2451
class MyAppAccount extends Account {}
const id = "co_123" as ID<UsersByUsername>;

// ---cut-before---
class UsersByUsername extends CoMap.Record(co.ref(MyAppAccount)) {}

// Before
// @ts-expect-error
const usersByUsername = useCoState(UsersByUsername, id, [{}]); // [!code --]

// After
const usersByUsername = useCoState(UsersByUsername, id, { // [!code ++]
  resolve: { $each: true } // [!code ++]
}); // [!code ++]
```
</CodeGroup>

Nested loading — note how it's now less terse, but more readable:

<CodeGroup>
```tsx twoslash
// @noErrors: 2451

const id = "co_123" as ID<ListOfTasks>;

// ---cut-before---
class Org extends CoMap {
  name = co.string;
}

class Assignee extends CoMap {
  name = co.string;
  org = co.ref(Org);
}
class ListOfAssignees extends CoList.Of(co.ref(Assignee)) {}

class Task extends CoMap {
  content = co.string;
  assignees = co.ref(ListOfAssignees);
}
class ListOfTasks extends CoList.Of(co.ref(Task)) {}

// Before
// @ts-expect-error
const tasksWithAssigneesAndTheirOrgs = useCoState(ListOfTasks, id, [{ // [!code --]
  assignees: [{ org: {}}]} // [!code --]
]); // [!code --]

// After
const tasksWithAssigneesAndTheirOrgs = useCoState(ListOfTasks, id, { // [!code ++]
  resolve: { // [!code ++]
    $each: { // [!code ++]
      assignees: { // [!code ++]
        $each: { org: true } // [!code ++]
      } // [!code ++]
    } // [!code ++]
  } // [!code ++]
}); // [!code ++]
```
</CodeGroup>

It's also a lot more auto-complete friendly:

<CodeGroup>
```tsx twoslash
// @noErrors: 2451 2353 2581

class Org extends CoMap { name = co.string; }
class Assignee extends CoMap { org = co.ref(Org); }
class ListOfAssignees extends CoList.Of(co.ref(Assignee)) {}
class Task extends CoMap { assignees = co.ref(ListOfAssignees);  }
class ListOfTasks extends CoList.Of(co.ref(Task)) {}
const id = "co_123" as ID<ListOfTasks>;

// ---cut-before---
const tasksWithAssigneesAndTheirOrgs = useCoState(ListOfTasks, id, {
  resolve: {
    $each: {
      assignees: {
        $
//       ^|
      }
    }
  }
});
```
</CodeGroup>

### A single, consistent load option

The new API works across all loading methods, and separating out the resolve query means
other options with default values are easier to manage, for example: loading a value as a specific account instead of using the implicit current account:

<CodeGroup>
```ts twoslash
// @noErrors: 2451

class Track extends CoMap {}
class ListOfTracks extends CoList.Of(co.ref(Track)) {}
class Playlist extends CoMap { tracks = co.ref(ListOfTracks); }
const id = "co_123" as ID<Playlist>;
const otherAccount = {} as Account;

// ---cut-before---
// Before
// @ts-expect-error
Playlist.load(id, otherAccount, { // [!code --]
  tracks: [], // [!code --]
}); // [!code --]

// After
Playlist.load(id, { // [!code ++]
  loadAs: otherAccount, // [!code ++]
  resolve: { tracks: true } // [!code ++]
}); // [!code ++]
```
</CodeGroup>

### Improved permission checks on deep loading

Now `useCoState` will return `null` when the current user lacks permissions to load requested data.

Previously, `useCoState` would return `undefined` if the current user lacked permissions, making it hard to tell if the value is loading or if it's missing.

Now `undefined` means that the value is definitely loading, and `null` means that the value is temporarily missing.

We also have implemented a more granular permission checking, where if an *optional* CoValue cannot be accessed, `useCoState` will return the data stripped of that CoValue.

**Note:** The state handling around loading and error states will become more detailed and easy-to-handle in future releases, so this is just a small step towards consistency.

<CodeGroup>
{/* prettier-ignore */}
```tsx twoslash
// @noErrors: 2451
class Track extends CoMap {}
function TrackComponent({ track }: { track: Track }) {return ""}

// ---cut-before---
class ListOfTracks extends CoList.Of(co.optional.ref(Track)) {}

// After
  const tracks = useCoState(ListOfTracks, id, { resolve: { $each: true } }); // [!code ++]
  if (tracks === undefined) return <div>Loading...</div>; // [!code ++]
  if (tracks === null) return <div>Not found or access denied</div>; // [!code ++]

// This will only show tracks that we have access to and that are loaded.
  return tracks.map(track => track && <TrackComponent track={track} />);
}
```
</CodeGroup>

The same change is applied to the load function, so now it returns `null` instead of `undefined` when the value is missing.

<CodeGroup>
```tsx twoslash
// @noErrors: 2451

class MyCoMap extends CoMap {}
const id = "co_123" as ID<MyCoMap>;

// ---cut-before---
// Before
// @ts-expect-error
const map = await MyCoMap.load(id);
if (map === undefined) {
  throw new Error("Map not found");
}

// After
const map = await MyCoMap.load(id);
if (map === null) {
  throw new Error("Map not found or access denied");
}
```
</CodeGroup>

## New Features

### The `Resolved` type helper

The new `Resolved` type can be used to define what kind of deeply loaded data you expect in your parameters, using the same resolve query syntax as the new loading APIs:

<CodeGroup>
```tsx twoslash
// @noErrors: 2451
class Track extends CoMap {}
class ListOfTracks extends CoList.Of(co.ref(Track)) {}
class Playlist extends CoMap { tracks = co.ref(ListOfTracks); }
function TrackComponent({ track }: { track: Track }) {return ""}

// ---cut-before---
type PlaylistResolved = Resolved<Playlist, {
  tracks: { $each: true }
}>;

function TrackListComponent({ playlist }: { playlist: PlaylistResolved }) {
  // Safe access to resolved tracks
  return playlist.tracks.map(track => <TrackComponent track={track} />);
}
```
</CodeGroup>

#### 0.11.0 - Roles and permissions

# Jazz 0.11.0 is out!

Jazz 0.11.0 brings several improvements to member handling, roles, and permissions management. This guide will help you upgrade your application to the latest version.

## What's new?
Here is what's changed in this release:
- [New permissions check APIs](#new-permissions-check-apis): New methods like `canRead`, `canWrite`, `canAdmin`, and `getRoleOf` to simplify permission checks.
- [Group.revokeExtend](#grouprevokeextend): New method to revoke group extension permissions.
- [Group.getParentGroups](#accountgetparentgroups): New method to get all the parent groups of an account.
- [Account Profile & Migrations](#account-profile--migrations): Fixed issues with custom account profile migrations for a more consistent experience
- [Dropped support for Accounts owning Profiles](#dropped-support-for-accounts-owning-profiles): Profiles can now only be owned by Groups.
- [Group.members now includes inherited members](#member-inheritance-changes): Updated behavior for the `members` getter method to include inherited members and have a more intuitive type definition.

## New Features

### New permissions check APIs

New methods have been added to both `Account` and `Group` classes to improve permission handling:

#### Permission checks

The new `canRead`, `canWrite` and `canAdmin` methods on `Account` allow you to easily check if the account has specific permissions on a CoValue:

<CodeGroup>
{/* prettier-ignore */}
```typescript
const me = Account.getMe();

if (me.canAdmin(value)) {
  console.log("I can share value with others"); 
} else if (me.canWrite(value)) {
  console.log("I can edit value");
} else if (me.canRead(value)) {
  console.log("I can view value");
} else {
  console.log("I cannot access value");
}
```
</CodeGroup>

#### Getting the role of an account

The `getRoleOf` method has been added to query the role of specific entities:

<CodeGroup>
```typescript
const group = Group.create();
group.getRoleOf(me); // admin
group.getRoleOf(Eve); // undefined

group.addMember(Eve, "writer");
group.getRoleOf(Eve); // writer
```
</CodeGroup>

#### Group.revokeExtend

We added a new method to revoke the extend of a Group:
<CodeGroup>
```typescript
function addTrackToPlaylist(playlist: Playlist, track: MusicTrack) {
  const trackGroup = track._owner.castAs(Group);
  trackGroup.extend(playlist._owner, "reader"); // Grant read access to the track to the playlist accounts

playlist.tracks.push(track);
}

function removeTrackFromPlaylist(playlist: Playlist, track: MusicTrack) {
  const trackGroup = track._owner.castAs(Group);
  trackGroup.revokeExtend(playlist._owner); // Revoke access to the track to the playlist accounts
  
  const index = playlist.tracks.findIndex(t => t.id === track.id);
  if (index !== -1) {
    playlist.tracks.splice(index, 1);
  }
}
```
</CodeGroup>

### Group.getParentGroups

The `getParentGroups` method has been added to `Group` to get all the parent groups of a group.

<CodeGroup>
```ts
const childGroup = Group.create();
const parentGroup = Group.create();
childGroup.extend(parentGroup);

console.log(childGroup.getParentGroups()); // [parentGroup]
```
</CodeGroup>

## Breaking Changes

### Account Profile & Migrations

The previous way of making the `Profile` migration work was to assume that the profile was always already there:

<CodeGroup>
```ts
export class MyAppAccount extends Account {
  profile = co.ref(MyAppProfile);

async migrate(this: MyAppAccount, creationProps: { name: string, lastName: string }) {
    if (creationProps) {
      const { profile } = await this.ensureLoaded({ profile: {} });

profile.name = creationProps.name;
      profile.bookmarks = ListOfBookmarks.create([], profileGroup);
    }
  }
}
```
</CodeGroup>

This was kind-of tricky to picture, and having different migration strategies for different CoValues was confusing.

We changed the logic so the default profile is created only if you didn't provide one in your migration.

This way you can use the same pattern for both `root` and `profile` migrations:
<CodeGroup>
```ts
export class MyAppAccount extends Account {
  profile = co.ref(MyAppProfile);

async migrate(this: MyAppAccount, creationProps?: { name: string }) {
    if (this.profile === undefined) {
      const profileGroup = Group.create();
      profileGroup.addMember("everyone", "reader");

this.profile = MyAppProfile.create({
        name: creationProps?.name,
        bookmarks: ListOfBookmarks.create([], profileGroup),
      }, profileGroup);
    }
  }
}
```
</CodeGroup>

<Alert variant="warning" title="Warning" className="mt-4">
If you provide a custom `Profile` in your `Account` schema and migration for a Worker account, 
make sure to also add  `everyone` as member with `reader` role to the owning group. 
Failing to do so will prevent any account from sending messages to the Worker's Inbox.
</Alert>

### Dropped support for Accounts owning Profiles
Starting from `0.11.0` `Profile`s can only be owned by `Group`s.

<Alert variant="info" title="Note" className="mt-4">
Existing profiles owned by `Account`s will still work, but you will get incorrect types when accessing a `Profile`'s `_owner`.
</Alert>

### Member Inheritance Changes

The behavior of groups' `members` getter method has been updated to return both direct members and inherited ones from ancestor groups. 
This might affect your application if you were relying on only direct members being returned.

<CodeGroup>
```ts
/**
 *  The following pseudocode only illustrates the inheritance logic, 
 *  the actual implementation is different.
*/

const parentGroup = Group.create();
parentGroup.addMember(John, "admin");

const childGroup = Group.create();
childGroup.addMember(Eve, "admin");

childGroup.extend(parentGroup);

console.log(childGroup.members);
// Before 0.11.0
// [Eve]

// After 0.11.0
// [Eve, John]
```
</CodeGroup>

Additionally:
- now `Group.members` doesn't include the `everyone` member anymore
- the account type in `Group.members` is now the globally registered Account schema and we have removed the `co.members` way to define an AccountSchema for members

If you need to explicitly check if "everyone" is a member of a group, you can use the `getRoleOf` method instead:
<CodeGroup>
```ts
if (group.getRoleOf("everyone")) {
  console.log("Everyone has access to the group");
}
```
</CodeGroup>

#### Migration Steps

1. Review your member querying logic to account for inherited members.
2. Update your permission checking code to utilize the new [`hasPermissions` and `getRoleOf`](#enhanced-permission-management) methods.
3. Consider implementing `"everyone"` role checks where appropriate.

### Removed auto-update of `profile.name` in `usePasskeyAuth`

The `usePasskeyAuth` hook now doesn't update the `profile.name` if the provided username is empty.

## Troubleshooting

> I'm getting the following error: `Error: Profile must be owned by a Group`

If you previously forced a migration of your `Account` schema to include a custom `Profile`, 
and assigned its ownership to an `Account`, you need to recreate your profile code and assign it to a `Group` instead.

<CodeGroup>
```ts
export class MyAppAccount extends Account {
  profile = co.ref(MyAppProfile);

override async migrate() {
    // ...

const me = await this.ensureLoaded({
      profile: {},
    });

if ((me.profile._owner as Group | Account)._type === "Account") {
      const profileGroup = Group.create();
      profileGroup.addMember("everyone", "reader");

// recreate your profile here...
      me.profile = Profile.create(
        {
          name: me.profile.name,
        },
        profileGroup,
      );
    }
  }
}
```
</CodeGroup>

#### 0.9.2 - Local persistence on React Native Expo

# Enable local persistence

Version 0.9.2 introduces local persistence for React Native apps using SQLite. In version 0.12, we've separated the implementations for Expo and framework-less React Native.

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

Local persistence is enabled by default in version 0.12 and higher.

## Choose your implementation

Depending on whether you're using Expo or framework-less React Native, you'll need to follow different steps:

- For Expo applications, refer to the [React Native - Expo](/docs/react-native-expo/project-setup) guide
- For framework-less React Native applications, refer to the [React Native](/docs/react-native/project-setup) guide

## Add the required dependencies

### For Expo

As SQLite package, Expo uses `expo-sqlite`. Install it with:

```bash
npx expo install expo-sqlite
npx expo install expo-secure-store
```

### For framework-less React Native

As SQLite package, we use `@op-engineering/op-sqlite` and `react-native-mmkv` for key-value storage:

```bash
npm install @op-engineering/op-sqlite react-native-mmkv
npx pod-install
```

## Update your JazzProvider

In version 0.12 and higher, you need to use either the `jazz-expo` package (for Expo) or the `jazz-react-native` package (for framework-less React Native). Local persistence is enabled by default in both packages.

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

### 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);
}

// Register the Account schema so `useAccount` returns our custom `MyAppAccount`
declare module "jazz-react" {
    interface Register {
        Account: MyAppAccount;
    }
}
```
</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); // [!code ++]
  root = co.ref(MyAppRoot);
}

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

export class MyAppProfile extends Profile { // [!code ++:4]
  name = co.string; // compatible with default Profile schema
  avatar = co.optional.ref(ImageDefinition);
}

// Register the Account schema so `useAccount` returns our custom `MyAppAccount` 
declare module "jazz-react" {
    interface Register {
        Account: MyAppAccount;
    }
}
```
</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 resolve query (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);
  profile = co.ref(MyAppProfile);

async migrate(this: MyAppAccount, creationProps?: { name: string }) {
    // 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())
      });
    }

if (this.profile === undefined) {
      const profileGroup = Group.create();
      // Unlike the root, we want the profile to be publicly readable.
      profileGroup.addMember("everyone", "reader");

this.profile = MyAppProfile.create({
        name: creationProps?.name,
        bookmarks: ListOfBookmarks.create([], profileGroup),
      }, profileGroup);
    }
  }
}
```
</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);

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

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

// we specifically need to check for undefined,
      // because myBookmarks might simply be not loaded (`null`) yet
      if (root.myBookmarks === undefined) { // [!code ++:3]
        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
*/}

### Using CoValues

#### CoMaps

# CoMaps

CoMaps are key-value objects that work like JavaScript objects. You can access properties with dot notation and define typed fields that provide TypeScript safety. They're ideal for structured data that needs type validation.

## Creating CoMaps

CoMaps are typically defined by extending the `CoMap` class and specifying primitive fields using the `co` declarer (see [Defining schemas: CoValues](/docs/schemas/covalues) for more details on primitive fields):

<CodeGroup>
```ts
class Project extends CoMap {
  name = co.string;
  startDate = co.Date;
  status = co.literal("planning", "active", "completed");
  coordinator = co.optional.ref(Member);
}
```
</CodeGroup>

You can create either struct-like CoMaps with fixed fields (as above) or record-like CoMaps for key-value pairs:

<CodeGroup>
```ts
class Inventory extends CoMap.Record(co.number) {}
```
</CodeGroup>

To instantiate a CoMap:

<CodeGroup>
```ts
const project = Project.create({
  name: "Spring Planting",
  startDate: new Date("2025-03-15"),
  status: "planning",
});

const inventory = Inventory.create({
  tomatoes: 48,
  basil: 12,
});

```
</CodeGroup>

### Ownership

When creating CoMaps, you can specify ownership to control access:

<CodeGroup>
```ts
// Create with default owner (current user)
const privateProject = Project.create({
  name: "My Herb Garden",
  startDate: new Date("2025-04-01"),
  status: "planning",
});

// Create with shared ownership
const gardenGroup = Group.create();
gardenGroup.addMember(memberAccount, "writer");

const communityProject = Project.create(
  {
    name: "Community Vegetable Plot",
    startDate: new Date("2025-03-20"),
    status: "planning",
  },
  { owner: gardenGroup },
);
```
</CodeGroup>

## Reading from CoMaps

CoMaps can be accessed using familiar JavaScript object notation:

<CodeGroup>
```ts
console.log(project.name);      // "Spring Planting"
console.log(project.status);    // "planning"
```
</CodeGroup>

### Handling Optional Fields

Optional fields require checks before access:

<CodeGroup>
```ts
if (project.coordinator) {
  console.log(project.coordinator.name);  // Safe access
}
```
</CodeGroup>

### Working with Record CoMaps

For record-type CoMaps, you can access values using bracket notation:

<CodeGroup>
```ts
const inventory = Inventory.create({
  tomatoes: 48,
  peppers: 24,
  basil: 12
});

console.log(inventory["tomatoes"]);  // 48
```
</CodeGroup>

## Updating CoMaps

Updating CoMap properties uses standard JavaScript assignment:

<CodeGroup>
```ts
project.name = "Spring Vegetable Garden";    // Update name
project.startDate = new Date("2025-03-20");  // Update date
```
</CodeGroup>

### Type Safety

CoMaps are fully typed in TypeScript, giving you autocomplete and error checking:

<CodeGroup>
```ts
project.name = "Spring Vegetable Planting";  // ✓ Valid string
project.startDate = "2025-03-15";  // ✗ Type error: expected Date
```
</CodeGroup>

### Deleting Properties

You can delete properties from CoMaps:

<CodeGroup>
```ts
delete inventory["basil"];  // Remove a key-value pair

// For optional fields in struct-like CoMaps
project.coordinator = null;  // Remove the reference
```
</CodeGroup>

## Best Practices

### Structuring Data

- Use struct-like CoMaps for entities with fixed, known properties
- Use record-like CoMaps for dynamic key-value collections
- Group related properties into nested CoMaps for better organization

### Common Patterns

#### Using Computed Properties

CoMaps support computed properties and methods:

<CodeGroup>
```ts
class ComputedProject extends CoMap {
  name = co.string;
  startDate = co.Date;
  endDate = co.optional.Date;

get isActive() {
    const now = new Date();
    return now >= this.startDate && (!this.endDate || now <= this.endDate);
  }

formatDuration(format: "short" | "full") {
    const start = this.startDate.toLocaleDateString();
    if (!this.endDate) {
      return format === "full"
        ? `Started on ${start}, ongoing`
        : `From ${start}`;
    }

const end = this.endDate.toLocaleDateString();
    return format === "full"
      ? `From ${start} to ${end}`
      : `${(this.endDate.getTime() - this.startDate.getTime()) / 86400000} days`;
  }
}

// ...

console.log(computedProject.isActive); // false
console.log(computedProject.formatDuration("short")); // "3 days"
```
</CodeGroup>

#### CoLists

# CoLists

CoLists are ordered collections that work like JavaScript arrays. They provide indexed access, iteration methods, and length properties, making them perfect for managing sequences of items.

## Creating CoLists

CoLists are defined by specifying the type of items they contain:

<CodeGroup>
```ts
class ListOfResources extends CoList.Of(co.string) {}

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

To create a `CoList`:

<CodeGroup>
```ts
// Create an empty list
const resources = ListOfResources.create([]);

// Create a list with initial items
const tasks = ListOfTasks.create([
  Task.create({ title: "Prepare soil beds", status: "in-progress" }),
  Task.create({ title: "Order compost", status: "todo" })
]);
```
</CodeGroup>

Like other CoValues, you can specify [ownership](/docs/using-covalues/ownership) when creating CoLists.

## Reading from CoLists

CoLists support standard array access patterns:

<CodeGroup>
```ts
// Access by index
const firstTask = tasks[0];
console.log(firstTask.title);  // "Prepare soil beds"

// Get list length
console.log(tasks.length);     // 2

// Iteration
tasks.forEach(task => {
  console.log(task.title);
  // "Prepare soil beds"
  // "Order compost"
});

// Array methods
const todoTasks = tasks.filter(task => task.status === "todo");
console.log(todoTasks.length); // 1
```
</CodeGroup>

## Updating CoLists

Update `CoList`s just like you would JavaScript arrays:

<CodeGroup>
```ts
// Add items
resources.push("Tomatoes");       // Add to end
resources.unshift("Lettuce");     // Add to beginning
tasks.push(Task.create({          // Add complex items
  title: "Install irrigation", 
  status: "todo"
}));

// Replace items
resources[0] = "Cucumber";           // Replace by index

// Modify nested items
tasks[0].status = "complete";        // Update properties of references
```
</CodeGroup>

### Deleting Items

Remove specific items by index with `splice`, or remove the first or last item with `pop` or `shift`:

<CodeGroup>
```ts
// Remove 2 items starting at index 1
resources.splice(1, 2);              
console.log(resources);              // ["Cucumber", "Peppers"]

// Remove a single item at index 0
resources.splice(0, 1);
console.log(resources);              // ["Peppers"]

// Remove items
const lastItem = resources.pop();    // Remove and return last item
resources.shift();                   // Remove first item
```
</CodeGroup>

### Array Methods

`CoList`s support the standard JavaScript array methods you already know:

<CodeGroup>
```ts
// Add multiple items at once
resources.push("Tomatoes", "Basil", "Peppers");

// Find items
const basil = resources.find(r => r === "Basil");

// Filter (returns regular array, not a CoList)
const tItems = resources.filter(r => r.startsWith("T"));
console.log(tItems); // ["Tomatoes"]

// Sort (modifies the CoList in-place)
resources.sort();
console.log(resources); // ["Basil", "Peppers", "Tomatoes"]
```
</CodeGroup>

### Type Safety

CoLists maintain type safety for their items:

<CodeGroup>
```ts
// TypeScript catches type errors
resources.push("Carrots");        // ✓ Valid string
resources.push(42);               // ✗ Type error: expected string

// For lists of references
tasks.forEach(task => {
  console.log(task.title);        // TypeScript knows task has title
});
```
</CodeGroup>
## Best Practices

### Common Patterns

#### List Rendering

CoLists work well with UI rendering libraries:

<CodeGroup>
```tsx
// React example
function TaskList({ tasks }) {
  return (
    <ul>
      {tasks.map(task => (
        <li key={task.id}>
          {task.title} - {task.status}
        </li>
      ))}
    </ul>
  );
}
```
</CodeGroup>

#### Managing Relations

CoLists can be used to create one-to-many relationships:

<CodeGroup>
```ts
class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
}

// ...

const task = Task.create({ 
  title: "Plant seedlings",
  status: "todo",
  project: project, // Add a reference to the project
});

// Add a task to a garden project
project.tasks.push(task);

// Access the project from the task
console.log(task.project); // { name: "Garden Project", tasks: [task] }
```
</CodeGroup>

#### CoFeeds

# CoFeeds

CoFeeds are append-only data structures that track entries from different user sessions and accounts. Unlike other CoValues where everyone edits the same data, CoFeeds maintain separate streams for each session.

Each account can have multiple sessions (different browser tabs, devices, or app instances), making CoFeeds ideal for building features like activity logs, presence indicators, and notification systems.

The following examples demonstrate a practical use of CoFeeds:
- [Multi-cursors](https://github.com/garden-co/jazz/tree/main/examples/multi-cursors) - track user presence on a canvas with multiple cursors and out of bounds indicators
- [Reactions](https://github.com/garden-co/jazz/tree/main/examples/reactions) - store per-user emoji reaction using a CoFeed

## Creating CoFeeds

CoFeeds are defined by specifying the type of items they'll contain, similar to how you define CoLists:

<CodeGroup>
```ts
// Define a schema for feed items
class Activity extends CoMap {
  timestamp = co.Date;
  action = co.literal("watering", "planting", "harvesting", "maintenance");
  notes = co.optional.string;
}

// Define a feed of garden activities
class ActivityFeed extends CoFeed.Of(co.ref(Activity)) {}

// Create a feed instance
const activityFeed = ActivityFeed.create([]);
```
</CodeGroup>

Like other CoValues, you can specify [ownership](/docs/using-covalues/ownership) when creating CoFeeds.

## Reading from CoFeeds

Since CoFeeds are made of entries from users over multiple sessions, you can access entries in different ways - from a specific user's session or from their account as a whole.

### Per-Session Access

To retrieve entries from a session:

<CodeGroup>
```ts
// Get the feed for a specific session
const sessionFeed = activityFeed.perSession[sessionId];

// Latest entry from a session
console.log(sessionFeed.value.action); // "watering"
```
</CodeGroup>

For convenience, you can also access the latest entry from the current session with `inCurrentSession`:

<CodeGroup>
```ts
// Get the feed for the current session
const currentSessionFeed = activityFeed.inCurrentSession;

// Latest entry from the current session
console.log(currentSessionFeed.value.action); // "harvesting"
```
</CodeGroup>

### Per-Account Access

To retrieve entries from a specific account you can use bracket notation with the account ID:

<CodeGroup>
```ts
// Get the feed for a specific account
const accountFeed = activityFeed[accountId];

// Latest entry from the account
console.log(accountFeed.value.action); // "watering"
```
</CodeGroup>

For convenience, you can also access the latest entry from the current account with `byMe`:

<CodeGroup>
```ts
// Get the feed for the current account
const myLatestEntry = activityFeed.byMe;

// Latest entry from the current account
console.log(myLatestEntry.value.action); // "harvesting"
```
</CodeGroup>

### Feed Entries

#### All Entries

To retrieve all entries from a CoFeed:

<CodeGroup>
```ts
// Get the feeds for a specific account and session
const accountFeed = activityFeed[accountId];
const sessionFeed = activityFeed.perSession[sessionId];

// Iterate over all entries from the account
for (const entry of accountFeed.all) {
  console.log(entry.value);
}

// Iterate over all entries from the session
for (const entry of sessionFeed.all) {
  console.log(entry.value);
}
```
</CodeGroup>

#### Latest Entry

To retrieve the latest entry from a CoFeed, ie. the last update:

<CodeGroup>
```ts
// Get the latest entry from the current account
const latestEntry = activityFeed.byMe;

console.log(`My last action was ${latestEntry.value.action}`); 
  // "My last action was harvesting"

// Get the latest entry from each account
const latestEntriesByAccount = Object.values(activityFeed).map(entry => ({
  accountName: entry.by?.profile?.name,
  value: entry.value,
}));
```
</CodeGroup>

## Writing to CoFeeds

CoFeeds are append-only; you can add new items, but not modify existing ones. This creates a chronological record of events or activities.

### Adding Items

<CodeGroup>
```ts
// Log a new activity
activityFeed.push(Activity.create({
  timestamp: new Date(),
  action: "watering",
  notes: "Extra water for new seedlings"
}));
```
</CodeGroup>

Each item is automatically associated with the current user's session. You don't need to specify which session the item belongs to - Jazz handles this automatically.

### Understanding Session Context

Each entry is automatically added to the current session's feed. When a user has multiple open sessions (like both a mobile app and web browser), each session creates its own separate entries:

<CodeGroup>
```ts
// On mobile device:
fromMobileFeed.push(Activity.create({
  timestamp: new Date(),
  action: "harvesting",
  location: "Vegetable patch"
}));

// On web browser (same user):
fromBrowserFeed.push(Activity.create({
  timestamp: new Date(),
  action: "planting",
  location: "Flower bed"
}));

// These are separate entries in the same feed, from the same account

```
</CodeGroup>

## Metadata

CoFeeds support metadata, which is useful for tracking information about the feed itself.

### By

The `by` property is the account that made the entry.

<CodeGroup>
```ts
const accountFeed = activityFeed[accountId];

// Get the account that made the last entry
console.log(accountFeed?.by);
```
</CodeGroup>

### MadeAt

The `madeAt` property is a timestamp of when the entry was added to the feed.

<CodeGroup>
```ts
const accountFeed = activityFeed[accountId];

// Get the timestamp of the last update
console.log(accountFeed?.madeAt);

// Get the timestamp of each entry
for (const entry of accountFeed.all) {
  console.log(entry.madeAt);
}
```
</CodeGroup>

## Best Practices

### When to Use CoFeeds

- **Use CoFeeds when**:
  - You need to track per-user/per-session data
  - Time-based information matters (activity logs, presence)

- **Consider alternatives when**:
  - Data needs to be collaboratively edited (use CoMaps or CoLists)
  - You need structured relationships (use CoMaps/CoLists with references)

#### FileStreams

# FileStreams

FileStreams handle binary data in Jazz applications - think documents, audio files, and other non-text content. They're essentially collaborative versions of `Blob`s that sync automatically across devices.

Use FileStreams when you need to:
- Distribute documents across devices
- Store audio or video files
- Sync any binary data between users

**Note:** For images specifically, Jazz provides the higher-level `ImageDefinition` abstraction which manages multiple image resolutions - see the [ImageDefinition documentation](/docs/using-covalues/imagedef) for details.

FileStreams provide automatic chunking when using the `createFromBlob` method, track upload progress, and handle MIME types and metadata.

In your schema, reference FileStreams like any other CoValue:

<CodeGroup>
```ts

class Document extends CoMap {
  title = co.string;
  file = co.ref(FileStream);  // Store a document file
}
```
</CodeGroup>

## Creating FileStreams

There are two main ways to create FileStreams: creating empty ones for manual data population or creating directly from existing files or blobs.

### Creating from Blobs and Files

For files from input elements or drag-and-drop interfaces, use `createFromBlob`:

<CodeGroup>
```ts
// From a file input
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async () => {
  const file = fileInput.files[0];
  if (file) {
    // Create FileStream from user-selected file
    const fileStream = await FileStream.createFromBlob(file);
    
    // Or with progress tracking for better UX
    const fileWithProgress = await FileStream.createFromBlob(file, {
      onProgress: (progress) => {
        // progress is a value between 0 and 1
        const percent = Math.round(progress * 100);
        console.log(`Upload progress: ${percent}%`);
        progressBar.style.width = `${percent}%`;
      }
    });
  }
});
```
</CodeGroup>

### Creating Empty FileStreams

Create an empty FileStream when you want to manually [add binary data in chunks](/docs/using-covalues/filestreams#writing-to-filestreams):

<CodeGroup>
```ts

// Create a new empty FileStream
const fileStream = FileStream.create();
```
</CodeGroup>

## Reading from FileStreams

`FileStream`s provide several ways to access their binary content, from raw chunks to convenient Blob objects.

### Getting Raw Data Chunks

To access the raw binary data and metadata:

<CodeGroup>
```ts
// Get all chunks and metadata
const fileData = fileStream.getChunks();

if (fileData) {
  console.log(`MIME type: ${fileData.mimeType}`);
  console.log(`Total size: ${fileData.totalSizeBytes} bytes`);
  console.log(`File name: ${fileData.fileName}`);
  console.log(`Is complete: ${fileData.finished}`);
  
  // Access raw binary chunks
  for (const chunk of fileData.chunks) {
    // Each chunk is a Uint8Array
    console.log(`Chunk size: ${chunk.length} bytes`);
  }
}
```
</CodeGroup>

By default, `getChunks()` only returns data for completely synced `FileStream`s. To start using chunks from a `FileStream` that's currently still being synced use the `allowUnfinished` option:

<CodeGroup>
```ts
// Get data even if the stream isn't complete
const partialData = fileStream.getChunks({ allowUnfinished: true });
```
</CodeGroup>

### Converting to Blobs

For easier integration with web APIs, convert to a `Blob`:

<CodeGroup>
```ts
// Convert to a Blob
const blob = fileStream.toBlob();

if (blob) {
  // Use with URL.createObjectURL
  const url = URL.createObjectURL(blob);
  
  // Create a download link
  const link = document.createElement('a');
  link.href = url;
  link.download = fileData?.fileName || 'document.pdf';
  link.click();
  
  // Clean up when done
  URL.revokeObjectURL(url);
}
```
</CodeGroup>

### Loading FileStreams as Blobs

You can directly load a `FileStream` as a `Blob` when you only have its ID:

<CodeGroup>
```ts
// Load directly as a Blob when you have an ID
const blob = await FileStream.loadAsBlob(fileStreamId);

// By default, waits for complete uploads
// For in-progress uploads:
const partialBlob = await FileStream.loadAsBlob(fileStreamId, {
  allowUnfinished: true 
});
```
</CodeGroup>

### Checking Completion Status

Check if a `FileStream` is fully synced:

<CodeGroup>
```ts
if (fileStream.isBinaryStreamEnded()) {
  console.log('File is completely synced');
} else {
  console.log('File upload is still in progress');
}
```
</CodeGroup>

## Writing to FileStreams

When creating a `FileStream` manually (not using `createFromBlob`), you need to manage the upload process yourself. This gives you more control over chunking and progress tracking.

### The Upload Lifecycle

`FileStream` uploads follow a three-stage process:

1. **Start** - Initialize with metadata
2. **Push** - Send one or more chunks of data
3. **End** - Mark the stream as complete

### Starting a `FileStream`

Begin by providing metadata about the file:

<CodeGroup>
```ts
// Create an empty FileStream
const fileStream = FileStream.create();

// Initialize with metadata
fileStream.start({
  mimeType: 'application/pdf',      // MIME type (required)
  totalSizeBytes: 1024 * 1024 * 2,  // Size in bytes (if known)
  fileName: 'document.pdf'          // Original filename (optional)
});
```
</CodeGroup>

### Pushing Data

Add binary data in chunks - this helps with large files and progress tracking:

<CodeGroup>
```ts
// Create a sample Uint8Array (in real apps, this would be file data)
const data = new Uint8Array([...]);

// For large files, break into chunks (e.g., 100KB each)
const chunkSize = 1024 * 100;
for (let i = 0; i < data.length; i += chunkSize) {
  // Create a slice of the data
  const chunk = data.slice(i, i + chunkSize);
  
  // Push chunk to the FileStream
  fileStream.push(chunk);
  
  // Track progress
  const progress = Math.min(100, Math.round((i + chunk.length) * 100 / data.length));
  console.log(`Upload progress: ${progress}%`);
}
```
</CodeGroup>

### Completing the Upload

Once all chunks are pushed, mark the `FileStream` as complete:

<CodeGroup>
```ts
// Finalize the upload
fileStream.end();

console.log('Upload complete!');
```
</CodeGroup>

## Subscribing to `FileStream`s

Like other CoValues, you can subscribe to `FileStream`s to get notified of changes as they happen. This is especially useful for tracking upload progress when someone else is uploading a file.

### Loading by ID

Load a `FileStream` when you have its ID:

<CodeGroup>
```ts
// Load a FileStream by ID
const fileStream = await FileStream.load(fileStreamId, []);

if (fileStream) {
  console.log('FileStream loaded successfully');
  
  // Check if it's complete
  if (fileStream.isBinaryStreamEnded()) {
    // Process the completed file
    const blob = fileStream.toBlob();
  }
}
```
</CodeGroup>

### Subscribing to Changes

Subscribe to a `FileStream` to be notified when chunks are added or when the upload is complete:

<CodeGroup>
```ts
// Subscribe to a FileStream by ID
const unsubscribe = FileStream.subscribe(fileStreamId, [], (fileStream) => {
  // Called whenever the FileStream changes
  console.log('FileStream updated');
  
  // Get current status
  const chunks = fileStream.getChunks({ allowUnfinished: true });
  if (chunks) {
    const uploadedBytes = chunks.chunks.reduce((sum, chunk) => sum + chunk.length, 0);
    const totalBytes = chunks.totalSizeBytes || 1;
    const progress = Math.min(100, Math.round(uploadedBytes * 100 / totalBytes));
    
    console.log(`Upload progress: ${progress}%`);
    
    if (fileStream.isBinaryStreamEnded()) {
      console.log('Upload complete!');
      // Now safe to use the file
      const blob = fileStream.toBlob();
      
      // Clean up the subscription if we're done
      unsubscribe();
    }
  }
});
```
</CodeGroup>

### Waiting for Upload Completion

If you need to wait for a `FileStream` to be fully synchronized across devices:

<CodeGroup>
```ts
// Wait for the FileStream to be fully synced
await fileStream.waitForSync({
  timeout: 5000  // Optional timeout in ms
});

console.log('FileStream is now synced to all connected devices');
```
</CodeGroup>

This is useful when you need to ensure that a file is available to other users before proceeding with an operation.

#### ImageDefinition

### react-native-expo Implementation

# ImageDefinition

`ImageDefinition` is a specialized CoValue designed specifically for managing images in Jazz. It extends beyond basic file storage by supporting multiple resolutions of the same image, optimized for mobile devices.

**Note**: This guide applies to both Expo and framework-less React Native implementations. The functionality described here is identical regardless of which implementation you're using, though you'll need to import from the appropriate package (`jazz-expo` or `jazz-react-native`).

Jazz offers several tools to work with images in React Native:
- [`createImage()`](#creating-images) - function to create an `ImageDefinition` from a base64 image data URI
- [`ProgressiveImg`](#displaying-images-with-progressiveimg) - React component to display an image with progressive loading
- [`useProgressiveImg`](#using-useprogressiveimg-hook) - React hook to load an image in your own component

For examples of use, see our example apps:
- [React Native Chat](https://github.com/gardencmp/jazz/tree/main/examples/chat-rn) (Framework-less implementation)
- [React Native Expo Chat](https://github.com/gardencmp/jazz/tree/main/examples/chat-rn-expo) (Expo implementation)
- [React Native Expo Clerk Chat](https://github.com/gardencmp/jazz/tree/main/examples/chat-rn-expo-clerk) (Expo implementation with Clerk)

## Creating Images

The easiest way to create and use images in your Jazz application is with the `createImage()` function:

<CodeGroup>
```tsx

async function handleImagePicker() {
  try {
    // Launch the image picker
    const result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ImagePicker.MediaTypeOptions.Images,
      base64: true,
      quality: 1,
    });

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

// Creates ImageDefinition with multiple resolutions automatically
      const image = await createImage(base64Uri, {
        owner: me.profile._owner,
        maxSize: 2048, // Optional: limit maximum resolution
      });

// Store the image
      me.profile.image = image;
    }
  } catch (error) {
    console.error("Error creating image:", error);
  }
}
```
</CodeGroup>

The `createImage()` function:
- Creates an `ImageDefinition` with the right properties
- Generates a small placeholder for immediate display
- Creates multiple resolution variants of your image
- Returns the created `ImageDefinition`

### Configuration Options

You can configure `createImage()` with additional options:

<CodeGroup>
```tsx
// Configuration options
const options = {
  owner: me,                // Owner for access control
  maxSize: 1024             // Maximum resolution to generate
};

// Setting maxSize controls which resolutions are generated:
// 256: Only creates the smallest resolution (256px on longest side)
// 1024: Creates 256px and 1024px resolutions
// 2048: Creates 256px, 1024px, and 2048px resolutions
// undefined: Creates all resolutions including the original size

const image = await createImage(base64Uri, options);
```
</CodeGroup>

## Displaying Images with `ProgressiveImg`

For a complete progressive loading experience, use the `ProgressiveImg` component:

<CodeGroup>
```tsx

function GalleryView({ image }) {
  return (
    <ProgressiveImg
      image={image}  // The image definition to load
      targetWidth={800} //  Looks for the best available resolution for a 800px image
    >
      {({ src }) => (
        <Image
          source={{ uri: src }}
          style={styles.galleryImage}
          resizeMode="cover"
        />
      )}
    </ProgressiveImg>
  );
}

const styles = StyleSheet.create({
  galleryImage: {
    width: '100%',
    height: 200,
    borderRadius: 8,
  }
});
```
</CodeGroup>

The `ProgressiveImg` component handles:
- Showing a placeholder while loading
- Automatically selecting the appropriate resolution
- Progressive enhancement as higher resolutions become available
- Cleaning up resources when unmounted

## Using `useProgressiveImg` Hook

For more control over image loading, you can implement your own progressive image component:

<CodeGroup>
```tsx

function CustomImageComponent({ image }) {
  const {
    src,         // Data URI containing the image data as a base64 string,
                 // or a placeholder image URI
    res,         // The current resolution
    originalSize // The original size of the image
  } = useProgressiveImg({
    image: image,  // The image definition to load
    targetWidth: 800  // Limit to resolutions up to 800px wide
  });

// When image is not available yet
  if (!src) {
    return (
      <View style={{ height: 200, justifyContent: 'center', alignItems: 'center', backgroundColor: '#f0f0f0' }}>
        <ActivityIndicator size="small" color="#0000ff" />
        <Text style={{ marginTop: 10 }}>Loading image...</Text>
      </View>
    );
  }

// When using placeholder
  if (res === "placeholder") {
    return (
      <View style={{ position: 'relative' }}>
        <Image
          source={{ uri: src }}
          style={{ width: '100%', height: 200, opacity: 0.7 }}
          resizeMode="cover"
        />
        <ActivityIndicator
          size="large"
          color="#ffffff"
          style={{ position: 'absolute', top: '50%', left: '50%', marginLeft: -20, marginTop: -20 }}
        />
      </View>
    );
  }

// Full image display with custom overlay
  return (
    <View style={{ position: 'relative', width: '100%', height: 200 }}>
      <Image
        source={{ uri: src }}
        style={{ width: '100%', height: '100%' }}
        resizeMode="cover"
      />
      <View style={{ position: 'absolute', bottom: 0, left: 0, right: 0, backgroundColor: 'rgba(0,0,0,0.5)', padding: 8 }}>
        <Text style={{ color: 'white' }}>Resolution: {res}</Text>
      </View>
    </View>
  );
}
```
</CodeGroup>

## Understanding ImageDefinition

Behind the scenes, `ImageDefinition` is a specialized CoValue that stores:

- The original image dimensions (`originalSize`)
- An optional placeholder (`placeholderDataURL`) for immediate display
- Multiple resolution variants of the same image as [`FileStream`s](../using-covalues/filestreams)

Each resolution is stored with a key in the format `"widthxheight"` (e.g., `"1920x1080"`, `"800x450"`).

<CodeGroup>
```tsx
// Structure of an ImageDefinition
const image = ImageDefinition.create({
  originalSize: [1920, 1080],
  placeholderDataURL: "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
});

// Accessing the highest available resolution
const highestRes = image.highestResAvailable();
if (highestRes) {
  console.log(`Found resolution: ${highestRes.res}`);
  console.log(`Stream: ${highestRes.stream}`);
}
```
</CodeGroup>

For more details on using `ImageDefinition` directly, see the [VanillaJS docs](/docs/vanilla/using-covalues/imagedef).

### Fallback Behavior

`highestResAvailable` returns the largest resolution that fits your constraints. If a resolution has incomplete data, it falls back to the next available lower resolution.

<CodeGroup>
```tsx
const image = ImageDefinition.create({
  originalSize: [1920, 1080],
});

image["1920x1080"] = FileStream.create(); // Empty image upload
image["800x450"] = await FileStream.createFromBlob(mediumSizeBlob);

const highestRes = image.highestResAvailable();
console.log(highestRes.res); // 800x450
```
</CodeGroup>

---

### react-native Implementation

# ImageDefinition

## Creating Images

The easiest way to create and use images in your Jazz application is with the `createImage()` function:

<CodeGroup>
```tsx

async function handleImagePicker() {
  try {
    // Launch the image picker
    const result = await launchImageLibrary({
      mediaType: 'photo',
      includeBase64: true,
      quality: 1,
    });

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

// Store the image
      me.profile.image = image;
    }
  } catch (error) {
    console.error("Error creating image:", error);
  }
}
```
</CodeGroup>

### Configuration Options

You can configure `createImage()` with additional options:

<CodeGroup>
```tsx
// Configuration options
const options = {
  owner: me,                // Owner for access control
  maxSize: 1024             // Maximum resolution to generate
};

const image = await createImage(base64Uri, options);
```
</CodeGroup>

## Displaying Images with `ProgressiveImg`

For a complete progressive loading experience, use the `ProgressiveImg` component:

<CodeGroup>
```tsx

const styles = StyleSheet.create({
  galleryImage: {
    width: '100%',
    height: 200,
    borderRadius: 8,
  }
});
```
</CodeGroup>

## Using `useProgressiveImg` Hook

For more control over image loading, you can implement your own progressive image component:

<CodeGroup>
```tsx

## Understanding ImageDefinition

Behind the scenes, `ImageDefinition` is a specialized CoValue that stores:

Each resolution is stored with a key in the format `"widthxheight"` (e.g., `"1920x1080"`, `"800x450"`).

<CodeGroup>
```tsx
// Structure of an ImageDefinition
const image = ImageDefinition.create({
  originalSize: [1920, 1080],
  placeholderDataURL: "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
});

For more details on using `ImageDefinition` directly, see the [VanillaJS docs](/docs/vanilla/using-covalues/imagedef).

### Fallback Behavior

`highestResAvailable` returns the largest resolution that fits your constraints. If a resolution has incomplete data, it falls back to the next available lower resolution.

<CodeGroup>
```tsx
const image = ImageDefinition.create({
  originalSize: [1920, 1080],
});

image["1920x1080"] = FileStream.create(); // Empty image upload
image["800x450"] = await FileStream.createFromBlob(mediumSizeBlob);

const highestRes = image.highestResAvailable();
console.log(highestRes.res); // 800x450
```
</CodeGroup>

---

### react Implementation

# ImageDefinition

`ImageDefinition` is a specialized CoValue designed specifically for managing images in Jazz applications. It extends beyond basic file storage by supporting multiple resolutions of the same image and progressive loading patterns.

Beyond [`ImageDefinition`](#understanding-imagedefinition), Jazz offers higher-level functions and components that make it easier to use images:
- [`createImage()`](#creating-images) - function to create an `ImageDefinition` from a file
- [`ProgressiveImg`](#displaying-images-with-progressiveimg) - React component to display an image with progressive loading
- [`useProgressiveImg`](#using-useprogressiveimg-hook) - React hook to load an image in your own component

The [Image Upload example](https://github.com/gardencmp/jazz/tree/main/examples/image-upload) demonstrates use of `ProgressiveImg` and `ImageDefinition`.

## Creating Images

The easiest way to create and use images in your Jazz application is with the `createImage()` function:

<CodeGroup>
```ts

// Create an image from a file input
async function handleFileUpload(event) {
  const file = event.target.files[0];
  if (file) {
    // Creates ImageDefinition with multiple resolutions automatically
    const image = await createImage(file, {
      owner: me.profile._owner,
    });
    
    // Store the image in your application data
    me.profile.image = image;
  }
}
```
</CodeGroup>

> Note: `createImage()` requires a browser environment as it uses browser APIs to process images.

### Configuration Options

You can configure `createImage()` with additional options:

<CodeGroup>
```tsx
// Configuration options
const options = {
  owner: me,                // Owner for access control
  maxSize: 1024             // Maximum resolution to generate
};

const image = await createImage(file, options);
```
</CodeGroup>

## Displaying Images with `ProgressiveImg`

For a complete progressive loading experience, use the `ProgressiveImg` component:

<CodeGroup>
```tsx

function GalleryView({ image }) {
  return (
    <div className="image-container">
      <ProgressiveImg
        image={image}  // The image definition to load
        targetWidth={800} // Looks for the best available resolution for a 800px image
      >
        {({ src }) => (
          <img 
            src={src} 
            alt="Gallery image" 
            className="gallery-image"
          />
        )}
      </ProgressiveImg>
    </div>
  );
}
```
</CodeGroup>

## Using `useProgressiveImg` Hook

For more control over image loading, you can implement your own progressive image component:

<CodeGroup>
```tsx

// When image is not available yet
  if (!src) {
    return <div className="image-loading-fallback">Loading image...</div>;
  }
  
  // When image is loading, show a placeholder
  if (res === "placeholder") {
    return <img src={src} alt="Loading..." className="blur-effect" />;
  }

// Full image display with custom overlay
  return (
    <div className="custom-image-wrapper">
      <img 
        src={src} 
        alt="Custom image" 
        className="custom-image"
      />
      <div className="image-overlay">
        <span className="image-caption">Resolution: {res}</span>
      </div>
    </div>
  );
}
```
</CodeGroup>

## Understanding ImageDefinition

Behind the scenes, `ImageDefinition` is a specialized CoValue that stores:

Each resolution is stored with a key in the format `"widthxheight"` (e.g., `"1920x1080"`, `"800x450"`).

<CodeGroup>
```ts
// Structure of an ImageDefinition
const image = ImageDefinition.create({
  originalSize: [1920, 1080],
  placeholderDataURL: "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
});

For more details on using `ImageDefinition` directly, see the [VanillaJS docs](/docs/vanilla/using-covalues/imagedef).

### Fallback Behavior

`highestResAvailable` returns the largest resolution that fits your constraints. If a resolution has incomplete data, it falls back to the next available lower resolution.

<CodeGroup>
```ts
const image = ImageDefinition.create({
  originalSize: [1920, 1080],
});

image["1920x1080"] = FileStream.create(); // Empty image upload
image["800x450"] = await FileStream.createFromBlob(mediumSizeBlob);

const highestRes = image.highestResAvailable();
console.log(highestRes.res); // 800x450
```
</CodeGroup>

#### Subscriptions & Deep Loading

# Subscriptions & Deep Loading

Jazz's Collaborative Values (such as [CoMaps](/docs/using-covalues/comaps) or [CoLists](/docs/using-covalues/colists)) work like reactive state. By subscribing to them, you can react to both local and remote updates. This is the main way to consume data in your application.

Subscriptions also take care of loading CoValues that are not yet loaded locally and can do so *deeply* — by resolving nested CoValues. To make use of this, we'll show you how to specify the depth of data you need with resolve queries.

With each update you can also handle loading states and inaccessible CoValues.

## Manual subscriptions

You can subscribe to a CoValue from anywhere in your code (if you have its ID) by using `CoValue.subscribe()`.

<ContentByFramework framework="vanilla">
If you're using React in your project, check out our [React hooks](/docs/react/using-covalues/subscription-and-loading#subscription-hooks) which provide a more streamlined experience with automatic subscription management.
</ContentByFramework>

<ContentByFramework framework={["react", "react-native"]}>
**Note:** Unless you're using vanilla JavaScript, this is only used outside of React components - for example in server-side code or in tests. See the section below for convenient subscription *hooks* that you typically use in React.
</ContentByFramework>

<CodeGroup>
```ts twoslash
const taskId = "co_123" as ID<Task>;
// ---cut-before---
class Task extends CoMap {
  title = co.string;
  description = co.string;
  status = co.literal("todo", "in-progress", "completed");
  assignedTo = co.optional.string;
}

// ...

// Subscribe to a Task by ID
const unsubscribe = Task.subscribe(taskId, (updatedTask) => {
  console.log("Task updated:", updatedTask.title);
  console.log("New status:", updatedTask.status);
});

// Clean up when you're done
unsubscribe();

```
</CodeGroup>

If you already have a CoValue instance, you can subscribe to it by calling its `subscribe` method.

<CodeGroup>
```ts twoslash

class Task extends CoMap {
  title = co.string;
  description = co.string;
  status = co.literal("todo", "in-progress", "completed");
  assignedTo = co.optional.string;
}
const otherProps = {} as any;
// ---cut-before---
const task = Task.create({
  title: "Cut the grass",
  ...otherProps
});

const unsubscribe = task.subscribe((updatedTask) => {
  console.log("Task updated:", updatedTask.title);
});

// Clean up when you're done
unsubscribe();
```
</CodeGroup>

<ContentByFramework framework={["react", "react-native"]}>
## Subscription hooks

### `useCoState`

Jazz provides a `useCoState` hook that provides a convenient way to subscribe to CoValues and handle loading states:

<CodeGroup>
```tsx twoslash

class Task extends CoMap {
  title = co.string;
  status = co.literal("todo", "in-progress", "completed");
}
class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
}
class ListOfTasks extends CoList.Of(co.ref(Task)) {}

// ---cut-before---

function GardenPlanner({ projectId }: { projectId: ID<Project> }) {
  // Subscribe to a project and its tasks
  const project = useCoState(Project, projectId, {
    resolve: {
      tasks: { $each: true },
    },
  });

if (!project) {
    return project === null
      ? "Project not found or not accessible"
      : "Loading project ...";
  }

return (
    <div>
      <h1>{project.name}</h1>
      <TaskList tasks={project.tasks} />
    </div>
  );
}

function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <ul>
      {tasks.map((task) => (
        <li key={task.id}>
          <span>{task.title}</span>
          <span>{task.status}</span>
        </li>
      ))}
    </ul>
  );
}
```
</CodeGroup>

The `useCoState` hook handles subscribing when the component mounts and unsubscribing when it unmounts, making it easy to keep your UI in sync with the underlying data.

### `useAccount`

`useAccount` is used to access the current user's account.
You can use this at the top-level of your app to subscribe to the current user's [account profile and root](../schemas/accounts-and-migrations#covalues-as-a-graph-of-data-rooted-in-accounts).

Like `useCoState`, you can specify a resolve query to also subscribe to CoValues referenced in the account profile or root.

<CodeGroup>
```tsx twoslash
class Task extends CoMap {
  title = co.string;
}
class ListOfTasks extends CoList.Of(co.ref(Task)) {}
class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
}
class ListOfProjects extends CoList.Of(co.ref(Project)) {}

class AccountRoot extends CoMap {
  myProjects = co.ref(ListOfProjects);
}
class MyAppAccount extends Account {
  root = co.ref(AccountRoot);
}
declare module "jazz-react" { interface Register { Account: MyAppAccount; } }
// ---cut-before---

function ProjectList() {
  const { me } = useAccount({
    resolve: {
      profile: true,
      root: {
        myProjects: {
          $each: {
            tasks: true
          }
        }
      },
    },
  });

if (!me) {
    return <div>Loading...</div>;
  }

return <div>
    <h1>{me.profile.name}'s projects</h1>
    <ul>
      {me.root.myProjects.map(project => (
        <li key={project.id}>
          {project.name} ({project.tasks.length} tasks)
        </li>
      ))}
    </ul>
  </div>
}
```
</CodeGroup>

</ContentByFramework>

## Loading States and Permission Checking

When subscribing to or loading a CoValue, you need to handle three possible states:

- `undefined`: The initial loading state, indicating the value is being fetched
- `null`: The CoValue was not found or is not accessible (e.g., due to permissions)
- `Value`: The successfully loaded CoValue instance

This allows you to handle loading, error, and success states in your application:

<CodeGroup>
```ts twoslash
class Task extends CoMap {
  title = co.string;
}

## Deep Loading

When working with related CoValues (like tasks in a project), you often need to load not just the top-level object but also its nested references. This is especially important when working with [CoMaps](/docs/using-covalues/comaps) that contain references to other CoValues or with [CoLists](/docs/using-covalues/colists) that contain multiple items. Jazz provides a flexible mechanism for specifying exactly how much of the object graph to load.

### Resolve queries

Resolve queries let you declare exactly which references to load and how deep to go using the `resolve` property:

<CodeGroup>
```ts twoslash
const projectId = "co_123" as ID<Project>;

// ---cut-before---
class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
  owner = co.ref(TeamMember);
}

class Task extends CoMap {
  title = co.string;
  subtasks = co.ref(ListOfTasks);
  assignee = co.optional.ref(TeamMember);
}

class TeamMember extends CoMap {
  name = co.string;
}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}

// Load just the project, not its references
const project = await Project.load(projectId);
if (!project) { throw new Error("Project not found or not accessible"); }

// string - primitive fields are always loaded
project.name;
// undefined | null | ListOfTasks - non-requested references might not be loaded, or inaccessible
project.tasks;

// Load the project and shallowly load its list of tasks
const projectWithTasksShallow = await Project.load(projectId, {
  resolve: {
    tasks: true
  }
});
if (!projectWithTasksShallow) { throw new Error("Project or required references not found or not accessible"); }

// ListOfTasks - shallowly loaded
projectWithTasksShallow.tasks;
// number - length of the list
projectWithTasksShallow.tasks.length;
// undefined | null | Task - items might not be loaded, or inaccessible
projectWithTasksShallow.tasks[0];

// Load the project and its tasks
const projectWithTasks = await Project.load(projectId, {
  resolve: {
    tasks: {
      $each: true
    }
  }
});
if (!projectWithTasks) { throw new Error("Project or required references not found or not accessible"); }

// ListOfTasks - fully loaded
projectWithTasks.tasks;
// Task - fully loaded
projectWithTasks.tasks[0];
// string - primitive fields are always loaded
projectWithTasks.tasks[0].title;
// undefined | null | ListOfTasks - subtasks might not be loaded, or inaccessible
projectWithTasks.tasks[0].subtasks;

// Load the project, its tasks, and their subtasks
const projectDeep = await Project.load(projectId, {
  resolve: {
    tasks: {
      $each: {
        subtasks: {
          $each: true
        },
        assignee: true
      }
    }
  }
});
if (!projectDeep) { throw new Error("Project or required references not found or not accessible"); }

// string - primitive fields are always loaded
projectDeep.tasks[0].subtasks[0].title;
// undefined | null | TeamMember - since assignee is optional:
//   TeamMember - set and definitely loaded
//   null - set but unavailable/inaccessible
//   undefined - not set, or loading (in case of subscription)
projectDeep.tasks[0].assignee;
```
</CodeGroup>

The resolve query defines which parts of the graph you want to load, making it intuitive to express complex loading patterns.

### Loading states and permissions

When loading data with references, the load operation will fail if one of the references is unavailable or if the user doesn't have read access to it. Let's explore what happens in various scenarios:

#### Resolved References

When a user tries to load a reference they don't have access to:

<CodeGroup>
```typescript twoslash

class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
  owner = co.ref(TeamMember);
}

class Task extends CoMap {
  title = co.string;
  subtasks = co.ref(ListOfTasks);
  assignee = co.optional.ref(TeamMember);
}

class TeamMember extends CoMap {
  name = co.string;
}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}

const taskId = "co_123" as ID<Task>;

// ---cut-before---
// If assignee is not accessible to the user:
const task = await Task.load(taskId, {
  resolve: { assignee: true }
});

task // => null
```
</CodeGroup>
The load operation will fail and return `null` if any requested reference is inaccessible. This maintains data consistency by ensuring all requested references are available before returning the object.

The behavior is the same for optional and required references.

#### List References

When a list contains references to items the user can't access:

<CodeGroup>
```typescript twoslash

class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
  owner = co.ref(TeamMember);
}

class Task extends CoMap {
  title = co.string;
  subtasks = co.ref(ListOfTasks);
  assignee = co.optional.ref(TeamMember);
}

class TeamMember extends CoMap {
  name = co.string;
}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}

const projectId = "co_123" as ID<Project>;
// ---cut-before---
// If any item in the list is not accessible:
const project = await Project.load(projectId, {
  resolve: { tasks: { $each: true } }
});

project // => null
```
</CodeGroup>
If any item in a list is inaccessible to the user, the entire load operation will fail and return `null`. This is because lists expect all their items to be accessible - a partially loaded list could lead to data inconsistencies.

#### Reading a non-resolved inaccessible reference

When trying to load an object with an inaccessible reference without directly resolving it:

<CodeGroup>
```typescript twoslash

class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
  owner = co.ref(TeamMember);
}

class Task extends CoMap {
  title = co.string;
  subtasks = co.ref(ListOfTasks);
  assignee = co.optional.ref(TeamMember);
}

class TeamMember extends CoMap {
  name = co.string;
}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}

const projectId = "co_123" as ID<Project>;
// ---cut-before---
const project = await Project.load(projectId, {
  resolve: true
});

project // => Project

// The user doesn't have access to the owner
project?.owner // => always null
```
</CodeGroup>

The load operation will succeed and return the object, but the inaccessible reference will always be `null`.

## Type Safety with Resolved Type

Jazz provides the `Resolved` type to help you define and enforce the structure of deeply loaded data in your application. This makes it easier to ensure that components receive the data they expect with proper TypeScript validation.

The `Resolved` type is especially useful when passing data between components, as it guarantees that all necessary nested data has been loaded:

<ContentByFramework framework="react">
<CodeGroup>
```tsx twoslash

class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
  owner = co.ref(TeamMember);
}

class Task extends CoMap {
  title = co.string;
  subtasks = co.ref(ListOfTasks);
  assignee = co.optional.ref(TeamMember);
}

class TeamMember extends CoMap {
  name = co.string;
}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}

// ---cut-before---
// Define a type that includes resolved nested data
type ProjectWithTasks = Resolved<Project, {
  tasks: { $each: true }
}>;

// Component that expects a fully resolved project
function TaskList({ project }: { project: ProjectWithTasks }) {
  // TypeScript knows tasks are loaded, so this is type-safe
  return (
    <ul>
      {project.tasks.map(task => (
        <li key={task.id}>{task.title}</li>
      ))}
    </ul>
  );
}

// For more complex resolutions
type FullyLoadedProject = Resolved<Project, {
  tasks: {
    $each: {
      subtasks: true,
      assignee: true
    }
  },
  owner: true
}>;

// Function that requires deeply resolved data
function processProject(project: FullyLoadedProject) {
  // Safe access to all resolved properties
  console.log(`Project ${project.name} owned by ${project.owner.name}`);

project.tasks.forEach(task => {
    console.log(`Task: ${task.title}, Assigned to: ${task.assignee?.name}`);
    console.log(`Subtasks: ${task.subtasks.length}`);
  });
}
```
</CodeGroup>
</ContentByFramework>

<ContentByFramework framework="vanilla">
<CodeGroup>
```ts twoslash

class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
  owner = co.ref(TeamMember);
}

class Task extends CoMap {
  title = co.string;
  subtasks = co.ref(ListOfTasks);
  assignee = co.optional.ref(TeamMember);
}

class TeamMember extends CoMap {
  name = co.string;
}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}

// ---cut-before---
// Define a type that includes resolved nested data
type ProjectWithTasks = Resolved<Project, {
  tasks: { $each: true }
}>;

// Function that expects resolved data
async function taskList({project}: {project: ProjectWithTasks}) {
  // TypeScript knows tasks are loaded, so this is type-safe
  return project.tasks
    .map(task => task.title)
    .join(`\n - `);
}

// For more complex resolutions
type FullyLoadedProject = Resolved<Project, {
  tasks: {
    $each: {
      title: true,
      subtasks: true,
      assignee: true
    }
  },
  owner: true
}>;

Using the `Resolved` type helps catch errors at compile time rather than runtime, ensuring that your components and functions receive data with the proper resolution depth. This is especially useful for larger applications where data is passed between many components.

## Ensuring Data is Loaded

Sometimes you need to make sure data is loaded before proceeding with an operation. The `ensureLoaded` method lets you guarantee that a CoValue and its referenced data are loaded to a specific depth:

<CodeGroup>
```ts twoslash

class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
  owner = co.ref(TeamMember);
}

class Task extends CoMap {
  title = co.string;
  status = co.literal("todo", "in-progress", "completed");
  subtasks = co.ref(ListOfTasks);
  assignee = co.optional.ref(TeamMember);
}

class TeamMember extends CoMap {
  name = co.string;
}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}

// ---cut-before---
async function completeAllTasks(projectId: ID<Project>) {
  // Ensure the project is loaded
  const project = await Project.load(projectId, { resolve: true });
  if (!project) return;

// Ensure tasks are loaded
  const loadedProject = await project.ensureLoaded({
    resolve: {
      tasks: {
        $each: true
      }
    }
  });

// Now we can safely access and modify tasks
  loadedProject.tasks.forEach(task => {
    task.status = "completed";
  });
}
```
</CodeGroup>

## Best Practices

1. **Be explicit about resolution depths**: Always specify exactly what you need
2. **Use framework integrations**: They handle subscription lifecycle automatically
3. **Clean up subscriptions**: Always store and call the unsubscribe function when you're done
4. **Handle all loading states**: Check for undefined (loading), null (not found), and success states
5. **Use the Resolved type**: Add compile-time type safety for components that require specific resolution patterns

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

## Creating a Group

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

<CodeGroup>
```tsx

const group = Group.create();
```
</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>

## 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");

const role = group.getRoleOf(bob);
```
</CodeGroup>

## Checking the permissions

You can check the permissions of an account on a CoValue by using the `canRead`, `canWrite` and `canAdmin` methods.

<CodeGroup>
```tsx
const value = await MyCoMap.load(valueID, {});
const me = Account.getMe();

To check the permissions of another account, you need to load it first:

<CodeGroup>
```tsx
const value = await MyCoMap.load(valueID, {});
const bob = await Account.load(accountID, []);

if (bob.canAdmin(value)) {
  console.log("Bob can share value with others"); 
} else if (bob.canWrite(value)) {
  console.log("Bob can edit value");
} else if (bob.canRead(value)) {
  console.log("Bob can view value");
} else {
  console.log("Bob cannot access value");
}
```
</CodeGroup>

#### 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="react-native-expo">
<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>

## Revoking a group extension

You can revoke a group extension by using the `revokeExtend` method:

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

childGroup.extend(parentGroup);

// Revoke the extension
await childGroup.revokeExtend(parentGroup);
```
</CodeGroup>

## Getting all parent groups

You can get all the parent groups of a group by calling the `getParentGroups` method:

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

console.log(childGroup.getParentGroups()); // [parentGroup]
```
</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.

## Authentication Flow

When a user first opens your app, they'll be in one of these states:

- **Anonymous Authentication**: Default starting point where Jazz automatically creates a local account on first visit. Data persists on one device and can be upgraded to a full account.

- **Authenticated Account**: Full account accessible across multiple devices using [passkeys](./passkey), [passphrases](./passphrase), or third-party authentications, such as [Clerk](./clerk).

- **Guest Mode**: No account, read-only access to public content. Users can browse but can't save data or sync.

Learn more about these states in the [Authentication States](./authentication-states) documentation.

Without authentication, users are limited to using the application on only one device.

When a user logs out of an Authenticated Account, they return to the Anonymous Authentication state with a new local account.

Here's what happens during registration and login:

- **Register**: When a user registers with an authentication provider, their Anonymous account credentials are stored in the auth provider, and the account is marked as Authenticated. The user keeps all their existing data.

- **Login**: When a user logs in with an authentication provider, their Anonymous account is discarded and the credentials are loaded from the auth provider. Data from the Anonymous account can be transferred using the [onAnonymousAccountDiscarded handler](./authentication-states#migrating-data-from-anonymous-to-authenticated-account).

## Available Authentication Methods

Jazz provides several ways to authenticate users:

- [**Passkeys**](./passkey): Secure, biometric authentication using WebAuthn
- [**Passphrases**](./passphrase): Bitcoin-style word phrases that users store
- [**Clerk Integration**](./clerk): Third-party authentication service with OAuth support

#### Authentication States

# Authentication States

Jazz provides three distinct authentication states that determine how users interact with your app: **Anonymous Authentication**, **Guest Mode**, and **Authenticated Account**.

## Anonymous Authentication

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

- Users have full accounts with unique IDs
- Data persists between sessions on the same device
- Can be upgraded to a full account (passkey, passphrase, etc.)
- Data syncs across the network (if enabled)

## Authenticated Account

**Authenticated Account** provides full multi-device functionality:

- Persistent identity across multiple devices
- Full access to all application features
- Data can sync across all user devices
- Multiple authentication methods available

## Guest Mode

**Guest Mode** provides a completely accountless context:

- No persistent identity or account
- Only provides access to publicly readable content
- Cannot save or sync user-specific data
- Suitable for read-only access to public resources

## Detecting Authentication State

You can detect the current authentication state using `useAccountOrGuest` and `useIsAuthenticated`.

<ContentByFramework framework="react">
<CodeGroup>
```tsx twoslash
// ---cut---

function AuthStateIndicator() {
  const { me } = useAccountOrGuest();
  const isAuthenticated = useIsAuthenticated();

// Check if guest mode is enabled in JazzProvider
  const isGuest = me._type !== "Account"

// Anonymous authentication: has an account but not fully authenticated
  const isAnonymous =  me._type === "Account" && !isAuthenticated;
  return (
    <div>
      {isGuest && <span>Guest Mode</span>}
      {isAnonymous && <span>Anonymous Account</span>}
      {isAuthenticated && <span>Authenticated</span>}
    </div>
  );
}
```
</CodeGroup>
</ContentByFramework>

## Migrating data from anonymous to authenticated account

When a user signs up, their anonymous account is transparently upgraded to an authenticated account, preserving all their data.

However, if a user has been using your app anonymously and later logs in with an existing account, their anonymous account data would normally be discarded. To prevent data loss, you can use the `onAnonymousAccountDiscarded` handler.

This example from our [music player example app](https://github.com/garden-co/jazz/tree/main/examples/music-player) shows how to migrate data:

<CodeGroup>
```ts twoslash

class MusicTrack extends CoMap {
  title = co.string;
  duration = co.number;
  isExampleTrack = co.optional.boolean;
}
class ListOfTracks extends CoList.Of(co.ref(MusicTrack)) {}
class Playlist extends CoMap {
  title = co.string;
  tracks = co.ref(ListOfTracks);
}
class MusicaAccountRoot extends CoMap {
  rootPlaylist = co.ref(Playlist);
}
class MusicaAccount extends Account {
  root = co.ref(MusicaAccountRoot);
}

// ---cut---
export async function onAnonymousAccountDiscarded(
  anonymousAccount: MusicaAccount,
) {
  const { root: anonymousAccountRoot } = await anonymousAccount.ensureLoaded({
    resolve: {
      root: {
        rootPlaylist: {
          tracks: {
            $each: true,
          },
        },
      },
    },
  });

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

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, try uploading a song in the [music player demo](https://music-demo.jazz.tools/) and then log in with an existing account.

## Controlling sync for different authentication states

You can control network sync with [Providers](/docs/project-setup/providers) based on authentication state:

- `when: "always"`: Sync is enabled for both Anonymous Authentication and Authenticated Account
- `when: "signedUp"`: Sync is enabled when the user is authenticated
- `when: "never"`: Sync is disabled, content stays local

<ContentByFramework framework="react">
<CodeGroup>
```tsx twoslash
const apiKey = "you@example.com";
function App() {
  return <div>Hello World</div>;
}
// ---cut---
<JazzProvider
  sync={{
    peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
     // Controls when sync is enabled for
     // both Anonymous Authentication and Authenticated Account
    when: "always", // or "signedUp" or "never"
  }}
>
  <App />
</JazzProvider>
```
</CodeGroup>
</ContentByFramework>

### Disable sync for Anonymous Authentication

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

For example, you may want to give users with Anonymous Authentication the opportunity to try your app locally-only (incurring no sync traffic), then enable network sync only when the user is fully authenticated.

<ContentByFramework framework="react">
<CodeGroup>
```tsx twoslash
const apiKey = "you@example.com";
function App() {
  return <div>Hello World</div>;
}
// ---cut---
<JazzProvider
  sync={{
    peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
     // This makes the app work in local mode when using Anonymous Authentication
    when: "signedUp",
  }}
>
  <App />
</JazzProvider>
```
</CodeGroup>
</ContentByFramework>

### Configuring Guest Mode Access

You can configure Guest Mode access with the `guestMode` prop for [Providers](/docs/project-setup/providers).

<ContentByFramework framework="react">
<CodeGroup>
```tsx twoslash
const apiKey = "you@example.com";
function App() {
  return <div>Hello World</div>;
}
// ---cut---
<JazzProvider
  // Enable Guest Mode for public content
  guestMode={true}
  sync={{
    peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
    // Only sync for authenticated users
    when: "signedUp",
  }}
>
  <App />
</JazzProvider>
```
</CodeGroup>
</ContentByFramework>

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

#### Passkey

# Passkey Authentication

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.

## How it works

Passkey authentication is based on the [Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) and uses familiar FaceID/TouchID flows that users already know how to use.

## Key benefits

- **Most secure**: Keys are managed by the device/OS
- **User-friendly**: Uses familiar biometric verification (FaceID/TouchID)
- **Cross-device**: Works across devices with the same biometric authentication
- **No password management**: Users don't need to remember or store anything
- **Wide support**: Available in most modern browsers

## Implementation

<ContentByFramework framework="react">
Using passkeys in Jazz is as easy as this:

<CodeGroup>
```tsx twoslash
type AuthModalProps = {
  open: boolean;
  onOpenChange: (open: boolean) => void;
}
// ---cut---
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>

## Examples

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

## When to use Passkeys

Passkeys are ideal when:
- Security is a top priority
- You want the most user-friendly authentication experience
- You're targeting modern browsers and devices
- You want to eliminate the risk of password-based attacks

## Limitations and considerations

- Requires hardware/OS support for biometric authentication
- Not supported in older browsers (see browser support below)
- Requires a fallback method for unsupported environments

### Browser Support

[Passkeys are supported in most modern browsers](https://caniuse.com/passkeys).

For older browsers, we recommend using [passphrase authentication](./passphrase) as a fallback.

## Additional resources

For more information about the Web Authentication API and passkeys:
- [WebAuthn.io](https://webauthn.io/)
- [MDN Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)

#### Passphrase

# Passphrase Authentication

Passphrase authentication lets users log into any device using a recovery phrase consisting of multiple words (similar to cryptocurrency wallets). Users are responsible for storing this passphrase safely.

## How it works

When a user creates an account with passphrase authentication:

1. Jazz generates a unique recovery phrase derived from the user's cryptographic keys
2. This phrase consists of words from a wordlist
3. Users save this phrase and enter it when logging in on new devices

You can use one of the ready-to-use wordlists from the [BIP39 repository](https://github.com/bitcoinjs/bip39/tree/a7ecbfe2e60d0214ce17163d610cad9f7b23140c/src/wordlists) or create your own.

## Key benefits

- **Portable**: Works across any device, even without browser or OS support
- **User-controlled**: User manages their authentication phrase
- **Flexible**: Works with any wordlist you choose
- **Offline capable**: No external dependencies

## Implementation

<ContentByFramework framework="react">
<CodeGroup>
```tsx twoslash
// @filename: wordlist.ts
export const wordlist = ["apple", "banana", "cherry", "date", "elderberry", "fig", "grape", "honeydew", "kiwi", "lemon", "mango", "orange", "pear", "quince", "raspberry", "strawberry", "tangerine", "uva", "watermelon", "xigua", "yuzu", "zucchini"];
// @filename: AuthModal.tsx
type AuthModalProps = {
  open: boolean;
  onOpenChange: (open: boolean) => void;
}
// ---cut---

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

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

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", "react-native-expo"]}>
<CodeGroup>
```tsx twoslash
// @filename: wordlist.ts
export const wordlist = ["apple", "banana", "cherry", "date", "elderberry", "fig", "grape", "honeydew", "kiwi", "lemon", "mango", "orange", "pear", "quince", "raspberry", "strawberry", "tangerine", "uva", "watermelon", "xigua", "yuzu", "zucchini"];
// @filename: AuthModal.tsx

type AuthModalProps = {
  open: boolean;
  onOpenChange: (open: boolean) => void;
}
// ---cut---

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

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

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}
        />
      </View>

## Examples

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

## When to use Passphrases

Passphrase authentication is ideal when:

- You need to support older browsers without WebAuthn capabilities
- Your users need to access the app on many different devices
- You want a fallback authentication method alongside passkeys

## Limitations and considerations

- **User responsibility**: Users must securely store their passphrase
- **Recovery concerns**: If a user loses their passphrase, they cannot recover their account
- **Security risk**: Anyone with the passphrase can access the account
- **User experience**: Requires users to enter a potentially long phrase

Make sure to emphasize to your users:
1. Store the passphrase in a secure location (password manager, written down in a safe place)
2. The passphrase is the only way to recover their account
3. Anyone with the passphrase can access the account

#### Clerk

### react-native Implementation

# Clerk Authentication

We do not currently support Clerk in React Native, but we do have support for [React Native Expo](/docs/react-native-expo/authentication/clerk).

### 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 {
  name = co.optional.string;

validate() {  // [!code ++:9]
    const errors: string[] = [];

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

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

Then perform the validation on submit.

<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 validation = draft.validate(); // [!code ++:5]
    if (validation.errors.length > 0) {
      console.log(validation.errors);
      return;
    }

const order = draft as BubbleTeaOrder;

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

if (!draft) return;

return <OrderForm order={draft} onSave={onSave} />;
}
```
</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 {
  name = co.string;
}

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

export class AccountRoot extends CoMap { // [!code ++:15]
  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 }) {
    return (
        <JazzProvider
            sync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com" }}
            AccountSchema={JazzAccount} // [!code ++]
        >
            {children}
        </JazzProvider>
    );
}

// Register the Account schema so `useAccount` returns our custom `JazzAccount`
declare module "jazz-react" { // [!code ++:5]
    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() {
  const { me } = useAccount({ root: { draft: {} } }); // [!code ++:3]

if (!me?.root) return;

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

const draft = me.root.draft; // [!code ++:2]
    if (!draft) return;

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

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

// create a new empty draft
    me.root.draft = DraftBubbleTeaOrder.create( // [!code ++:3]
      {},
    );
  };

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

function CreateOrderForm({ // [!code ++:13]
  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 {
  name = co.optional.string;

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

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

return { errors };
  }

get hasChanges() { // [!code ++:3]
    return Object.keys(this._edits).length;
  }
}
```
</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

## Music Example

### /vercel/path0/examples/music-player/src/1_schema.ts

```ts
import { Account, CoList, CoMap, FileStream, Profile, co } from "jazz-tools";

/** Walkthrough: Defining the data model with CoJSON
 *
 *  Here, we define our main data model of tasks, lists of tasks and projects
 *  using CoJSON's collaborative map and list types, CoMap & CoList.
 *
 *  CoMap values and CoLists items can contain:
 *  - arbitrary immutable JSON
 *  - other CoValues
 **/

export class MusicTrack extends CoMap {
  /**
   *  Attributes are defined as class properties
   *  and you can get the types from the `co` module
   *  here we are defining the title and duration for our music track
   *
   *  Tip: try to follow the co.string defintion to discover the other available primitives!
   */
  title = co.string;
  duration = co.number;

/**
   * With `co.ref` you can define relations between your coValues.
   *
   * Attributes are required by default unless you mark them as optional.
   */
  sourceTrack = co.optional.ref(MusicTrack);

/**
   * In Jazz you can upload files using FileStream.
   *
   * As for any other coValue the music files we put inside FileStream
   * is available offline and end-to-end encrypted 😉
   */
  file = co.ref(FileStream);
  waveform = co.ref(MusicTrackWaveform);

isExampleTrack = co.optional.boolean;
}

export class MusicTrackWaveform extends CoMap {
  data = co.json<number[]>();
}

/**
 * CoList is the collaborative version of Array
 *
 * They are strongly typed and accept only the type you define here
 * as "CoList.Of" argument
 */
export class ListOfTracks extends CoList.Of(co.ref(MusicTrack)) {}

export class Playlist extends CoMap {
  title = co.string;
  tracks = co.ref(ListOfTracks);
}

export class ListOfPlaylists extends CoList.Of(co.ref(Playlist)) {}

/** The account root is an app-specific per-user private `CoMap`
 *  where you can store top-level objects for that user */
export class MusicaAccountRoot extends CoMap {
  // The root playlist works as container for the tracks that
  // the user has uploaded
  rootPlaylist = co.ref(Playlist);
  // Here we store the list of playlists that the user has created
  // or that has been invited to
  playlists = co.ref(ListOfPlaylists);
  // We store the active track and playlist as coValue here
  // so when the user reloads the page can see the last played
  // track and playlist
  // You can also add the position in time if you want make it possible
  // to resume the song
  activeTrack = co.optional.ref(MusicTrack);
  activePlaylist = co.ref(Playlist);

exampleDataLoaded = co.optional.boolean;
}

export class MusicaAccount extends Account {
  profile = co.ref(Profile);
  root = co.ref(MusicaAccountRoot);

/**
   *  The account migration is run on account creation and on every log-in.
   *  You can use it to set up the account root and any other initial CoValues you need.
   */
  migrate() {
    if (this.root === undefined) {
      const tracks = ListOfTracks.create([]);
      const rootPlaylist = Playlist.create({
        tracks,
        title: "",
      });

this.root = MusicaAccountRoot.create({
        rootPlaylist,
        playlists: ListOfPlaylists.create([]),
        activeTrack: null,
        activePlaylist: rootPlaylist,
        exampleDataLoaded: false,
      });
    }
  }
}

/** Walkthrough: Continue with ./2_main.tsx */

```

### /vercel/path0/examples/music-player/src/2_main.tsx

```ts
import { Toaster } from "@/components/ui/toaster";
import { JazzInspector } from "jazz-inspector";
/* eslint-disable react-refresh/only-export-components */
import React from "react";
import ReactDOM from "react-dom/client";
import { RouterProvider, createHashRouter } from "react-router-dom";
import { HomePage } from "./3_HomePage";
import { useMediaPlayer } from "./5_useMediaPlayer";
import { InvitePage } from "./6_InvitePage";
import { PlayerControls } from "./components/PlayerControls";
import "./index.css";

import { MusicaAccount } from "@/1_schema";
import { apiKey } from "@/apiKey.ts";
import { JazzProvider } from "jazz-react";
import { onAnonymousAccountDiscarded } from "./4_actions";
import { useUploadExampleData } from "./lib/useUploadExampleData";

/**
 * Walkthrough: The top-level provider `<JazzProvider/>`
 *
 * This shows how to use the top-level provider `<JazzProvider/>`,
 * which provides the rest of the app with a controlled account (used through `useAccount` later).
 * Here we use `DemoAuth` which is great for prototyping you app without wasting time on figuring out
 * the best way to do auth.
 *
 * `<JazzProvider/>` also runs our account migration
 */

function Main() {
  const mediaPlayer = useMediaPlayer();

useUploadExampleData();

const router = createHashRouter([
    {
      path: "/",
      element: <HomePage mediaPlayer={mediaPlayer} />,
    },
    {
      path: "/playlist/:playlistId",
      element: <HomePage mediaPlayer={mediaPlayer} />,
    },
    {
      path: "/invite/*",
      element: <InvitePage />,
    },
  ]);

return (
    <>
      <RouterProvider router={router} />
      <PlayerControls mediaPlayer={mediaPlayer} />
      <Toaster />
    </>
  );
}

const peer =
  (new URL(window.location.href).searchParams.get(
    "peer",
  ) as `ws://${string}`) ?? `wss://cloud.jazz.tools/?key=${apiKey}`;

declare module "jazz-react" {
  interface Register {
    Account: MusicaAccount;
  }
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <JazzProvider
      sync={{
        peer,
      }}
      storage="indexedDB"
      AccountSchema={MusicaAccount}
      defaultProfileName="Anonymous unicorn"
      onAnonymousAccountDiscarded={onAnonymousAccountDiscarded}
    >
      <Main />
      <JazzInspector />
    </JazzProvider>
  </React.StrictMode>,
);

```

### /vercel/path0/examples/music-player/src/3_HomePage.tsx

```ts
import { useToast } from "@/hooks/use-toast";
import {
  createInviteLink,
  useAccount,
  useCoState,
  useIsAuthenticated,
} from "jazz-react";
import { ID } from "jazz-tools";
import { useNavigate, useParams } from "react-router";
import { Playlist } from "./1_schema";
import { createNewPlaylist, uploadMusicTracks } from "./4_actions";
import { MediaPlayer } from "./5_useMediaPlayer";
import { AuthButton } from "./components/AuthButton";
import { FileUploadButton } from "./components/FileUploadButton";
import { MusicTrackRow } from "./components/MusicTrackRow";
import { PlaylistTitleInput } from "./components/PlaylistTitleInput";
import { SidePanel } from "./components/SidePanel";
import { Button } from "./components/ui/button";
import { usePlayState } from "./lib/audio/usePlayState";

export function HomePage({ mediaPlayer }: { mediaPlayer: MediaPlayer }) {
  /**
   * `me` represents the current user account, which will determine
   *  access rights to CoValues. We get it from the top-level provider `<WithJazz/>`.
   */
  const { me } = useAccount({
    resolve: { root: { rootPlaylist: true, playlists: true } },
  });

const navigate = useNavigate();
  const playState = usePlayState();
  const isPlaying = playState.value === "play";
  const { toast } = useToast();

async function handleFileLoad(files: FileList) {
    /**
     * Follow this function definition to see how we update
     * values in Jazz and manage files!
     */
    await uploadMusicTracks(files);
  }

async function handleCreatePlaylist() {
    const playlist = await createNewPlaylist();

navigate(`/playlist/${playlist.id}`);
  }

const params = useParams<{ playlistId: ID<Playlist> }>();
  const playlistId = params.playlistId ?? me?.root._refs.rootPlaylist.id;

const playlist = useCoState(Playlist, playlistId, {
    resolve: { tracks: true },
  });

const isRootPlaylist = !params.playlistId;
  const isPlaylistOwner = playlist?._owner.myRole() === "admin";
  const isActivePlaylist = playlistId === me?.root.activePlaylist?.id;

const handlePlaylistShareClick = async () => {
    if (!isPlaylistOwner) return;

const inviteLink = createInviteLink(playlist, "reader");

await navigator.clipboard.writeText(inviteLink);

toast({
      title: "Invite link copied into the clipboard",
    });
  };

const isAuthenticated = useIsAuthenticated();

return (
    <div className="flex flex-col h-screen text-gray-800 bg-blue-50">
      <div className="flex flex-1 overflow-hidden">
        <SidePanel />
        <main className="flex-1 p-6 overflow-y-auto">
          <div className="flex items-center justify-between mb-6">
            {isRootPlaylist ? (
              <h1 className="text-2xl font-bold text-blue-800">All tracks</h1>
            ) : (
              <PlaylistTitleInput playlistId={playlistId} />
            )}
            <div className="flex items-center space-x-4">
              {isRootPlaylist && (
                <>
                  <FileUploadButton onFileLoad={handleFileLoad}>
                    Add file
                  </FileUploadButton>
                  <Button onClick={handleCreatePlaylist}>New playlist</Button>
                </>
              )}
              {!isRootPlaylist && isAuthenticated && (
                <Button onClick={handlePlaylistShareClick}>
                  Share playlist
                </Button>
              )}
              <AuthButton />
            </div>
          </div>
          <ul className="flex flex-col">
            {playlist?.tracks?.map(
              (track) =>
                track && (
                  <MusicTrackRow
                    trackId={track.id}
                    key={track.id}
                    isLoading={mediaPlayer.loading === track.id}
                    isPlaying={
                      mediaPlayer.activeTrackId === track.id &&
                      isActivePlaylist &&
                      isPlaying
                    }
                    onClick={() => {
                      mediaPlayer.setActiveTrack(track, playlist);
                    }}
                    showAddToPlaylist={isRootPlaylist}
                  />
                ),
            )}
          </ul>
        </main>
      </div>
    </div>
  );
}

```

### /vercel/path0/examples/music-player/src/4_actions.ts

```ts
import { getAudioFileData } from "@/lib/audio/getAudioFileData";
import { FileStream, Group } from "jazz-tools";
import {
  ListOfTracks,
  MusicTrack,
  MusicTrackWaveform,
  MusicaAccount,
  Playlist,
} from "./1_schema";

/**
 * Walkthrough: Actions
 *
 * With Jazz is very simple to update the state, you
 * just mutate the values and we take care of triggering
 * the updates and sync  and persist the values you change.
 *
 * We have grouped the complex updates here in an actions file
 * just to keep them separated from the components.
 *
 * Jazz is very unopinionated in this sense and you can adopt the
 * pattern that best fits your app.
 */

export async function uploadMusicTracks(
  files: Iterable<File>,
  isExampleTrack: boolean = false,
) {
  const { root } = await MusicaAccount.getMe().ensureLoaded({
    resolve: {
      root: {
        rootPlaylist: {
          tracks: true,
        },
      },
    },
  });

for (const file of files) {
    // The ownership object defines the user that owns the created coValues
    // We are creating a group for each CoValue in order to be able to share them via Playlist
    const group = Group.create();

const data = await getAudioFileData(file);

// We transform the file blob into a FileStream
    // making it a collaborative value that is encrypted, easy
    // to share across devices and users and available offline!
    const fileStream = await FileStream.createFromBlob(file, group);

const musicTrack = MusicTrack.create(
      {
        file: fileStream,
        duration: data.duration,
        waveform: MusicTrackWaveform.create({ data: data.waveform }, group),
        title: file.name,
        isExampleTrack,
      },
      group,
    );

// The newly created musicTrack can be associated to the
    // user track list using a simple push call
    root.rootPlaylist.tracks.push(musicTrack);
  }
}

export async function createNewPlaylist() {
  const { root } = await MusicaAccount.getMe().ensureLoaded({
    resolve: {
      root: {
        playlists: true,
      },
    },
  });

// Since playlists are meant to be shared we associate them
  // to a group which will contain the keys required to get
  // access to the "owned" values
  const playlistGroup = Group.create();

const playlist = Playlist.create(
    {
      title: "New Playlist",
      tracks: ListOfTracks.create([], playlistGroup),
    },
    playlistGroup,
  );

// Again, we associate the new playlist to the
  // user by pushing it into the playlists CoList
  root.playlists.push(playlist);

return playlist;
}

export async function addTrackToPlaylist(
  playlist: Playlist,
  track: MusicTrack,
) {
  const alreadyAdded = playlist.tracks?.some(
    (t) => t?.id === track.id || t?._refs.sourceTrack?.id === track.id,
  );

if (alreadyAdded) return;

// Check if the track has been created after the Group inheritance was introduced
  if (track._owner._type === "Group" && playlist._owner._type === "Group") {
    /**
     * Extending the track with the Playlist group in order to make the music track
     * visible to the Playlist user
     */
    const trackGroup = track._owner;
    trackGroup.extend(playlist._owner);

playlist.tracks?.push(track);
    return;
  }
}

export async function removeTrackFromPlaylist(
  playlist: Playlist,
  track: MusicTrack,
) {
  const notAdded = !playlist.tracks?.some(
    (t) => t?.id === track.id || t?._refs.sourceTrack?.id === track.id,
  );

if (notAdded) return;

if (track._owner._type === "Group" && playlist._owner._type === "Group") {
    const trackGroup = track._owner;
    await trackGroup.revokeExtend(playlist._owner);

const index =
      playlist.tracks?.findIndex(
        (t) => t?.id === track.id || t?._refs.sourceTrack?.id === track.id,
      ) ?? -1;
    if (index > -1) {
      playlist.tracks?.splice(index, 1);
    }
    return;
  }
}

export async function updatePlaylistTitle(playlist: Playlist, title: string) {
  playlist.title = title;
}

export async function updateMusicTrackTitle(track: MusicTrack, title: string) {
  track.title = title;
}

export async function updateActivePlaylist(playlist?: Playlist) {
  const { root } = await MusicaAccount.getMe().ensureLoaded({
    resolve: {
      root: {
        activePlaylist: true,
        rootPlaylist: true,
      },
    },
  });

root.activePlaylist = playlist ?? root.rootPlaylist;
}

export async function updateActiveTrack(track: MusicTrack) {
  const { root } = await MusicaAccount.getMe().ensureLoaded({
    resolve: {
      root: {},
    },
  });

root.activeTrack = track;
}

export async function onAnonymousAccountDiscarded(
  anonymousAccount: MusicaAccount,
) {
  const { root: anonymousAccountRoot } = await anonymousAccount.ensureLoaded({
    resolve: {
      root: {
        rootPlaylist: {
          tracks: {
            $each: true,
          },
        },
      },
    },
  });

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

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);
  }
}

export async function deletePlaylist(playlistId: string) {
  const { root } = await MusicaAccount.getMe().ensureLoaded({
    resolve: {
      root: {
        playlists: true,
      },
    },
  });

const index = root.playlists.findIndex((p) => p?.id === playlistId);
  if (index > -1) {
    root.playlists.splice(index, 1);
  }
}

```

### /vercel/path0/examples/music-player/src/5_useMediaPlayer.ts

```ts
import { MusicTrack, Playlist } from "@/1_schema";
import { usePlayMedia } from "@/lib/audio/usePlayMedia";
import { usePlayState } from "@/lib/audio/usePlayState";
import { useAccount } from "jazz-react";
import { FileStream, ID } from "jazz-tools";
import { useRef, useState } from "react";
import { updateActivePlaylist, updateActiveTrack } from "./4_actions";
import { getNextTrack, getPrevTrack } from "./lib/getters";

export function useMediaPlayer() {
  const { me } = useAccount({
    resolve: { root: true },
  });

const playState = usePlayState();
  const playMedia = usePlayMedia();

const [loading, setLoading] = useState<ID<MusicTrack> | null>(null);

const activeTrackId = me?.root._refs.activeTrack?.id;

// Reference used to avoid out-of-order track loads
  const lastLoadedTrackId = useRef<ID<MusicTrack> | null>(null);

async function loadTrack(track: MusicTrack) {
    lastLoadedTrackId.current = track.id;

setLoading(track.id);

const file = await FileStream.loadAsBlob(track._refs.file.id);

if (!file) {
      setLoading(null);
      return;
    }

// Check if another track has been loaded during
    // the file download
    if (lastLoadedTrackId.current !== track.id) {
      return;
    }

updateActiveTrack(track);

await playMedia(file);

setLoading(null);
  }

async function playNextTrack() {
    const track = await getNextTrack();

if (track) {
      updateActiveTrack(track);
      await loadTrack(track);
    }
  }

async function playPrevTrack() {
    const track = await getPrevTrack();

if (track) {
      await loadTrack(track);
    }
  }

async function setActiveTrack(track: MusicTrack, playlist?: Playlist) {
    if (activeTrackId === track.id && lastLoadedTrackId.current !== null) {
      playState.toggle();
      return;
    }

updateActivePlaylist(playlist);

await loadTrack(track);

if (playState.value === "pause") {
      playState.toggle();
    }
  }

return {
    activeTrackId,
    setActiveTrack,
    playNextTrack,
    playPrevTrack,
    loading,
  };
}

export type MediaPlayer = ReturnType<typeof useMediaPlayer>;

```

### /vercel/path0/examples/music-player/src/6_InvitePage.tsx

```ts
import { useAcceptInvite, useIsAuthenticated } from "jazz-react";
import { ID } from "jazz-tools";
import { useCallback } from "react";
import { useNavigate } from "react-router-dom";
import { MusicaAccount, Playlist } from "./1_schema";

export function InvitePage() {
  const navigate = useNavigate();

const isAuthenticated = useIsAuthenticated();

useAcceptInvite({
    invitedObjectSchema: Playlist,
    onAccept: useCallback(
      async (playlistId: ID<Playlist>) => {
        const playlist = await Playlist.load(playlistId, {});

const me = await MusicaAccount.getMe().ensureLoaded({
          resolve: {
            root: {
              playlists: true,
            },
          },
        });

if (
          playlist &&
          !me.root.playlists.some((item) => playlist.id === item?.id)
        ) {
          me.root.playlists.push(playlist);
        }

navigate("/playlist/" + playlistId);
      },
      [navigate],
    ),
  });

return isAuthenticated ? (
    <p>Accepting invite....</p>
  ) : (
    <p>Please sign in to accept the invite.</p>
  );
}

```

### /vercel/path0/examples/music-player/src/apiKey.ts

```ts
export const apiKey = "music-player-example-jazz@garden.co";

```

### /vercel/path0/examples/music-player/src/components/AuthButton.tsx

```ts
"use client";

import { Button } from "@/components/ui/button";
import { useAccount, useIsAuthenticated } from "jazz-react";
import { useState } from "react";
import { useNavigate } from "react-router-dom";
import { AuthModal } from "./AuthModal";

export function AuthButton() {
  const [open, setOpen] = useState(false);
  const { logOut } = useAccount();
  const navigate = useNavigate();

const isAuthenticated = useIsAuthenticated();

function handleSignOut() {
    logOut();
    navigate("/");
  }

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

return (
    <>
      <Button
        onClick={() => setOpen(true)}
        className="bg-white text-black hover:bg-gray-100"
      >
        Sign up
      </Button>
      <AuthModal open={open} onOpenChange={setOpen} />
    </>
  );
}

```

### /vercel/path0/examples/music-player/src/components/AuthModal.tsx

```ts
import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
} from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { useAccount, usePasskeyAuth } from "jazz-react";
import { useState } from "react";

interface AuthModalProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
}

export function AuthModal({ open, onOpenChange }: AuthModalProps) {
  const [username, setUsername] = useState("");
  const [isSignUp, setIsSignUp] = useState(true);
  const [error, setError] = useState<string | null>(null);

const { me } = useAccount({
    resolve: {
      root: {
        rootPlaylist: {
          tracks: {
            $each: true,
          },
        },
      },
    },
  });

const auth = usePasskeyAuth({
    appName: "Jazz Music Player",
  });

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

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

try {
      if (isSignUp) {
        await auth.signUp(username);
      } else {
        await auth.logIn();
      }
      onOpenChange(false);
    } catch (error) {
      setError(error instanceof Error ? error.message : "Unknown error");
    }
  };

const shouldShowTransferRootPlaylist =
    !isSignUp &&
    me?.root.rootPlaylist.tracks.some((track) => !track.isExampleTrack);

return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent className="sm:max-w-[425px]">
        <DialogHeader>
          <DialogTitle className="text-2xl font-bold">
            {isSignUp ? "Create account" : "Welcome back"}
          </DialogTitle>
          <DialogDescription>
            {isSignUp
              ? "Sign up to enable network sync and share your playlists with others"
              : "Changes done before logging in will be lost"}
          </DialogDescription>
        </DialogHeader>
        <form onSubmit={handleSubmit} className="space-y-4">
          {isSignUp && (
            <div className="space-y-2">
              <Label htmlFor="username">Username</Label>
              <Input
                id="username"
                value={username}
                onChange={(e) => setUsername(e.target.value)}
                placeholder="Enter your username"
                required
              />
            </div>
          )}
          {error && <div className="text-sm text-red-500">{error}</div>}
          {shouldShowTransferRootPlaylist && (
            <div className="text-sm text-red-500">
              You have tracks in your root playlist that are not example tracks.
              If you log in with a passkey, your playlists will be transferred
              to your logged account.
            </div>
          )}
          <div className="space-y-4">
            <Button
              type="submit"
              className="w-full bg-blue-600 hover:bg-blue-700"
            >
              {isSignUp ? "Sign up with passkey" : "Login with passkey"}
            </Button>
            <div className="text-center text-sm">
              {isSignUp ? "Already have an account?" : "Don't have an account?"}{" "}
              <button
                type="button"
                onClick={handleViewChange}
                className="text-blue-600 hover:underline"
              >
                {isSignUp ? "Login" : "Sign up"}
              </button>
            </div>
          </div>
        </form>
      </DialogContent>
    </Dialog>
  );
}

```

### /vercel/path0/examples/music-player/src/components/FileUploadButton.tsx

```ts
import { ReactNode } from "react";
import { Button } from "./ui/button";

export function FileUploadButton(props: {
  onFileLoad: (files: FileList) => Promise<void>;
  children: ReactNode;
}) {
  async function handleFileLoad(evt: React.ChangeEvent<HTMLInputElement>) {
    if (!evt.target.files) return;

await props.onFileLoad(evt.target.files);

evt.target.value = "";
  }

return (
    <Button>
      <label className="flex items-center  cursor-pointer p-2">
        <input type="file" onChange={handleFileLoad} multiple hidden />
        {props.children}
      </label>
    </Button>
  );
}

```

### /vercel/path0/examples/music-player/src/components/LocalOnlyTag.tsx

```ts
import { Badge } from "@/components/ui/badge";
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip";
import { useIsAuthenticated } from "jazz-react";
import { Info } from "lucide-react";

export function LocalOnlyTag() {
  const isAuthenticated = useIsAuthenticated();

if (isAuthenticated) {
    return null;
  }

return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <div className="inline-flex items-center gap-1.5 cursor-help">
            <Badge variant="default" className="h-5 text-xs font-normal">
              Local only
            </Badge>
            <Info className="h-3.5 w-3.5 text-muted-foreground" />
          </div>
        </TooltipTrigger>
        <TooltipContent className="max-w-[250px]">
          <p>
            Sign up to enable network sync and share your playlists with others
          </p>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

```

### /vercel/path0/examples/music-player/src/components/LogoutButton.tsx

```ts
import { useAccount } from "jazz-react";
import { Button } from "./ui/button";

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

return <Button onClick={logOut}>Logout</Button>;
}

```

### /vercel/path0/examples/music-player/src/components/MusicTrackRow.tsx

```ts
import { MusicTrack, Playlist } from "@/1_schema";
import { addTrackToPlaylist, removeTrackFromPlaylist } from "@/4_actions";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { cn } from "@/lib/utils";
import { useAccount, useCoState } from "jazz-react";
import { ID } from "jazz-tools";
import { MoreHorizontal } from "lucide-react";
import { Fragment } from "react/jsx-runtime";
import { MusicTrackTitleInput } from "./MusicTrackTitleInput";
import { Button } from "./ui/button";

export function MusicTrackRow({
  trackId,
  isLoading,
  isPlaying,
  onClick,
  showAddToPlaylist,
}: {
  trackId: ID<MusicTrack>;
  isLoading: boolean;
  isPlaying: boolean;
  onClick: (track: MusicTrack) => void;
  showAddToPlaylist: boolean;
}) {
  const track = useCoState(MusicTrack, trackId);

const { me } = useAccount({
    resolve: { root: { playlists: { $each: true } } },
  });

const playlists = me?.root.playlists ?? [];

function handleTrackClick() {
    if (!track) return;
    onClick(track);
  }

function handleAddToPlaylist(playlist: Playlist) {
    if (!track) return;
    addTrackToPlaylist(playlist, track);
  }

function handleRemoveFromPlaylist(playlist: Playlist) {
    if (!track) return;
    removeTrackFromPlaylist(playlist, track);
  }

function deleteTrack() {
    if (!me || !track) return;
    const tracks = me.root.rootPlaylist?.tracks;
    if (!tracks) return;
    const index = tracks.findIndex((t) => t?.id === trackId);
    if (index !== -1) {
      tracks.splice(index, 1);
    }
  }

return (
    <li
      className={
        "flex gap-1  hover:bg-slate-200 group py-2 px-2 cursor-pointer"
      }
      onClick={handleTrackClick}
    >
      <button
        className={cn(
          "flex items-center justify-center bg-transparent w-8 h-8 ",
          !isPlaying && "group-hover:bg-slate-300 rounded-full",
        )}
        onClick={handleTrackClick}
        aria-label={`${isPlaying ? "Pause" : "Play"} ${track?.title}`}
      >
        {isLoading ? (
          <div className="animate-spin">߷</div>
        ) : isPlaying ? (
          "⏸️"
        ) : (
          "▶️"
        )}
      </button>
      <MusicTrackTitleInput trackId={trackId} />
      <div onClick={(evt) => evt.stopPropagation()}>
        {showAddToPlaylist && (
          <DropdownMenu>
            <DropdownMenuTrigger asChild>
              <Button
                variant="ghost"
                className="h-8 w-8 p-0"
                aria-label={`Open ${track?.title} menu`}
              >
                <span className="sr-only">Open menu</span>
                <MoreHorizontal className="h-4 w-4" />
              </Button>
            </DropdownMenuTrigger>
            <DropdownMenuContent align="end">
              <DropdownMenuItem
                key={`delete`}
                onSelect={async () => {
                  if (!track) return;
                  deleteTrack();
                }}
              >
                Delete
              </DropdownMenuItem>
              {playlists.map((playlist, index) => (
                <Fragment key={index}>
                  <DropdownMenuItem
                    key={`add-${index}`}
                    onSelect={() => handleAddToPlaylist(playlist)}
                  >
                    Add to {playlist.title}
                  </DropdownMenuItem>
                  <DropdownMenuItem
                    key={`remove-${index}`}
                    onSelect={() => handleRemoveFromPlaylist(playlist)}
                  >
                    Remove from {playlist.title}
                  </DropdownMenuItem>
                </Fragment>
              ))}
            </DropdownMenuContent>
          </DropdownMenu>
        )}
      </div>
    </li>
  );
}

```

### /vercel/path0/examples/music-player/src/components/MusicTrackTitleInput.tsx

```ts
import { MusicTrack } from "@/1_schema";
import { updateMusicTrackTitle } from "@/4_actions";
import { useCoState } from "jazz-react";
import { ID } from "jazz-tools";
import { ChangeEvent, useState } from "react";

export function MusicTrackTitleInput({
  trackId,
}: {
  trackId: ID<MusicTrack> | undefined;
}) {
  const track = useCoState(MusicTrack, trackId);
  const [isEditing, setIsEditing] = useState(false);
  const [localTrackTitle, setLocalTrackTitle] = useState("");

function handleTitleChange(evt: ChangeEvent<HTMLInputElement>) {
    setLocalTrackTitle(evt.target.value);
  }

function handleFoucsIn() {
    setIsEditing(true);
    setLocalTrackTitle(track?.title ?? "");
  }

function handleFocusOut() {
    setIsEditing(false);
    setLocalTrackTitle("");
    track && updateMusicTrackTitle(track, localTrackTitle);
  }

const inputValue = isEditing ? localTrackTitle : (track?.title ?? "");

return (
    <div
      className="relative flex-grow"
      onClick={(evt) => evt.stopPropagation()}
    >
      <input
        className="absolute w-full h-full left-0 bg-transparent px-1"
        value={inputValue}
        onChange={handleTitleChange}
        spellCheck="false"
        onFocus={handleFoucsIn}
        onBlur={handleFocusOut}
        aria-label={`Edit track title: ${track?.title}`}
      />
      <span className="opacity-0 px-1 w-fit pointer-events-none whitespace-pre">
        {inputValue}
      </span>
    </div>
  );
}

```

### /vercel/path0/examples/music-player/src/components/PlayerControls.tsx

```ts
import { MusicTrack } from "@/1_schema";
import { MediaPlayer } from "@/5_useMediaPlayer";
import { useMediaEndListener } from "@/lib/audio/useMediaEndListener";
import { usePlayState } from "@/lib/audio/usePlayState";
import { useKeyboardListener } from "@/lib/useKeyboardListener";
import { useAccount, useCoState } from "jazz-react";
import { Pause, Play, SkipBack, SkipForward } from "lucide-react";
import { Waveform } from "./Waveform";

export function PlayerControls({ mediaPlayer }: { mediaPlayer: MediaPlayer }) {
  const playState = usePlayState();
  const isPlaying = playState.value === "play";

const activePlaylist = useAccount({
    resolve: { root: { activePlaylist: true } },
  }).me?.root.activePlaylist;

useMediaEndListener(mediaPlayer.playNextTrack);
  useKeyboardListener("Space", () => {
    if (document.activeElement !== document.body) return;

playState.toggle();
  });

const activeTrack = useCoState(MusicTrack, mediaPlayer.activeTrackId, {
    resolve: { waveform: true },
  });

if (!activeTrack) return null;

const activeTrackTitle = activeTrack.title;

return (
    <footer className="flex items-center justify-between p-4 gap-4 bg-white border-t border-gray-200 fixed bottom-0 left-0 right-0 w-full">
      <div className="flex justify-center items-center space-x-2">
        <div className="flex items-center space-x-4">
          <button
            onClick={mediaPlayer.playPrevTrack}
            className="text-blue-600 hover:text-blue-800"
            aria-label="Previous track"
          >
            <SkipBack size={20} />
          </button>
          <button
            onClick={playState.toggle}
            className="w-[42px] h-[42px] flex items-center justify-center bg-blue-600 rounded-full text-white hover:bg-blue-700"
            aria-label={isPlaying ? "Pause active track" : "Play active track"}
          >
            {isPlaying ? (
              <Pause size={24} fill="currentColor" />
            ) : (
              <Play size={24} fill="currentColor" />
            )}
          </button>
          <button
            onClick={mediaPlayer.playNextTrack}
            className="text-blue-600 hover:text-blue-800"
            aria-label="Next track"
          >
            <SkipForward size={20} />
          </button>
        </div>
      </div>
      <div className=" sm:hidden md:flex flex-col flex-shrink-1 items-center w-[75%]">
        <Waveform track={activeTrack} height={30} />
      </div>
      <div className="flex flex-col items-end  gap-1 text-right min-w-fit w-[25%]">
        <h4 className="font-medium text-blue-800">{activeTrackTitle}</h4>
        <p className="text-sm text-gray-600">
          {activePlaylist?.title || "All tracks"}
        </p>
      </div>
    </footer>
  );
}

```

### /vercel/path0/examples/music-player/src/components/PlaylistTitleInput.tsx

```ts
import { Playlist } from "@/1_schema";
import { updatePlaylistTitle } from "@/4_actions";
import { useCoState } from "jazz-react";
import { ID } from "jazz-tools";
import { ChangeEvent, useState } from "react";

export function PlaylistTitleInput({
  playlistId,
}: {
  playlistId: ID<Playlist> | undefined;
}) {
  const playlist = useCoState(Playlist, playlistId);
  const [isEditing, setIsEditing] = useState(false);
  const [localPlaylistTitle, setLocalPlaylistTitle] = useState("");

function handleTitleChange(evt: ChangeEvent<HTMLInputElement>) {
    setLocalPlaylistTitle(evt.target.value);
  }

function handleFoucsIn() {
    setIsEditing(true);
    setLocalPlaylistTitle(playlist?.title ?? "");
  }

function handleFocusOut() {
    setIsEditing(false);
    setLocalPlaylistTitle("");
    playlist && updatePlaylistTitle(playlist, localPlaylistTitle);
  }

const inputValue = isEditing ? localPlaylistTitle : (playlist?.title ?? "");

return (
    <input
      value={inputValue}
      onChange={handleTitleChange}
      className="text-2xl font-bold text-blue-800 bg-transparent"
      onFocus={handleFoucsIn}
      onBlur={handleFocusOut}
      aria-label={`Playlist title`}
    />
  );
}

```

### /vercel/path0/examples/music-player/src/components/SidePanel.tsx

```ts
import { deletePlaylist } from "@/4_actions";
import { useAccount } from "jazz-react";
import { Trash2 } from "lucide-react";
import { useNavigate, useParams } from "react-router";
import { LocalOnlyTag } from "./LocalOnlyTag";

export function SidePanel() {
  const { playlistId } = useParams();
  const navigate = useNavigate();
  const { me } = useAccount({
    resolve: { root: { playlists: { $each: true } } },
  });

function handleAllTracksClick(evt: React.MouseEvent<HTMLAnchorElement>) {
    evt.preventDefault();
    navigate(`/`);
  }

function handlePlaylistClick(
    evt: React.MouseEvent<HTMLAnchorElement>,
    playlistId: string,
  ) {
    evt.preventDefault();
    navigate(`/playlist/${playlistId}`);
  }

async function handleDeletePlaylist(playlistId: string) {
    if (confirm("Are you sure you want to delete this playlist?")) {
      await deletePlaylist(playlistId);
      navigate(`/`);
    }
  }

return (
    <aside className="w-64 p-6 bg-white overflow-y-auto">
      <div className="flex items-center mb-1">
        <svg
          className="w-8 h-8 mr-2"
          viewBox="0 0 24 24"
          fill="none"
          xmlns="http://www.w3.org/2000/svg"
        >
          <path
            d="M9 18V5l12-2v13"
            stroke="#3b82f6"
            strokeWidth="2"
            strokeLinecap="round"
            strokeLinejoin="round"
          />
          <path
            d="M6 15H3c-1.1 0-2 .9-2 2v4c0 1.1.9 2 2 2h3c1.1 0 2-.9 2-2v-4c0-1.1-.9-2-2-2zM18 13h-3c-1.1 0-2 .9-2 2v4c0 1.1.9 2 2 2h3c1.1 0 2-.9 2-2v-4c0-1.1-.9-2-2-2z"
            fill="#3b82f6"
          />
        </svg>
        <span className="text-xl font-bold text-blue-600">Music Player</span>
      </div>
      <div className="mb-6">
        <LocalOnlyTag />
      </div>
      <nav>
        <h2 className="mb-2 text-sm font-semibold text-gray-600">Playlists</h2>
        <ul className="space-y-1">
          <li>
            <a
              href="#"
              className={`block px-2 py-1 text-sm rounded ${
                !playlistId ? "bg-blue-100 text-blue-600" : "hover:bg-blue-100"
              }`}
              onClick={handleAllTracksClick}
            >
              All tracks
            </a>
          </li>
          {me?.root.playlists.map((playlist, index) => (
            <li
              key={index}
              className={`px-2 py-1 flex transition-all duration-300 rounded items-center justify-between ${
                playlist.id === playlistId ? "bg-blue-100" : ""
              }`}
            >
              <a
                href="#"
                className={`w-full text-sm`}
                onClick={(evt) => handlePlaylistClick(evt, playlist.id)}
              >
                {playlist.title}
              </a>
              {playlist.id === playlistId && (
                <button
                  onClick={() => handleDeletePlaylist(playlist.id)}
                  className="ml-2 text-red-600 hover:text-red-800 animate-in fade-in scale-in duration-200"
                  aria-label={`Delete ${playlist.title}`}
                >
                  <Trash2 size={16} />
                </button>
              )}
            </li>
          ))}
        </ul>
      </nav>
    </aside>
  );
}

```

### /vercel/path0/examples/music-player/src/components/Waveform.tsx

```ts
import { MusicTrack, MusicTrackWaveform } from "@/1_schema";
import { usePlayerCurrentTime } from "@/lib/audio/usePlayerCurrentTime";
import { cn } from "@/lib/utils";
import { useCoState } from "jazz-react";

export function Waveform(props: { track: MusicTrack; height: number }) {
  const { track, height } = props;
  const waveformData = useCoState(
    MusicTrackWaveform,
    track._refs.waveform.id,
  )?.data;
  const duration = track.duration;

const currentTime = usePlayerCurrentTime();

if (!waveformData) {
    return (
      <div
        style={{
          height,
        }}
      />
    );
  }

const barCount = waveformData.length;
  const activeBar = Math.ceil(barCount * (currentTime.value / duration));

function seek(i: number) {
    currentTime.setValue((i / barCount) * duration);
  }

return (
    <div
      className="flex justify-center items-end w-full"
      style={{
        height,
        gap: 1,
      }}
    >
      {waveformData.map((value, i) => (
        <button
          type="button"
          key={i}
          onClick={() => seek(i)}
          className={cn(
            "w-1 transition-colors rounded-none rounded-t-lg min-h-1",
            activeBar >= i ? "bg-gray-500" : "bg-gray-300",
            "hover:bg-black hover:border-1 hover:border-solid hover:border-black",
            "focus-visible:outline-black focus:outline-none",
          )}
          style={{
            height: height * value,
          }}
          aria-label={`Seek to ${(i / barCount) * duration} seconds`}
        />
      ))}
    </div>
  );
}

```

### /vercel/path0/examples/music-player/src/components/ui/badge.tsx

```ts
import { type VariantProps, cva } from "class-variance-authority";
import * as React from "react";

import { cn } from "@/lib/utils";

const badgeVariants = cva(
  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
  {
    variants: {
      variant: {
        default:
          "border-transparent bg-primary text-primary-foreground hover:bg-primary/80",
        secondary:
          "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
        destructive:
          "border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
        outline: "text-foreground",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  },
);

export interface BadgeProps
  extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof badgeVariants> {}

function Badge({ className, variant, ...props }: BadgeProps) {
  return (
    <div className={cn(badgeVariants({ variant }), className)} {...props} />
  );
}

export { Badge, badgeVariants };

```

### /vercel/path0/examples/music-player/src/components/ui/button.tsx

```ts
import { Slot } from "@radix-ui/react-slot";
import { type VariantProps, cva } from "class-variance-authority";
import * as React from "react";

import { cn } from "@/lib/utils";

const buttonVariants = cva(
  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive:
          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline:
          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary:
          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  },
);

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

// eslint-disable-next-line react-refresh/only-export-components
export { Button, buttonVariants };

```

### /vercel/path0/examples/music-player/src/components/ui/dialog.tsx

```ts
import * as DialogPrimitive from "@radix-ui/react-dialog";
import { X } from "lucide-react";
import * as React from "react";

import { cn } from "@/lib/utils";

const Dialog = DialogPrimitive.Root;

const DialogTrigger = DialogPrimitive.Trigger;

const DialogPortal = DialogPrimitive.Portal;

const DialogClose = DialogPrimitive.Close;

const DialogOverlay = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Overlay>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
>(({ className, ...props }, ref) => (
  <DialogPrimitive.Overlay
    ref={ref}
    className={cn(
      "fixed inset-0 z-50 bg-black/80  data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
      className,
    )}
    {...props}
  />
));
DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;

const DialogContent = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
>(({ className, children, ...props }, ref) => (
  <DialogPortal>
    <DialogOverlay />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
        className,
      )}
      {...props}
    >
      {children}
      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
        <X className="h-4 w-4" />
        <span className="sr-only">Close</span>
      </DialogPrimitive.Close>
    </DialogPrimitive.Content>
  </DialogPortal>
));
DialogContent.displayName = DialogPrimitive.Content.displayName;

const DialogHeader = ({
  className,
  ...props
}: React.HTMLAttributes<HTMLDivElement>) => (
  <div
    className={cn(
      "flex flex-col space-y-1.5 text-center sm:text-left",
      className,
    )}
    {...props}
  />
);
DialogHeader.displayName = "DialogHeader";

const DialogFooter = ({
  className,
  ...props
}: React.HTMLAttributes<HTMLDivElement>) => (
  <div
    className={cn(
      "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
      className,
    )}
    {...props}
  />
);
DialogFooter.displayName = "DialogFooter";

const DialogTitle = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Title>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
>(({ className, ...props }, ref) => (
  <DialogPrimitive.Title
    ref={ref}
    className={cn(
      "text-lg font-semibold leading-none tracking-tight",
      className,
    )}
    {...props}
  />
));
DialogTitle.displayName = DialogPrimitive.Title.displayName;

const DialogDescription = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Description>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
>(({ className, ...props }, ref) => (
  <DialogPrimitive.Description
    ref={ref}
    className={cn("text-sm text-muted-foreground", className)}
    {...props}
  />
));
DialogDescription.displayName = DialogPrimitive.Description.displayName;

export {
  Dialog,
  DialogPortal,
  DialogOverlay,
  DialogClose,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogFooter,
  DialogTitle,
  DialogDescription,
};

```

### /vercel/path0/examples/music-player/src/components/ui/dropdown-menu.tsx

```ts
import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
import { Check, ChevronRight, Circle } from "lucide-react";
import * as React from "react";

import { cn } from "@/lib/utils";

const DropdownMenu = DropdownMenuPrimitive.Root;

const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;

const DropdownMenuGroup = DropdownMenuPrimitive.Group;

const DropdownMenuPortal = DropdownMenuPrimitive.Portal;

const DropdownMenuSub = DropdownMenuPrimitive.Sub;

const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup;

const DropdownMenuSubContent = React.forwardRef<
  React.ElementRef<typeof DropdownMenuPrimitive.SubContent>,
  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent>
>(({ className, ...props }, ref) => (
  <DropdownMenuPrimitive.SubContent
    ref={ref}
    className={cn(
      "z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
      className,
    )}
    {...props}
  />
));
DropdownMenuSubContent.displayName =
  DropdownMenuPrimitive.SubContent.displayName;

const DropdownMenuContent = React.forwardRef<
  React.ElementRef<typeof DropdownMenuPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
>(({ className, sideOffset = 4, ...props }, ref) => (
  <DropdownMenuPrimitive.Portal>
    <DropdownMenuPrimitive.Content
      ref={ref}
      sideOffset={sideOffset}
      className={cn(
        "z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
        className,
      )}
      {...props}
    />
  </DropdownMenuPrimitive.Portal>
));
DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName;

const DropdownMenuCheckboxItem = React.forwardRef<
  React.ElementRef<typeof DropdownMenuPrimitive.CheckboxItem>,
  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.CheckboxItem>
>(({ className, children, checked, ...props }, ref) => (
  <DropdownMenuPrimitive.CheckboxItem
    ref={ref}
    className={cn(
      "relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
      className,
    )}
    checked={checked}
    {...props}
  >
    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
      <DropdownMenuPrimitive.ItemIndicator>
        <Check className="h-4 w-4" />
      </DropdownMenuPrimitive.ItemIndicator>
    </span>
    {children}
  </DropdownMenuPrimitive.CheckboxItem>
));
DropdownMenuCheckboxItem.displayName =
  DropdownMenuPrimitive.CheckboxItem.displayName;

const DropdownMenuRadioItem = React.forwardRef<
  React.ElementRef<typeof DropdownMenuPrimitive.RadioItem>,
  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.RadioItem>
>(({ className, children, ...props }, ref) => (
  <DropdownMenuPrimitive.RadioItem
    ref={ref}
    className={cn(
      "relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
      className,
    )}
    {...props}
  >
    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
      <DropdownMenuPrimitive.ItemIndicator>
        <Circle className="h-2 w-2 fill-current" />
      </DropdownMenuPrimitive.ItemIndicator>
    </span>
    {children}
  </DropdownMenuPrimitive.RadioItem>
));
DropdownMenuRadioItem.displayName = DropdownMenuPrimitive.RadioItem.displayName;

const DropdownMenuSeparator = React.forwardRef<
  React.ElementRef<typeof DropdownMenuPrimitive.Separator>,
  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Separator>
>(({ className, ...props }, ref) => (
  <DropdownMenuPrimitive.Separator
    ref={ref}
    className={cn("-mx-1 my-1 h-px bg-muted", className)}
    {...props}
  />
));
DropdownMenuSeparator.displayName = DropdownMenuPrimitive.Separator.displayName;

export {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuCheckboxItem,
  DropdownMenuRadioItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuGroup,
  DropdownMenuPortal,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuRadioGroup,
};

```

### /vercel/path0/examples/music-player/src/components/ui/input.tsx

```ts
import * as React from "react";

import { cn } from "@/lib/utils";

export { Input };

```

### /vercel/path0/examples/music-player/src/components/ui/label.tsx

```ts
import * as LabelPrimitive from "@radix-ui/react-label";
import { type VariantProps, cva } from "class-variance-authority";
import * as React from "react";

import { cn } from "@/lib/utils";

const labelVariants = cva(
  "text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
);

const Label = React.forwardRef<
  React.ElementRef<typeof LabelPrimitive.Root>,
  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root> &
    VariantProps<typeof labelVariants>
>(({ className, ...props }, ref) => (
  <LabelPrimitive.Root
    ref={ref}
    className={cn(labelVariants(), className)}
    {...props}
  />
));
Label.displayName = LabelPrimitive.Root.displayName;

export { Label };

```

### /vercel/path0/examples/music-player/src/components/ui/toast.tsx

```ts
import * as ToastPrimitives from "@radix-ui/react-toast";
import { type VariantProps, cva } from "class-variance-authority";
import { X } from "lucide-react";
import * as React from "react";

import { cn } from "@/lib/utils";

const ToastProvider = ToastPrimitives.Provider;

const ToastViewport = React.forwardRef<
  React.ElementRef<typeof ToastPrimitives.Viewport>,
  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Viewport>
>(({ className, ...props }, ref) => (
  <ToastPrimitives.Viewport
    ref={ref}
    className={cn(
      "fixed top-0 z-[100] flex max-h-screen w-full flex-col-reverse p-4 sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-[420px]",
      className,
    )}
    {...props}
  />
));
ToastViewport.displayName = ToastPrimitives.Viewport.displayName;

const toastVariants = cva(
  "group pointer-events-auto relative flex w-full items-center justify-between space-x-4 overflow-hidden rounded-md border p-6 pr-8 shadow-lg transition-all data-[swipe=cancel]:translate-x-0 data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)] data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[swipe=end]:animate-out data-[state=closed]:fade-out-80 data-[state=closed]:slide-out-to-right-full data-[state=open]:slide-in-from-top-full data-[state=open]:sm:slide-in-from-bottom-full",
  {
    variants: {
      variant: {
        default: "border bg-background text-foreground",
        destructive:
          "destructive group border-destructive bg-destructive text-destructive-foreground",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  },
);

const ToastAction = React.forwardRef<
  React.ElementRef<typeof ToastPrimitives.Action>,
  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Action>
>(({ className, ...props }, ref) => (
  <ToastPrimitives.Action
    ref={ref}
    className={cn(
      "inline-flex h-8 shrink-0 items-center justify-center rounded-md border bg-transparent px-3 text-sm font-medium ring-offset-background transition-colors hover:bg-secondary focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 group-[.destructive]:border-muted/40 group-[.destructive]:hover:border-destructive/30 group-[.destructive]:hover:bg-destructive group-[.destructive]:hover:text-destructive-foreground group-[.destructive]:focus:ring-destructive",
      className,
    )}
    {...props}
  />
));
ToastAction.displayName = ToastPrimitives.Action.displayName;

const ToastClose = React.forwardRef<
  React.ElementRef<typeof ToastPrimitives.Close>,
  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Close>
>(({ className, ...props }, ref) => (
  <ToastPrimitives.Close
    ref={ref}
    className={cn(
      "absolute right-2 top-2 rounded-md p-1 text-foreground/50 opacity-0 transition-opacity hover:text-foreground focus:opacity-100 focus:outline-none focus:ring-2 group-hover:opacity-100 group-[.destructive]:text-red-300 group-[.destructive]:hover:text-red-50 group-[.destructive]:focus:ring-red-400 group-[.destructive]:focus:ring-offset-red-600",
      className,
    )}
    toast-close=""
    {...props}
  >
    <X className="h-4 w-4" />
  </ToastPrimitives.Close>
));
ToastClose.displayName = ToastPrimitives.Close.displayName;

const ToastTitle = React.forwardRef<
  React.ElementRef<typeof ToastPrimitives.Title>,
  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Title>
>(({ className, ...props }, ref) => (
  <ToastPrimitives.Title
    ref={ref}
    className={cn("text-sm font-semibold", className)}
    {...props}
  />
));
ToastTitle.displayName = ToastPrimitives.Title.displayName;

const ToastDescription = React.forwardRef<
  React.ElementRef<typeof ToastPrimitives.Description>,
  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Description>
>(({ className, ...props }, ref) => (
  <ToastPrimitives.Description
    ref={ref}
    className={cn("text-sm opacity-90", className)}
    {...props}
  />
));
ToastDescription.displayName = ToastPrimitives.Description.displayName;

type ToastProps = React.ComponentPropsWithoutRef<typeof Toast>;

type ToastActionElement = React.ReactElement<typeof ToastAction>;

export {
  type ToastProps,
  type ToastActionElement,
  ToastProvider,
  ToastViewport,
  Toast,
  ToastTitle,
  ToastDescription,
  ToastClose,
  ToastAction,
};

```

### /vercel/path0/examples/music-player/src/components/ui/toaster.tsx

```ts
import {
  Toast,
  ToastClose,
  ToastDescription,
  ToastProvider,
  ToastTitle,
  ToastViewport,
} from "@/components/ui/toast";
import { useToast } from "@/hooks/use-toast";

export function Toaster() {
  const { toasts } = useToast();

return (
    <ToastProvider>
      {toasts.map(function ({ id, title, description, action, ...props }) {
        return (
          <Toast key={id} {...props}>
            <div className="grid gap-1">
              {title && <ToastTitle>{title}</ToastTitle>}
              {description && (
                <ToastDescription>{description}</ToastDescription>
              )}
            </div>
            {action}
            <ToastClose />
          </Toast>
        );
      })}
      <ToastViewport />
    </ToastProvider>
  );
}

```

### /vercel/path0/examples/music-player/src/components/ui/tooltip.tsx

```ts
"use client";

import * as TooltipPrimitive from "@radix-ui/react-tooltip";
import * as React from "react";

import { cn } from "@/lib/utils";

const TooltipProvider = TooltipPrimitive.Provider;

const Tooltip = TooltipPrimitive.Root;

const TooltipTrigger = TooltipPrimitive.Trigger;

const TooltipContent = React.forwardRef<
  React.ElementRef<typeof TooltipPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
>(({ className, sideOffset = 4, ...props }, ref) => (
  <TooltipPrimitive.Content
    ref={ref}
    sideOffset={sideOffset}
    className={cn(
      "z-50 overflow-hidden rounded-md border bg-popover px-3 py-1.5 text-sm text-popover-foreground shadow-md animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
      className,
    )}
    {...props}
  />
));
TooltipContent.displayName = TooltipPrimitive.Content.displayName;

export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };

```

### /vercel/path0/examples/music-player/src/hooks/use-toast.ts

```ts
import * as React from "react";

import type { ToastActionElement, ToastProps } from "@/components/ui/toast";

const TOAST_LIMIT = 1;
const TOAST_REMOVE_DELAY = 1000000;

type ToasterToast = ToastProps & {
  id: string;
  title?: React.ReactNode;
  description?: React.ReactNode;
  action?: ToastActionElement;
};

const actionTypes = {
  ADD_TOAST: "ADD_TOAST",
  UPDATE_TOAST: "UPDATE_TOAST",
  DISMISS_TOAST: "DISMISS_TOAST",
  REMOVE_TOAST: "REMOVE_TOAST",
} as const;

let count = 0;

function genId() {
  count = (count + 1) % Number.MAX_SAFE_INTEGER;
  return count.toString();
}

type ActionType = typeof actionTypes;

type Action =
  | {
      type: ActionType["ADD_TOAST"];
      toast: ToasterToast;
    }
  | {
      type: ActionType["UPDATE_TOAST"];
      toast: Partial<ToasterToast>;
    }
  | {
      type: ActionType["DISMISS_TOAST"];
      toastId?: ToasterToast["id"];
    }
  | {
      type: ActionType["REMOVE_TOAST"];
      toastId?: ToasterToast["id"];
    };

interface State {
  toasts: ToasterToast[];
}

const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>();

const addToRemoveQueue = (toastId: string) => {
  if (toastTimeouts.has(toastId)) {
    return;
  }

const timeout = setTimeout(() => {
    toastTimeouts.delete(toastId);
    dispatch({
      type: "REMOVE_TOAST",
      toastId: toastId,
    });
  }, TOAST_REMOVE_DELAY);

toastTimeouts.set(toastId, timeout);
};

export const reducer = (state: State, action: Action): State => {
  switch (action.type) {
    case "ADD_TOAST":
      return {
        ...state,
        toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
      };

case "UPDATE_TOAST":
      return {
        ...state,
        toasts: state.toasts.map((t) =>
          t.id === action.toast.id ? { ...t, ...action.toast } : t,
        ),
      };

case "DISMISS_TOAST": {
      const { toastId } = action;

// ! Side effects ! - This could be extracted into a dismissToast() action,
      // but I'll keep it here for simplicity
      if (toastId) {
        addToRemoveQueue(toastId);
      } else {
        state.toasts.forEach((toast) => {
          addToRemoveQueue(toast.id);
        });
      }

return {
        ...state,
        toasts: state.toasts.map((t) =>
          t.id === toastId || toastId === undefined
            ? {
                ...t,
                open: false,
              }
            : t,
        ),
      };
    }
    case "REMOVE_TOAST":
      if (action.toastId === undefined) {
        return {
          ...state,
          toasts: [],
        };
      }
      return {
        ...state,
        toasts: state.toasts.filter((t) => t.id !== action.toastId),
      };
  }
};

const listeners: Array<(state: State) => void> = [];

let memoryState: State = { toasts: [] };

function dispatch(action: Action) {
  memoryState = reducer(memoryState, action);
  listeners.forEach((listener) => {
    listener(memoryState);
  });
}

type Toast = Omit<ToasterToast, "id">;

function toast({ ...props }: Toast) {
  const id = genId();

const update = (props: ToasterToast) =>
    dispatch({
      type: "UPDATE_TOAST",
      toast: { ...props, id },
    });
  const dismiss = () => dispatch({ type: "DISMISS_TOAST", toastId: id });

dispatch({
    type: "ADD_TOAST",
    toast: {
      ...props,
      id,
      open: true,
      onOpenChange: (open) => {
        if (!open) dismiss();
      },
    },
  });

return {
    id: id,
    dismiss,
    update,
  };
}

function useToast() {
  const [state, setState] = React.useState<State>(memoryState);

React.useEffect(() => {
    listeners.push(setState);
    return () => {
      const index = listeners.indexOf(setState);
      if (index > -1) {
        listeners.splice(index, 1);
      }
    };
  }, [state]);

return {
    ...state,
    toast,
    dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
  };
}

export { useToast, toast };

```

### /vercel/path0/examples/music-player/src/index.css

```ts
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 20 14.3% 4.1%;

--card: 0 0% 100%;
    --card-foreground: 20 14.3% 4.1%;

--popover: 0 0% 100%;
    --popover-foreground: 20 14.3% 4.1%;

--primary: 24 9.8% 10%;
    --primary-foreground: 60 9.1% 97.8%;

--secondary: 60 4.8% 95.9%;
    --secondary-foreground: 24 9.8% 10%;

--muted: 60 4.8% 95.9%;
    --muted-foreground: 25 5.3% 44.7%;

--accent: 60 4.8% 95.9%;
    --accent-foreground: 24 9.8% 10%;

--destructive: 0 84.2% 60.2%;
    --destructive-foreground: 60 9.1% 97.8%;

--border: 20 5.9% 90%;
    --input: 20 5.9% 90%;
    --ring: 20 14.3% 4.1%;

--radius: 0.5rem;
  }

.dark {
    --background: 20 14.3% 4.1%;
    --foreground: 60 9.1% 97.8%;

--card: 20 14.3% 4.1%;
    --card-foreground: 60 9.1% 97.8%;

--popover: 20 14.3% 4.1%;
    --popover-foreground: 60 9.1% 97.8%;

--primary: 60 9.1% 97.8%;
    --primary-foreground: 24 9.8% 10%;

--secondary: 12 6.5% 15.1%;
    --secondary-foreground: 60 9.1% 97.8%;

--muted: 12 6.5% 15.1%;
    --muted-foreground: 24 5.4% 63.9%;

--accent: 12 6.5% 15.1%;
    --accent-foreground: 60 9.1% 97.8%;

--destructive: 0 62.8% 30.6%;
    --destructive-foreground: 60 9.1% 97.8%;

--border: 12 6.5% 15.1%;
    --input: 12 6.5% 15.1%;
    --ring: 24 5.7% 82.9%;
  }
}

@layer base {
  * {
    @apply border-border;
  }
  body {
    @apply bg-background text-foreground;
  }
}

```

### /vercel/path0/examples/music-player/src/lib/audio/AudioManager.ts

```ts
import { createContext, useContext } from "react";

export class AudioManager {
  mediaElement: HTMLAudioElement;

audioObjectURL: string | null = null;

constructor() {
    const mediaElement = new Audio();

this.mediaElement = mediaElement;
  }

async unloadCurrentAudio() {
    if (this.audioObjectURL) {
      URL.revokeObjectURL(this.audioObjectURL);
      this.audioObjectURL = null;
    }
  }

async loadAudio(file: Blob) {
    await this.unloadCurrentAudio();

const { mediaElement } = this;
    const audioObjectURL = URL.createObjectURL(file);

this.audioObjectURL = audioObjectURL;

mediaElement.src = audioObjectURL;
  }

play() {
    if (this.mediaElement.ended) {
      this.mediaElement.fastSeek(0);
    }

this.mediaElement.play();
  }

pause() {
    this.mediaElement.pause();
  }

destroy() {
    this.unloadCurrentAudio();
    this.mediaElement.pause();
  }
}

const context = createContext<AudioManager>(new AudioManager());

export function useAudioManager() {
  return useContext(context);
}

export const AudionManagerProvider = context.Provider;

```

### /vercel/path0/examples/music-player/src/lib/audio/getAudioFileData.ts

```ts
export async function getAudioFileData(file: Blob, samples = 200) {
  const ctx = new AudioContext();

const buffer = await file.arrayBuffer();
  const decodedAudio = await ctx.decodeAudioData(buffer);

return {
    waveform: transformDecodedAudioToWaveformData(decodedAudio, samples),
    duration: decodedAudio.duration,
  };
}

const transformDecodedAudioToWaveformData = (
  audioBuffer: AudioBuffer,
  samples: number,
) => {
  const rawData = audioBuffer.getChannelData(0); // We only need to work with one channel of data
  const blockSize = Math.floor(rawData.length / samples); // the number of samples in each subdivision

const sampledData: number[] = new Array(samples);
  let max = 0;

for (let i = 0; i < samples; i++) {
    const blockStart = blockSize * i; // the location of the first sample in the block
    let sum = 0;
    for (let j = 0; j < blockSize; j++) {
      sum = sum + Math.abs(rawData[blockStart + j]); // find the sum of all the samples in the block
    }
    const sampledValue = sum / blockSize; // divide the sum by the block size to get the average

if (max < sampledValue) {
      max = sampledValue;
    }

sampledData[i] = sampledValue;
  }

const multiplier = max ** -1;

for (let i = 0; i < samples; i++) {
    sampledData[i] = sampledData[i] * multiplier;
  }

return sampledData;
};

```

### /vercel/path0/examples/music-player/src/lib/audio/useMediaEndListener.ts

```ts
import { useEffect } from "react";
import { useAudioManager } from "./AudioManager";

export function useMediaEndListener(callback: () => void) {
  const audioManager = useAudioManager();

useEffect(() => {
    audioManager.mediaElement.addEventListener("ended", callback);

return () => {
      audioManager.mediaElement.removeEventListener("ended", callback);
    };
  }, [audioManager, callback]);
}

```

### /vercel/path0/examples/music-player/src/lib/audio/usePlayMedia.ts

```ts
import { useRef } from "react";
import { useAudioManager } from "./AudioManager";

export function usePlayMedia() {
  const audioManager = useAudioManager();

const previousMediaLoad = useRef<Promise<unknown>>();

async function playMedia(file: Blob) {
    // Wait for the previous load to finish
    // to avoid to incur into concurrency issues
    await previousMediaLoad.current;

const promise = audioManager.loadAudio(file);

previousMediaLoad.current = promise;

await promise;

audioManager.play();
  }

return playMedia;
}

```

### /vercel/path0/examples/music-player/src/lib/audio/usePlayState.ts

```ts
import { useLayoutEffect, useState } from "react";
import { useAudioManager } from "./AudioManager";

export type PlayState = "pause" | "play";

export function usePlayState() {
  const audioManager = useAudioManager();
  const [value, setValue] = useState<PlayState>("pause");

useLayoutEffect(() => {
    setValue(audioManager.mediaElement.paused ? "pause" : "play");

const onPlay = () => {
      setValue("play");
    };

const onPause = () => {
      setValue("pause");
    };

audioManager.mediaElement.addEventListener("play", onPlay);
    audioManager.mediaElement.addEventListener("pause", onPause);

return () => {
      audioManager.mediaElement.removeEventListener("play", onPlay);
      audioManager.mediaElement.removeEventListener("pause", onPause);
    };
  }, [audioManager]);

function togglePlayState() {
    if (value === "pause") {
      audioManager.play();
    } else {
      audioManager.pause();
    }
  }

return { value, toggle: togglePlayState };
}

```

### /vercel/path0/examples/music-player/src/lib/audio/usePlayerCurrentTime.ts

```ts
import { useLayoutEffect, useState } from "react";
import { useAudioManager } from "./AudioManager";

export function usePlayerCurrentTime() {
  const audioManager = useAudioManager();
  const [value, setValue] = useState<number>(0);

useLayoutEffect(() => {
    setValue(audioManager.mediaElement.currentTime);

const onTimeUpdate = () => {
      setValue(audioManager.mediaElement.currentTime);
    };

audioManager.mediaElement.addEventListener("timeupdate", onTimeUpdate);

return () => {
      audioManager.mediaElement.removeEventListener("timeupdate", onTimeUpdate);
    };
  }, [audioManager]);

function setCurrentTime(time: number) {
    if (audioManager.mediaElement.paused) audioManager.play();

// eslint-disable-next-line react-compiler/react-compiler
    audioManager.mediaElement.currentTime = time;
  }

return {
    value,
    setValue: setCurrentTime,
  };
}

```

### /vercel/path0/examples/music-player/src/lib/getters.ts

```ts
import { MusicaAccount } from "../1_schema";

export async function getNextTrack() {
  const me = await MusicaAccount.getMe().ensureLoaded({
    resolve: {
      root: {
        activePlaylist: {
          tracks: true,
        },
      },
    },
  });

const tracks = me.root.activePlaylist.tracks;
  const activeTrack = me.root._refs.activeTrack;

const currentIndex = tracks.findIndex((item) => item?.id === activeTrack.id);

const nextIndex = (currentIndex + 1) % tracks.length;

return tracks[nextIndex];
}

export async function getPrevTrack() {
  const me = await MusicaAccount.getMe().ensureLoaded({
    resolve: {
      root: {
        activePlaylist: {
          tracks: true,
        },
      },
    },
  });

const tracks = me.root.activePlaylist.tracks;
  const activeTrack = me.root._refs.activeTrack;

const currentIndex = tracks.findIndex((item) => item?.id === activeTrack.id);

const previousIndex = (currentIndex - 1 + tracks.length) % tracks.length;
  return tracks[previousIndex];
}

```

### /vercel/path0/examples/music-player/src/lib/useKeyboardListener.ts

```ts
import { useEffect } from "react";

export function useKeyboardListener(code: string, callback: () => void) {
  useEffect(() => {
    const handler = (evt: KeyboardEvent) => {
      if (evt.code === code) {
        callback();
      }
    };
    window.addEventListener("keyup", handler);

return () => {
      window.removeEventListener("keyup", handler);
    };
  }, [callback, code]);
}

```

### /vercel/path0/examples/music-player/src/lib/useUploadExampleData.ts

```ts
import { MusicaAccount } from "@/1_schema";
import { useAccount } from "jazz-react";
import { useEffect } from "react";
import { uploadMusicTracks } from "../4_actions";

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

useEffect(() => {
    uploadOnboardingData();
  }, [me.id]);
}

async function uploadOnboardingData() {
  const me = await MusicaAccount.getMe().ensureLoaded({
    resolve: { root: true },
  });

if (me.root.exampleDataLoaded) return;

me.root.exampleDataLoaded = true;

try {
    const trackFile = await (await fetch("/example.mp3")).blob();

await uploadMusicTracks([new File([trackFile], "Example song")], true);
  } catch (error) {
    me.root.exampleDataLoaded = false;
    throw error;
  }
}

```

### /vercel/path0/examples/music-player/src/lib/utils.ts

```ts
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

```

### /vercel/path0/examples/music-player/src/vite-env.d.ts

```ts
/// <reference types="vite/client" />

```

{issue.title}

Buy terrarium