Scaffold Stratasync

Scaffold a Strata Sync App

Generates a runnable local-first app: a Next.js client and a standalone Fastify API with PostgreSQL, converging over a server-sequenced log.

• IS: creating a new Strata Sync project from nothing, or adding the full client and server sync layer to an existing Next.js app.
• IS NOT: changing an app that already syncs (use the stratasync skill), general Next.js scaffolding (use scaffold-nextjs), or deployment.

Strata Sync is a clean-room implementation of the architecture Linear published; it contains no Linear code. The reverse-engineering notes are the reference for the concepts named here.

Reference files

Variables

Workflow

Phase 1: Gather info

• Ask for project name (default: my-stratasync-app)
• Ask for primary model name (default: Todo)
• Ask for model fields beyond defaults (id, groupId, createdAt)
• If user says "just defaults" or gives no specifics, use Todo with title: string and completed: boolean
• Derive MODEL_NAME_LOWER and MODEL_TABLE from MODEL_NAME

Phase 2: Scaffold Next.js client

• Detect if inside an existing Next.js project (check for next.config.*)
• If no existing project: run npx create-next-app@latest {{PROJECT_NAME}} --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" with --use-npm
• Install client dependencies per references/client-setup.md § Dependencies
• Merge tsconfig changes per references/client-setup.md § tsconfig. experimentalDecorators: true is CRITICAL.
• Write next.config.ts per references/client-setup.md § next.config. transpilePackages is CRITICAL.

Phase 3: Scaffold server

• Create server/ directory alongside the client
• Write all server files per references/server-setup.md:
  • server/package.json
  • server/tsconfig.json
  • server/docker-compose.yml
  • server/.env.example
  • server/.env (copy from .env.example)
  • server/drizzle.config.ts
  • server/src/db/schema.ts
  • server/src/config.ts
  • server/src/server.ts
• Run cd server && npm install

Phase 4: Scaffold client sync layer

Write all client sync files per references/client-setup.md:

• src/lib/sync/models/{{MODEL_NAME_LOWER}}.ts: Model class with decorators
• src/lib/sync/models.ts: Barrel with side-effect import (CRITICAL: decorator registration)
• src/lib/sync/config.ts: API URL, dev tokens
• src/lib/sync/create-client.ts: Client factory (singleton)
• src/app/providers.tsx: NextSyncProvider wrapper
• src/app/layout.tsx: Wrap children with <Providers>

Phase 5: Scaffold example page

• Write src/app/page.tsx per references/client-setup.md § Example page
• Includes: create form, toggle, delete, sync status display
• Uses useQuery, useSyncClient, useConnectionState, observer, and instance .save() / .delete() methods
• All components marked "use client"

Phase 6: Start and verify

• cd server && docker compose up -d: Start PostgreSQL
• cd server && npm run db:push: Create database tables
• cd server && npm run dev: Start API server (port {{API_PORT}})
• In a new terminal: npm run dev: Start Next.js (port {{WEB_PORT}})
• Verify: open http://localhost:{{WEB_PORT}}, create a todo, confirm it persists across refresh
• Verify: open a second tab, confirm real-time sync via WebSocket

Anti-patterns

• Never omit experimentalDecorators: true from tsconfig. Decorators fail silently.
• Never omit transpilePackages from next.config. ESM imports break at runtime.
• Never forget side-effect model imports in the barrel file. Schema will be empty, no data syncs.
• Never install @stratasync/server in the client app. It is server-only.
• Never import @stratasync/next directly in client components. Use @stratasync/next/client.
• Never omit "use client" on components that use hooks
• Never use React.forwardRef. React 19+ passes ref as prop.

Skill handoffs