davenov:cc:expert-evolu-nextjs

<quick_start> Install packages: npm install @evolu/common @evolu/react @evolu/react-web

Enable TypeScript strict mode and exactOptionalPropertyTypes. Define schema with branded types using id() and NonEmptyString. Create Evolu instance and wrap app with EvoluProvider. Use useQuery for reactive data and create/update for mutations. </quick_start>

<success_criteria>

• TypeScript compiles with strict mode enabled
• Schema uses branded ID types for all tables
• Queries filter soft-deleted rows with where("isDeleted", "is not", evolu.sqliteTrue)
• All Evolu code is in Client Components with “use client” directive
• EvoluProvider and Suspense boundaries are properly configured
• Mutations validate input with .from() before executing
• Mnemonic backup is available for data recovery </success_criteria>

1. Set up Evolu in a new Next.js project
2. Add features to existing Evolu app
3. Debug sync, encryption, or hydration issues
4. Understand Evolu concepts (schemas, queries, mutations)

Wait for response before proceeding.

Packages: @evolu/common, @evolu/react, @evolu/react-web

Quick install:

npm install @evolu/common @evolu/react @evolu/react-web

See: [references/installation.md] for platform variants (React Native, Expo, Svelte) and full TypeScript configuration.

Key patterns:

• id("TableName") – branded ID types prevent mixing IDs across tables
• NonEmptyString + maxLength() – validated strings
• nullOr() – optional fields (Evolu uses null, not undefined)
• SqliteBoolean – booleans stored as 0/1

See: [references/schema-definition.md] for complete examples and automatic system columns.

Key files:

• lib/evolu.ts – Schema, instance creation, typed hooks
• app/providers.tsx – EvoluProvider + Suspense wrapper
• app/layout.tsx – Import providers

Important: All Evolu code must be in Client Components ("use client").

See: [references/instance-setup.md] for complete setup code.

Key patterns:

const todosQuery = evolu.createQuery((db) =>
  db.selectFrom("todo")
    .select(["id", "title", "isCompleted"])
    .where("isDeleted", "is not", evolu.sqliteTrue)
    .orderBy("createdAt", "desc")
);

const { rows } = useQuery(todosQuery);

Always filter: .where("isDeleted", "is not", evolu.sqliteTrue)

See: [references/queries.md] for relationships, conditional queries, and useQueries for parallel loading.

Key rules:

• Create: create(tableName, data) – ID auto-generated
• Update: update(tableName, { id, ...changes }) – ID required
• Delete: Soft delete with isDeleted: evolu.sqliteTrue
• Validate: Always use .from() before mutations

See: [references/mutations.md] for complete CRUD examples and batch operations.

Key operations:

• getMnemonic() – Get 12-word recovery phrase (handle securely!)
• restoreAppOwner(mnemonic) – Restore on new device
• resetAppOwner() – Delete all local data (irreversible)
• exportDatabase() – Export for backup

Security: Mnemonic = master key to ALL encrypted data. Never log in production.

See: [references/owner-management.md] for complete examples and security checklist.

Architecture:

• Server Components can render Client Components that use Evolu
• Evolu runs entirely client-side (local-first)
• Use Suspense for loading states
• Consider next/dynamic with ssr: false if hydration issues occur

See: [references/nextjs-integration.md] for complete setup and hydration troubleshooting.

<error_handling> Evolu handles offline automatically. For persistent issues: check sync URL, verify mnemonic, check WebSocket errors in console.

See: [references/troubleshooting.md] for detailed solutions. </error_handling>

<security_checklist>

• NEVER log mnemonic to console in production
• Store mnemonic in secure password manager
• Warn users before displaying mnemonic
• Remember: mnemonic = master key to ALL encrypted data </security_checklist>

1. TypeScript compiles: npx tsc --noEmit
2. Schema valid: All tables have branded ID types
3. Validation used: .from() before mutations
4. Soft delete filtered: Queries filter isDeleted rows
5. Client Component: All Evolu code has "use client"
6. Suspense wrapped: Components using useQuery have boundary
7. App builds: npm run build