@korajs/cli 0.0.0-canary-20261008174129

package/templates/react-tailwind/AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this project. Humans: this is useful for you too.
+
+## What this project is
+
+This is a **Kora.js** application: an offline-first app where all data lives in a local SQLite database (WASM + OPFS in the browser) and optionally syncs across devices through a Kora sync server. Offline is the normal state, not an error state. Full docs: https://korajs.dev and machine-readable index at https://korajs.dev/llms.txt (complete docs in one file: https://korajs.dev/llms-full.txt).
+
+## Golden rules
+
+1. **The schema is the source of truth.** All collections are defined in `src/schema.ts` with `defineSchema` and the `t.*` field builders. To add or change data shapes, edit the schema first; types flow from it automatically. Never hand-write types for records.
+2. **Never fetch application data over HTTP.** Do not add REST or GraphQL calls for app data, and do not talk to the sync server directly. Read and write through Kora collections only; sync happens automatically in the background.
+3. **Await readiness before direct collection access.** Outside the UI bindings, `await app.ready` before calling `app.<collection>` methods. The bindings handle this for you inside components.
+4. **Offline must keep working.** Any feature you add must function with the network off. Never gate a write or a read on connectivity. If you find yourself checking `navigator.onLine` before a data operation, you are doing it wrong.
+5. **Surface mutation errors.** Fire-and-forget mutate calls put errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
+6. **Do not touch `src/kora-worker.ts`.** It wires the SQLite WASM binary URL for both dev and production builds. Changing it breaks production builds in ways that only show up after deploy.
+7. **Do not add a state management library for server or app data.** Kora's reactive queries are the store. Local UI state (form inputs, toggles) can use the framework's normal state tools.
+
+## Data API cheat sheet
+
+```ts
+await app.ready
+const rec = await app.todos.insert({ title: 'x' })   // defaults and .auto() fields applied
+await app.todos.update(rec.id, { completed: true })  // partial update, changed fields only
+await app.todos.delete(rec.id)
+const one = await app.todos.findById(rec.id)
+const unsubscribe = app.todos
+  .where({ completed: false })
+  .orderBy('createdAt', 'desc')
+  .subscribe((rows) => {/* fires immediately, then on every change */})
+```
+
+Schema example (`src/schema.ts`):
+
+```ts
+import { defineSchema, t } from 'korajs'
+
+export default defineSchema({
+  version: 1,
+  collections: {
+    todos: {
+      fields: {
+        title: t.string(),
+        completed: t.boolean().default(false),
+        tags: t.array(t.string()).default([]),
+        priority: t.enum(['low', 'medium', 'high']).default('medium'),
+        createdAt: t.timestamp().auto(), // set automatically; never pass it on insert
+      },
+      indexes: ['completed', 'createdAt'],
+    },
+  },
+})
+```
+
+If you change a collection's shape, increment `version` and add a `migrations` entry for it (`migrate().addField(...)`): each device migrates its local database on its next open. `npx kora migrate` generates the matching migration for server databases and a transform stub for clients still on the older version.
+
+## Project conventions
+
+- Feature code lives in `src/modules/<feature>/` with the pattern: `<feature>.schema.ts` (collection definition, imported into `src/schema.ts`), `<feature>.queries.ts` (query builders), `<feature>.mutations.ts` (mutation functions taking a collection accessor).
+- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, arrays as multisets that keep every device's additions and removals, objects per top-level key). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
+
+## Commands
+
+- `npm run dev` starts everything: Vite dev server (port 5173), local sync server (port 3001), and the schema watcher.
+- `npm run build` type-checks and builds for production.
+- `npx kora doctor` diagnoses a broken setup.
+- DevTools overlay: press Ctrl+Shift+K (Cmd+Shift+K on macOS) in the running app to inspect operations, merges, and sync status.
+
+## Sync and auth
+
+Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })`. In dev, the sync URL is derived from the page host and proxied by Vite; in production set `VITE_SYNC_URL`. Auth (if present in this template) uses `@korajs/auth`; the client is created in `src/auth.ts`. Local writes work without sign-in; sync requires the server to accept the connection.
+
+## React bindings
+
+```tsx
+import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/react'
+
+const todos = useCollection('todos')
+const rows = useQuery(orderedTodos(todos))            // reactive; [] on the very first render
+const addTodo = useMutation((data) => todos.insert(data))
+addTodo.mutate({ title: 'x' })                        // fire-and-forget; errors land in addTodo.error
+await addTodo.mutateAsync({ title: 'x' })             // throws on failure; use when you need the error
+const status = useSyncStatus()                        // status.status, status.pendingOperations
+```
+
+Rules: always render `mutation.error` somewhere. The app must work under React StrictMode (the framework's hooks are StrictMode-safe; keep `<StrictMode>` in `src/main.tsx`). `useQuery` reads the local store: no network, no spinner. Its very first render returns `[]` before the local query has run; use `useQueryState` when you must tell "loading" from "no rows".

package/templates/react-tailwind/README.md.hbs

@@ -0,0 +1,62 @@
+# {{projectName}}
+
+An offline-first application built with [Kora.js](https://ehoneahobed.github.io/kora/).
+
+## Getting Started
+
+```bash
+npm run dev
+```
+
+- **App**: http://localhost:5173
+
+## Project Structure
+
+```
+src/
+  schema.ts        # Schema entry point
+  main.tsx         # App initialization and Kora setup
+  App.tsx          # Main application component
+  modules/
+    todos/
+      todo.schema.ts     # Todo collection definition
+      todo.queries.ts    # Reusable todo query builders
+      todo.mutations.ts  # Todo mutation helpers
+      useTodos.ts        # React hook connecting todos to the UI
+  kora-worker.ts   # SQLite WASM web worker
+  index.css        # Styles
+kora.config.ts     # Kora configuration
+```
+
+In a feature module, `schema` defines data shape, `queries` contain reads only, `mutations` contain
+writes, and `useTodos.ts` is the React binding that exposes todo data and actions to components.
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Start dev server |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build |
+
+## Adding Sync
+
+To enable real-time sync across devices, update `src/main.tsx`:
+
+```typescript
+const app = createApp({
+  schema,
+  sync: {
+    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001/kora-sync',
+  },
+  // ...
+})
+```
+
+Then create a `server.ts` and install `@korajs/server`. See the [Sync Configuration guide](https://ehoneahobed.github.io/kora/guide/sync-configuration).
+
+## Learn More
+
+- [Documentation](https://ehoneahobed.github.io/kora/)
+- [Storage Configuration](https://ehoneahobed.github.io/kora/guide/storage-configuration)
+- [Schema Design](https://ehoneahobed.github.io/kora/guide/schema-design)

package/templates/react-tailwind/index.html.hbs

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react-tailwind/kora.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'korajs/config'
+
+export default defineConfig({
+	schema: './src/schema.ts',
+	dev: {
+		port: 5173,
+		watch: {
+			enabled: true,
+			debounceMs: 300,
+		},
+		sync: false,
+	},
+})

package/templates/react-tailwind/package.json.hbs

@@ -0,0 +1,38 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "kora dev",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "korajs": "{{koraVersion}}",
+    "@korajs/react": "{{koraVersion}}",
+    "@korajs/store": "{{koraVersion}}",
+    "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
+    "lucide-react": "^0.468.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "yjs": "^13.6.30"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "protobufjs"
+    ]
+  },
+  "devDependencies": {
+    "@korajs/cli": "{{koraVersion}}",
+    "@tailwindcss/vite": "^4.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "tailwindcss": "^4.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}

package/templates/react-tailwind/src/App.tsx

@@ -0,0 +1,201 @@
+import { CheckCircle2, Circle, ClipboardList, Loader2, Plus, Trash2 } from 'lucide-react'
+import { useState } from 'react'
+import { useTodos } from './modules/todos/useTodos'
+
+type Filter = 'all' | 'active' | 'completed'
+
+export function App() {
+	const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } = useTodos()
+	const isAdding = addTodo.isLoading
+
+	const [filter, setFilter] = useState<Filter>('all')
+	const [input, setInput] = useState('')
+
+	const filteredTodos =
+		filter === 'active' ? activeTodos : filter === 'completed' ? completedTodos : allTodos
+
+	const handleSubmit = (e: React.FormEvent) => {
+		e.preventDefault()
+		const title = input.trim()
+		if (title) {
+			addTodo.mutate({ title })
+			setInput('')
+		}
+	}
+
+	const clearCompleted = () => {
+		for (const todo of completedTodos) {
+			deleteTodo.mutate(todo.id)
+		}
+	}
+
+	return (
+		<div className="min-h-screen bg-gray-950 text-gray-100">
+			<div className="mx-auto max-w-2xl px-4 py-12">
+				{/* Header */}
+				<div className="flex items-center justify-between mb-8">
+					<div className="flex items-center gap-3">
+						<ClipboardList className="h-8 w-8 text-indigo-400" />
+						<h1 className="text-2xl font-bold">My Tasks</h1>
+					</div>
+					<span className="rounded-full bg-gray-800 px-3 py-1.5 text-sm text-gray-400">
+						Local-first
+					</span>
+				</div>
+
+				{/* Stats */}
+				<div className="grid grid-cols-3 gap-4 mb-8">
+					<StatCard label="Total" value={allTodos.length} color="text-gray-300" />
+					<StatCard label="Remaining" value={activeTodos.length} color="text-amber-400" />
+					<StatCard label="Done" value={completedTodos.length} color="text-emerald-400" />
+				</div>
+
+				{/* Add form */}
+				<form onSubmit={handleSubmit} className="flex gap-3 mb-8">
+					<input
+						type="text"
+						value={input}
+						onChange={(e) => setInput(e.target.value)}
+						placeholder="What needs to be done?"
+						className="flex-1 rounded-lg border border-gray-700 bg-gray-900 px-4 py-3 text-gray-100 placeholder-gray-500 outline-none focus:border-indigo-500 focus:ring-1 focus:ring-indigo-500"
+					/>
+					<button
+						type="submit"
+						disabled={isAdding || !input.trim()}
+						className="flex items-center gap-2 rounded-lg bg-indigo-600 px-5 py-3 font-medium text-white transition hover:bg-indigo-500 disabled:opacity-50 disabled:cursor-not-allowed"
+					>
+						{isAdding ? <Loader2 className="h-4 w-4 animate-spin" /> : <Plus className="h-4 w-4" />}
+						Add
+					</button>
+				</form>
+
+				{/* Filter tabs */}
+				<div className="flex gap-2 mb-6">
+					{(['all', 'active', 'completed'] as const).map((f) => {
+						const count =
+							f === 'all'
+								? allTodos.length
+								: f === 'active'
+									? activeTodos.length
+									: completedTodos.length
+						return (
+							<button
+								key={f}
+								onClick={() => setFilter(f)}
+								className={`flex items-center gap-2 rounded-lg px-4 py-2 text-sm font-medium transition ${
+									filter === f
+										? 'bg-indigo-600 text-white'
+										: 'bg-gray-800 text-gray-400 hover:bg-gray-700 hover:text-gray-200'
+								}`}
+							>
+								{f.charAt(0).toUpperCase() + f.slice(1)}
+								<span
+									className={`rounded-full px-2 py-0.5 text-xs ${
+										filter === f ? 'bg-indigo-500 text-white' : 'bg-gray-700 text-gray-400'
+									}`}
+								>
+									{count}
+								</span>
+							</button>
+						)
+					})}
+				</div>
+
+				{/* Todo list */}
+				<div className="space-y-2">
+					{filteredTodos.length === 0 ? (
+						<EmptyState filter={filter} />
+					) : (
+						filteredTodos.map((todo) => (
+							<div
+								key={todo.id}
+								className="group flex items-center gap-3 rounded-lg border border-gray-800 bg-gray-900 px-4 py-3 transition hover:border-gray-700"
+							>
+								<button
+									onClick={() => toggleTodo.mutate(todo.id, { completed: !todo.completed })}
+									className="shrink-0 text-gray-500 hover:text-indigo-400 transition"
+								>
+									{todo.completed ? (
+										<CheckCircle2 className="h-5 w-5 text-emerald-400" />
+									) : (
+										<Circle className="h-5 w-5" />
+									)}
+								</button>
+								<span
+									className={`flex-1 ${
+										todo.completed ? 'text-gray-500 line-through' : 'text-gray-100'
+									}`}
+								>
+									{String(todo.title)}
+								</span>
+								{todo.createdAt && (
+									<span className="text-xs text-gray-600">
+										{formatTime(Number(todo.createdAt))}
+									</span>
+								)}
+								<button
+									onClick={() => deleteTodo.mutate(todo.id)}
+									className="shrink-0 text-gray-600 opacity-0 transition hover:text-red-400 group-hover:opacity-100"
+								>
+									<Trash2 className="h-4 w-4" />
+								</button>
+							</div>
+						))
+					)}
+				</div>
+
+				{/* Footer */}
+				{allTodos.length > 0 && (
+					<div className="mt-6 flex items-center justify-between text-sm text-gray-500">
+						<span>
+							{activeTodos.length} item{activeTodos.length !== 1 ? 's' : ''} left
+						</span>
+						{completedTodos.length > 0 && (
+							<button
+								onClick={clearCompleted}
+								className="text-gray-500 transition hover:text-gray-300"
+							>
+								Clear completed
+							</button>
+						)}
+					</div>
+				)}
+
+				<p className="mt-12 text-center text-xs text-gray-700">
+					Powered by Kora &mdash; offline-first, real-time sync
+				</p>
+			</div>
+		</div>
+	)
+}
+
+function StatCard({ label, value, color }: { label: string; value: number; color: string }) {
+	return (
+		<div className="rounded-lg border border-gray-800 bg-gray-900 p-4">
+			<p className="text-sm text-gray-500">{label}</p>
+			<p className={`text-2xl font-bold ${color}`}>{value}</p>
+		</div>
+	)
+}
+
+function EmptyState({ filter }: { filter: Filter }) {
+	const messages: Record<Filter, string> = {
+		all: 'No tasks yet. Add one above!',
+		active: 'All caught up! No active tasks.',
+		completed: 'No completed tasks yet.',
+	}
+	return (
+		<div className="rounded-lg border border-dashed border-gray-800 py-12 text-center text-gray-600">
+			{messages[filter]}
+		</div>
+	)
+}
+
+function formatTime(timestamp: number): string {
+	const date = new Date(timestamp)
+	const now = new Date()
+	if (date.toDateString() === now.toDateString()) {
+		return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+	}
+	return date.toLocaleDateString([], { month: 'short', day: 'numeric' })
+}

package/templates/react-tailwind/src/index.css

@@ -0,0 +1,7 @@
+@import "tailwindcss";
+
+@layer base {
+	body {
+		@apply bg-gray-950 text-gray-100 antialiased;
+	}
+}

package/templates/react-tailwind/src/kora-worker.ts

@@ -0,0 +1,9 @@
+// Web Worker entry point for SQLite WASM.
+// Loaded automatically by the Kora store to run SQLite in a background thread.
+
+// Import the WASM binary URL so Vite resolves it with the correct content hash.
+// Without this, production builds fail because sqlite3 looks for the unhashed filename.
+import sqliteWasmUrl from '@sqlite.org/sqlite-wasm/sqlite3.wasm?url'
+;(globalThis as Record<string, unknown>).__KORA_SQLITE_WASM_URL = sqliteWasmUrl
+
+import '@korajs/store/sqlite-wasm/worker'

package/templates/react-tailwind/src/main.tsx

@@ -0,0 +1,31 @@
+import { KoraProvider } from '@korajs/react'
+import { createApp } from 'korajs'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { App } from './App'
+import schema from './schema'
+import './index.css'
+import koraWorkerUrl from './kora-worker.ts?worker&url'
+
+const app = createApp({
+	schema,
+	store: {
+		workerUrl: koraWorkerUrl,
+	},
+	devtools: import.meta.env.DEV,
+})
+
+createRoot(document.getElementById('root')!).render(
+	<StrictMode>
+		<KoraProvider
+			app={app}
+			fallback={
+				<div className="flex items-center justify-center h-screen bg-gray-950 text-gray-400">
+					Loading...
+				</div>
+			}
+		>
+			<App />
+		</KoraProvider>
+	</StrictMode>,
+)

package/templates/react-tailwind/src/modules/todos/todo.mutations.ts

@@ -0,0 +1,25 @@
+import type { CollectionAccessor } from 'korajs'
+
+export interface CreateTodoInput {
+	title: string
+}
+
+export interface UpdateTodoStatusInput {
+	completed: boolean
+}
+
+export function createTodo(todos: CollectionAccessor, data: CreateTodoInput) {
+	return todos.insert({ title: data.title })
+}
+
+export function updateTodoStatus(
+	todos: CollectionAccessor,
+	id: string,
+	data: UpdateTodoStatusInput,
+) {
+	return todos.update(id, { completed: data.completed })
+}
+
+export function deleteTodo(todos: CollectionAccessor, id: string) {
+	return todos.delete(id)
+}

package/templates/react-tailwind/src/modules/todos/todo.queries.ts

@@ -0,0 +1,5 @@
+import type { CollectionAccessor } from 'korajs'
+
+export function orderedTodos(todos: CollectionAccessor) {
+	return todos.where({}).orderBy('createdAt', 'desc')
+}

package/templates/react-tailwind/src/modules/todos/todo.schema.ts

@@ -0,0 +1,10 @@
+import { t } from 'korajs'
+
+export const todos = {
+	fields: {
+		title: t.string(),
+		completed: t.boolean().default(false),
+		createdAt: t.timestamp().auto(),
+	},
+	indexes: ['completed', 'createdAt'],
+}

package/templates/react-tailwind/src/modules/todos/useTodos.ts

@@ -0,0 +1,31 @@
+import { useCollection, useMutation, useQuery } from '@korajs/react'
+import {
+	type CreateTodoInput,
+	type UpdateTodoStatusInput,
+	createTodo,
+	deleteTodo,
+	updateTodoStatus,
+} from './todo.mutations'
+import { orderedTodos } from './todo.queries'
+
+export function useTodos() {
+	const todos = useCollection('todos')
+	const allTodos = useQuery(orderedTodos(todos))
+	const addTodo = useMutation((data: CreateTodoInput) => createTodo(todos, data))
+	const toggleTodo = useMutation((id: string, data: UpdateTodoStatusInput) =>
+		updateTodoStatus(todos, id, data),
+	)
+	const removeTodo = useMutation((id: string) => deleteTodo(todos, id))
+
+	const activeTodos = allTodos.filter((todo) => !todo.completed)
+	const completedTodos = allTodos.filter((todo) => !!todo.completed)
+
+	return {
+		allTodos,
+		activeTodos,
+		completedTodos,
+		addTodo,
+		toggleTodo,
+		deleteTodo: removeTodo,
+	}
+}

package/templates/react-tailwind/src/schema.ts

@@ -0,0 +1,9 @@
+import { defineSchema } from 'korajs'
+import { todos } from './modules/todos/todo.schema'
+
+export default defineSchema({
+	version: 1,
+	collections: {
+		todos,
+	},
+})

package/templates/react-tailwind/src/vite-env.d.ts

@@ -0,0 +1,18 @@
+interface ImportMetaEnv {
+	readonly DEV: boolean
+	readonly VITE_SYNC_URL?: string
+}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv
+}
+
+declare module '*?worker&url' {
+	const url: string
+	export default url
+}
+
+declare module '*?url' {
+	const url: string
+	export default url
+}

package/templates/react-tailwind/tsconfig.json.hbs

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}