velt-live-state-sync-best-practices

Files (18)

• AGENTS.full.md
• AGENTS.md
• SKILL.md
• metadata.json
• api-broadcast.md · rules/shared/api/
• api-data-models.md · rules/shared/api/
• core-auth-provider.md · rules/shared/core/
• core-setup-overview.md · rules/shared/core/
• element-connection.md · rules/shared/element/
• element-fetch.md · rules/shared/element/
• element-get-set.md · rules/shared/element/
• hooks-connection-state.md · rules/shared/hooks/
• hooks-set-get-data.md · rules/shared/hooks/
• hooks-use-live-state.md · rules/shared/hooks/
• patterns-best-practices.md · rules/shared/patterns/
• redux-action-structure.md · rules/shared/redux/
• redux-dynamic-id.md · rules/shared/redux/
• redux-middleware-setup.md · rules/shared/redux/

SKILL.md (first lines)

# Velt Live State Sync Best Practices

Comprehensive guide for implementing Velt's Live State Sync API — real-time shared state across clients with sub-10ms latency, offline support, and Redux middleware integration. Contains 14 rules across 6 categories.

## When to Apply

Reference these guidelines when:
- Adding real-time shared state (counters, selections, cursors, tool modes) to a collaborative app
- Using `useLiveState` for useState-like shared state
- Using `useSetLiveStateData` / `useLiveStateData` for separated read/write patterns
- Working with the `LiveStateSyncElement` for observable subscriptions or promise-based fetches
- Integrating Redux with `createLiveStateMiddleware` for full store sync
- Broadcasting state updates from your server via the REST API
- Monitoring connection state for offline/online indicators

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Core | CRITICAL | `core-` |
| 2 | Hooks | CRITICAL | `hooks-` |
| 3 | Element | HIGH | `element-` |
| 4 | Redux | HIGH | `redux-` |
| 5 | API | MEDIUM | `api-` |
| 6 | Patterns | MEDIUM | `patterns-` |

## Prerequisites

Live State Sync requires `VeltProvider` with `authProvider` wrapping your app and a `documentId` set to scope state. No additional packages beyond `@veltdev/react` are needed.

## Compiled Documents

- `AGENTS.md` — Compressed index of all rules with file paths (start here)
- `AGENTS.full.md` — Full verbose guide with all rules expanded inline

From velt-js/velt-plugin-cursor, MIT.