jazz-ui-development（爵士乐用户界面开发）

Jazz UI Development

When to Use This Skill

• Building user interfaces that display or interact with Jazz data
• Setting up authentication providers and contexts
• Debugging reactivity, data loading, or sync issues in the UI
• Optimizing performance of data subscriptions
• Handling media (images, files) in the UI

Do NOT Use This Skill For

• Defining data schemas (use jazz-schema-design)
• Complex permission logic or sharing workflows (use jazz-permissions-security)
• Testing questions (use jazz-testing)

Key Heuristic for Agents

Use this skill when the user asks about rendering data, handling user input, managing authentication state, or framework-specific integration (React, Svelte, etc.). If the issue is "data not appearing" but permissions are correct, look here for loading and subscription patterns.

Framework Guides

Select the guide for your specific framework:

• React: React Reference
• React Native (Bare): As well as the React guide, also see React Native Reference
• React Native (Expo): As well as the React guide, also seeReact Native (Expo) Reference
• Svelte: Svelte Reference
• Vanilla JS: Vanilla JS Reference

Universal CoValue API

These APIs are available on all CoValue instances, regardless of the framework.

Core Properties

All CoValues (CoMaps, CoLists, etc.) have these properties directly on the instance:

• $isLoaded (boolean): Returns true if the CoValue is fully loaded and ready to read.
• .toJSON(): Returns a plain JavaScript object representation of the CoValue. Use this for debugging only, not for rendering.

The .$jazz Namespace

Every CoValue instance has a .$jazz property containing metadata and utility methods.

Metadata

• .$jazz.id (ID<CoValue>): The globally unique ID of the CoValue (e.g., co_zXy...).
• .$jazz.owner (Group): The Group that owns this CoValue. Access control is determined by membership in this group.
• .$jazz.createdAt (number): Creation timestamp (ms since epoch).
• .$jazz.createdBy (ID<Account> | undefined): ID of the creating account.
• .$jazz.lastUpdatedAt (number): Last update timestamp (ms since epoch).

Loading & Inspection

• .$jazz.loadingState ("loading" | "loaded" | "unavailable" | "unauthorized"): The current loading state.
• .$jazz.ensureLoaded({resolve: {...}}): Waits for nested references to load. Returns a promise with a new instance where requested fields are guaranteed available.

const detailedPost = await post.$jazz.ensureLoaded({
  resolve: {
    comments: {
      $each: {
        author: true
      }
    }
  }
});

• .$jazz.refs (CoMap/CoRecord only): Access nested CoValues as references (with IDs) without loading them.
• .$jazz.has(key) (CoMap/CoRecord only): Checks if a key exists.

Subscription & Sync

• .$jazz.subscribe(callback): Manually subscribe to changes. Returns an unsubscribe function. Prefer framework-specific hooks (e.g., useCoState) over this.
• .$jazz.waitForSync(): Promise that resolves when changes are synced to peers. Useful for critical saves or logout flows.

Version Control

• .$jazz.isBranched (boolean): Whether the CoValue is currently in a local branch.
• .$jazz.branchName (string): The name of the current branch.
• .$jazz.unstable_merge(): Merges a branch back into the main history.

Working with Data Types

CoMap / CoRecord

• Read: Access properties like a standard JS object (e.g., user.name).
• Write:

- .$jazz.set(key, value) - .$jazz.delete(key) - .$jazz.applyDiff(diff)

CoList

• Read: Access by index (list[0]), iterate (map, forEach).
• Write:

- .$jazz.push(item) - .$jazz.unshift(item) - .$jazz.splice(...) - .$jazz.remove(index or predicate)

CoText (CoPlainText / CoRichText)

• Read: toString() or use directly in template.
• Write:

- insertAfter(index, text) - deleteRange({from, to}) - .$jazz.applyDiff(newText)

CoFeed

• Read: Iterate over feed.all (returns per-session feeds).
• Write: .$jazz.push(item) (Append-only).

// Subscribing to all entries across all accounts
const allEntries = Object.values(feed.perAccount).flatMap(accountFeed => Array.from(accountFeed.all));

// Pushing a new entry
feed.$jazz.push({ message: "Hello", timestamp: Date.now() });

DiscriminatedUnion

• Read: Check the discriminator property (e.g. type) to narrow the type.
• Write: Overwrite the property with a new object of the desired variant.

const list = co.list(MyUnion);
const item = list[0];

if (item.type === "text") {
  console.log(item.value); // item is narrowed to TextVariant
} else if (item.type === "image") {
  console.log(item.image.$jazz.id); // item is narrowed to ImageVariant
}

FileStream

• Read: Use toBlob() or consume chunks.
• Write: Use createFromBlob(blobOrFile) or start(metadata) -> push(chunk) -> end().

ImageDefinition

• Read: Use <Image> component (framework specific) or loadImageBySize.
• Write: use the createImage function from jazz-tools/media

<Image imageId={productImage.$jazz.id} width={300} />

Troubleshooting

"Data not appearing" or "Value is undefined"

1. Check $isLoaded: Ensure you are checking if (coValue.$isLoaded) before rendering.
2. Deep Loading: If nested data is missing, use resolve in your hook (e.g. useCoState(..., {resolve: {items: true}})).
3. Provider Check: Ensure the component is wrapped in the appropriate <JazzProvider />.

"Infinite re-render loops"

1. Selector Stability: Ensure your select function in useCoState is stable or returns stable references.
2. Expensive Selectors: Move computations to useMemo instead of doing them inside the select function.
3. Equality Function: Use equalityFn to prevent unnecessary updates if the selected data hasn't changed semantically.

"Reactivity not triggering"

1. Direct Mutations: Ensure you are using .$jazz.set() or .$jazz.push() instead of direct property assignment (e.g. obj.key = val won't sync).
2. Deep Updates: Remember that updating a nested scalar doesn't trigger a change in the parent CoValue unless that parent property is replaced.