feat: add fullstack-vercel-turso example

.gitignore

@@ -12,4 +12,6 @@ website/.vitepress/cache/
 website/.vitepress/dist/
 
 # test coverage
-coverage
+coverage
+.vercel
+.env*.local

CLAUDE.md

@@ -77,6 +77,19 @@ pnpm --filter @coji/durably test:node:all        # Run all Node tests (SQLite +
 pnpm db:down                                     # Stop Postgres
 ```
 
+## Codex CLI for Research & Consultation
+
+When stuck or needing up-to-date information about external services, use Codex CLI (`codex exec`) to consult GPT. Codex can perform web searches, making it especially useful for real-time information like Vercel configuration, latest library APIs, or deployment troubleshooting.
+
+```bash
+codex exec "your question or prompt here"
+```
+
+- Run in the background and check results later for non-blocking workflow
+- Include relevant codebase context in the prompt for better answers
+- Useful for research, design consultation, and debugging — not just search
+- **During `/review` and `/simplify`**: Run `codex exec` in parallel with the review agents to get a second opinion on the diff. Pass the diff content and ask for code quality feedback, potential issues, or improvement suggestions
+
 ## Skills
 
 - **release-check** - Pre-release integrity check for API changes and spec updates (`.claude/skills/release-check/`)

examples/fullstack-vercel-turso/.env.example

@@ -0,0 +1,7 @@
+# Local development (libsqld via Docker)
+TURSO_DATABASE_URL=http://localhost:8080
+
+# Production (Turso)
+# TURSO_DATABASE_URL=libsql://your-db-name.turso.io
+# TURSO_AUTH_TOKEN=your-token
+# CRON_SECRET=your-secret

examples/fullstack-vercel-turso/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.env
+/node_modules/
+
+# React Router
+/.react-router/
+/build/
+
+*.swp
+.vercel
+.env*.local

examples/fullstack-vercel-turso/.vercelignore

@@ -0,0 +1,13 @@
+# Exclude sibling examples to prevent @vercel/react-router builder
+# from scanning other React Router apps in the monorepo
+../../examples/fullstack-react-router
+../../examples/spa-vite-react
+../../examples/spa-react-router
+../../examples/server-node
+
+# Exclude non-essential workspace packages
+../../website
+
+# Exclude tests and docs
+../../packages/durably/tests
+../../packages/durably-react/tests

examples/fullstack-vercel-turso/README.md

@@ -0,0 +1,78 @@
+# Fullstack Vercel + Turso Example
+
+Durably fullstack demo deployed on Vercel with Turso (libSQL) as the database.
+
+> **Note**: This is a demo app with no authentication on the Durably control plane.
+> For production use, add authentication via `createDurablyHandler({ authenticate })`.
+> See the [auth guide](../../website/guide/auth.md) for details.
+
+## Architecture
+
+- **Framework**: React Router v7 with `@vercel/react-router` preset
+- **Database**: Turso (remote libSQL) in production, local libsqld via Docker in development
+- **Worker**: Dual-mode
+  - **Real-time**: `onRequest` lazily starts the worker — runs during SSE streaming
+  - **Background**: `/api/worker` endpoint called by Vercel Cron (requires Pro plan for per-minute schedule)
+
+## How it works
+
+```text
+User triggers job → POST /api/durably/trigger
+                  ↓
+User subscribes   → GET /api/durably/subscribe?runId=xxx (SSE)
+                  ↓
+onRequest         → durably.init() starts worker during SSE connection
+                  ↓
+Worker processes  → steps stream via SSE in real-time
+                  ↓
+SSE disconnects   → function terminates, worker stops
+                  ↓
+Vercel Cron       → GET /api/worker processes any remaining pending jobs
+```
+
+## Setup
+
+### Local development
+
+Requires Docker for the local libsqld instance.
+
+```bash
+cp .env.example .env
+pnpm install
+pnpm dev
+```
+
+This starts a local libsqld container (Docker) and the dev server.
+The app connects to `http://localhost:8080` — same HTTP protocol as production Turso.
+
+### Production (Vercel + Turso)
+
+1. Create a Turso database:
+
+   ```bash
+   turso db create my-durably-app
+   turso db tokens create my-durably-app
+   ```
+
+2. Set environment variables in Vercel:
+   - `TURSO_DATABASE_URL` — `libsql://my-durably-app-<user>.turso.io`
+   - `TURSO_AUTH_TOKEN` — token from step 1
+   - `CRON_SECRET` — any random string to authenticate cron requests
+
+3. Deploy:
+   ```bash
+   vercel
+   ```
+
+## Key files
+
+| File                          | Description                                 |
+| ----------------------------- | ------------------------------------------- |
+| `docker-compose.yml`          | Local libsqld for development               |
+| `app/lib/database.server.ts`  | Turso/libSQL connection config              |
+| `app/lib/durably.server.ts`   | Durably instance with `onRequest` lazy init |
+| `app/lib/durably.ts`          | Type-safe client for React components       |
+| `app/routes/api.durably.$.ts` | Durably HTTP/SSE handler (splat route)      |
+| `app/routes/api.worker.ts`    | Background worker endpoint for Vercel Cron  |
+| `vercel.json`                 | Cron schedule (per-minute requires Pro)     |
+| `react-router.config.ts`      | Vercel preset configuration                 |

examples/fullstack-vercel-turso/app/app.css

@@ -0,0 +1,12 @@
+@import 'tailwindcss';
+
+@theme {
+  --font-sans:
+    'Inter', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
+    'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+}
+
+html,
+body {
+  @apply bg-gray-50;
+}

examples/fullstack-vercel-turso/app/jobs/data-sync.ts

@@ -0,0 +1,55 @@
+/**
+ * Data Sync Job
+ *
+ * Simulates syncing data with a remote server.
+ */
+
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+import { delay } from './delay'
+
+export const dataSyncJob = defineJob({
+  name: 'data-sync',
+  input: z.object({ userId: z.string() }),
+  output: z.object({ synced: z.number(), failed: z.number() }),
+  run: async (step, input) => {
+    step.log.info(`Starting sync for user: ${input.userId}`)
+
+    const items = await step.run('fetch-local', async () => {
+      step.progress(1, 4, 'Fetching local data...')
+      await delay(300)
+      return Array.from({ length: 10 }, (_, i) => ({
+        id: `item-${i}`,
+        data: `Data for ${input.userId}`,
+      }))
+    })
+
+    let synced = 0
+    let failed = 0
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i]
+      const success = await step.run(`sync-item-${item.id}`, async () => {
+        step.progress(2 + Math.floor(i / 5), 4, `Syncing item ${i + 1}...`)
+        await delay(100)
+        return Math.random() > 0.1 // 90% success rate
+      })
+
+      if (success) {
+        synced++
+      } else {
+        failed++
+        step.log.warn(`Failed to sync item: ${item.id}`)
+      }
+    }
+
+    await step.run('finalize', async () => {
+      step.progress(4, 4, 'Finalizing...')
+      await delay(200)
+    })
+
+    step.log.info(`Sync complete: ${synced} synced, ${failed} failed`)
+
+    return { synced, failed }
+  },
+})

examples/fullstack-vercel-turso/app/jobs/delay.ts

@@ -0,0 +1 @@
+export const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))