@korajs/cli 1.0.0-beta.11 → 1.0.0-beta.13

package/templates/react-sync/AGENTS.md

@@ -12,7 +12,7 @@ This is a **Kora.js** application: an offline-first app where all data lives in
 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 swallow 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.
+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.
 
@@ -52,12 +52,12 @@ export default defineSchema({
 })
 ```
 
-If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+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, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- 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
@@ -77,11 +77,11 @@ Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })
 import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/react'
 
 const todos = useCollection('todos')
-const rows = useQuery(orderedTodos(todos))            // reactive, no loading state for local data
+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` returns data synchronously from the local store, so do not add loading spinners for local reads.
+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-sync/server.ts

@@ -3,7 +3,9 @@ import {
 	type CreateKoraAuthServerOptions,
 	createKoraAuthServer,
 	createPostgresOAuthStores,
+	createPostgresUserStore,
 	createSqliteOAuthStores,
+	createSqliteUserStore,
 	googleProvider,
 } from '@korajs/auth/server'
 import {
@@ -101,8 +103,14 @@ async function createAuth() {
 	}
 
 	const oauth = await createOAuthConfig()
+	// Users and token revocations persist in the same database (the user store's
+	// revocation store is used automatically), so sign-outs survive restarts.
+	const userStore = process.env.DATABASE_URL
+		? await createPostgresUserStore({ connectionString: process.env.DATABASE_URL })
+		: await createSqliteUserStore({ filename: process.env.KORA_AUTH_DB || './.kora/kora-auth.db' })
 	return createKoraAuthServer({
 		jwtSecret: process.env.KORA_AUTH_SECRET,
+		userStore,
 		...(oauth ? { oauth } : {}),
 	})
 }

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

@@ -1,6 +1,7 @@
 interface ImportMetaEnv {
 	readonly DEV: boolean
 	readonly VITE_SYNC_URL?: string
+	readonly VITE_AUTH_URL?: string
 }
 
 interface ImportMeta {

package/templates/react-sync/vite.config.ts

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
+import { koraServiceWorker } from '@korajs/cli/vite'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
@@ -70,8 +71,10 @@ function sqliteWasmHotfix(): Plugin {
 	}
 }
 
+// koraServiceWorker() (build only, keep it last): precaches the built app shell so the
+// app opens offline, with a "new version available" reload prompt. See @korajs/cli/vite.
 export default defineConfig({
-	plugins: [react(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [react(), crossOriginIsolation(), sqliteWasmHotfix(), koraServiceWorker()],
 	worker: {
 		format: 'es',
 	},

package/templates/react-tailwind/AGENTS.md

@@ -12,7 +12,7 @@ This is a **Kora.js** application: an offline-first app where all data lives in
 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 swallow 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.
+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.
 
@@ -52,12 +52,12 @@ export default defineSchema({
 })
 ```
 
-If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+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, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- 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
@@ -77,11 +77,11 @@ Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })
 import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/react'
 
 const todos = useCollection('todos')
-const rows = useQuery(orderedTodos(todos))            // reactive, no loading state for local data
+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` returns data synchronously from the local store, so do not add loading spinners for local reads.
+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/vite.config.ts

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
+import { koraServiceWorker } from '@korajs/cli/vite'
 import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
@@ -71,8 +72,16 @@ function sqliteWasmHotfix(): Plugin {
 	}
 }
 
+// koraServiceWorker() (build only, keep it last): precaches the built app shell so the
+// app opens offline, with a "new version available" reload prompt. See @korajs/cli/vite.
 export default defineConfig({
-	plugins: [react(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [
+		react(),
+		tailwindcss(),
+		crossOriginIsolation(),
+		sqliteWasmHotfix(),
+		koraServiceWorker(),
+	],
 	worker: {
 		format: 'es',
 	},

package/templates/react-tailwind-sync/AGENTS.md

@@ -12,7 +12,7 @@ This is a **Kora.js** application: an offline-first app where all data lives in
 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 swallow 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.
+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.
 
@@ -52,12 +52,12 @@ export default defineSchema({
 })
 ```
 
-If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+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, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- 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
@@ -69,19 +69,21 @@ If you bump collections in a way that changes shapes, increment `version` and ru
 
 ## 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.
+Sync is configured in `src/kora.ts` 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
 
+Import the hooks from `src/kora.ts`, where `createKoraHooks<typeof app>()` binds them to this app's schema: collection names, inserts, updates, `where` and the rows `useQuery` returns are type-checked. Do not import them from `@korajs/react` directly (those are untyped).
+
 ```tsx
-import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/react'
+import { useCollection, useMutation, useQuery, useSyncStatus } from './kora'
 
 const todos = useCollection('todos')
-const rows = useQuery(orderedTodos(todos))            // reactive, no loading state for local data
+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` returns data synchronously from the local store, so do not add loading spinners for local reads.
+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-sync/server.ts

@@ -3,7 +3,9 @@ import {
 	type CreateKoraAuthServerOptions,
 	createKoraAuthServer,
 	createPostgresOAuthStores,
+	createPostgresUserStore,
 	createSqliteOAuthStores,
+	createSqliteUserStore,
 	googleProvider,
 } from '@korajs/auth/server'
 import {
@@ -101,8 +103,14 @@ async function createAuth() {
 	}
 
 	const oauth = await createOAuthConfig()
+	// Users and token revocations persist in the same database (the user store's
+	// revocation store is used automatically), so sign-outs survive restarts.
+	const userStore = process.env.DATABASE_URL
+		? await createPostgresUserStore({ connectionString: process.env.DATABASE_URL })
+		: await createSqliteUserStore({ filename: process.env.KORA_AUTH_DB || './.kora/kora-auth.db' })
 	return createKoraAuthServer({
 		jwtSecret: process.env.KORA_AUTH_SECRET,
+		userStore,
 		...(oauth ? { oauth } : {}),
 	})
 }

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

@@ -1,5 +1,4 @@
 import { useAuth } from '@korajs/auth/react'
-import { useSyncStatus } from '@korajs/react'
 import {
 	AlertCircle,
 	CheckCircle2,
@@ -12,6 +11,7 @@ import {
 	WifiOff,
 } from 'lucide-react'
 import { useState } from 'react'
+import { useSyncStatus } from './kora'
 import { useTodos } from './modules/todos/useTodos'
 
 type Filter = 'all' | 'active' | 'completed'

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

@@ -0,0 +1,32 @@
+import { createKoraAuthSync } from '@korajs/auth'
+import { createApp } from 'korajs'
+import { createKoraHooks } from 'korajs/react'
+import { authClient } from './auth'
+import koraWorkerUrl from './kora-worker.ts?worker&url'
+import schema from './schema'
+
+// Build sync URL: use env var if set, otherwise derive from current page host.
+// This allows the Vite proxy (/kora-sync → ws://localhost:3001) to work in dev,
+// and also works through any tunnel (ngrok, cloudflared) without extra configuration.
+const syncUrl =
+	import.meta.env.VITE_SYNC_URL ||
+	`${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/kora-sync`
+
+export const app = createApp({
+	schema,
+	sync: {
+		url: syncUrl,
+		authClient: createKoraAuthSync({ authClient, schema }),
+	},
+	store: {
+		workerUrl: koraWorkerUrl,
+	},
+	devtools: import.meta.env.DEV,
+})
+
+/** The typed `todos` collection: inserts, updates and queries are checked against the schema. */
+export type Todos = typeof app.todos
+
+// Hooks bound to this app's schema: `useCollection('todoz')` is a type error, and the
+// rows `useQuery` returns are typed from the query.
+export const { useCollection, useQuery, useMutation, useSyncStatus } = createKoraHooks<typeof app>()

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

@@ -1,33 +1,11 @@
-import { createKoraAuthSync } from '@korajs/auth'
 import { AuthProvider } from '@korajs/auth/react'
 import { KoraProvider } from '@korajs/react'
-import { createApp } from 'korajs'
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import { App } from './App'
 import { authClient, completeOAuthCallbackFromLocation } from './auth'
-import schema from './schema'
+import { app } from './kora'
 import './index.css'
-import koraWorkerUrl from './kora-worker.ts?worker&url'
-
-// Build sync URL: use env var if set, otherwise derive from current page host.
-// This allows the Vite proxy (/kora-sync → ws://localhost:3001) to work in dev,
-// and also works through any tunnel (ngrok, cloudflared) without extra configuration.
-const syncUrl =
-	import.meta.env.VITE_SYNC_URL ||
-	`${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/kora-sync`
-
-const app = createApp({
-	schema,
-	sync: {
-		url: syncUrl,
-		authClient: createKoraAuthSync({ authClient, schema }),
-	},
-	store: {
-		workerUrl: koraWorkerUrl,
-	},
-	devtools: import.meta.env.DEV,
-})
 
 // Connect to sync server once the app is ready
 app.ready.then(() => app.sync?.connect())

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { useCollection, useMutation, useQuery } from '@korajs/react'
+import { useCollection, useMutation, useQuery } from '../../kora'
 import {
 	type CreateTodoInput,
 	type UpdateTodoStatusInput,

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

@@ -1,6 +1,7 @@
 interface ImportMetaEnv {
 	readonly DEV: boolean
 	readonly VITE_SYNC_URL?: string
+	readonly VITE_AUTH_URL?: string
 }
 
 interface ImportMeta {

package/templates/react-tailwind-sync/vite.config.ts

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
+import { koraServiceWorker } from '@korajs/cli/vite'
 import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
@@ -71,8 +72,16 @@ function sqliteWasmHotfix(): Plugin {
 	}
 }
 
+// koraServiceWorker() (build only, keep it last): precaches the built app shell so the
+// app opens offline, with a "new version available" reload prompt. See @korajs/cli/vite.
 export default defineConfig({
-	plugins: [react(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [
+		react(),
+		tailwindcss(),
+		crossOriginIsolation(),
+		sqliteWasmHotfix(),
+		koraServiceWorker(),
+	],
 	worker: {
 		format: 'es',
 	},

package/templates/svelte-basic/AGENTS.md

@@ -12,7 +12,7 @@ This is a **Kora.js** application: an offline-first app where all data lives in
 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 swallow 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.
+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.
 
@@ -52,12 +52,12 @@ export default defineSchema({
 })
 ```
 
-If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+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, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- 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
@@ -73,4 +73,4 @@ Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })
 
 ## Svelte bindings
 
-Kora's Svelte package exposes store-based bindings from `@korajs/svelte`, wired through the provider set up in the app entry. Queries are reactive stores that read synchronously from the local database; mutations expose error state that must be surfaced in the UI. Avoid loading spinners for local reads.
+Kora's Svelte package exposes store-based bindings from `@korajs/svelte`, wired through the provider set up in the app entry. Queries are reactive stores over the local database (no network, no spinner; `[]` until the first local result); mutations expose error state that must be surfaced in the UI.

package/templates/svelte-basic/package.json.hbs

@@ -17,10 +17,16 @@
     "svelte": "^5.0.0",
     "yjs": "^13.6.30"
   },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
   "devDependencies": {
     "@korajs/cli": "{{koraVersion}}",
     "@sveltejs/vite-plugin-svelte": "^5.0.0",
     "svelte-check": "^4.1.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0"
   }

package/templates/svelte-basic/src/App.svelte

@@ -6,7 +6,8 @@ type Filter = 'all' | 'active' | 'completed'
 const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } =
 	createTodosStores()
 
-const filter = $state<Filter>('all')
+// biome-ignore lint/style/useConst: reassigned in the markup, which Biome does not see
+let filter = $state<Filter>('all')
 let input = $state('')
 
 const filteredTodos = $derived(

package/templates/svelte-basic/vite.config.ts

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
+import { koraServiceWorker } from '@korajs/cli/vite'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
 import type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
@@ -43,8 +44,10 @@ function sqliteWasmHotfix(): Plugin {
 	}
 }
 
+// koraServiceWorker() (build only, keep it last): precaches the built app shell so the
+// app opens offline, with a "new version available" reload prompt. See @korajs/cli/vite.
 export default defineConfig({
-	plugins: [svelte(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [svelte(), crossOriginIsolation(), sqliteWasmHotfix(), koraServiceWorker()],
 	worker: { format: 'es' },
 	optimizeDeps: {
 		exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],

package/templates/svelte-sync/AGENTS.md

@@ -12,7 +12,7 @@ This is a **Kora.js** application: an offline-first app where all data lives in
 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 swallow 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.
+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.
 
@@ -52,12 +52,12 @@ export default defineSchema({
 })
 ```
 
-If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+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, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- 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
@@ -73,4 +73,4 @@ Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })
 
 ## Svelte bindings
 
-Kora's Svelte package exposes store-based bindings from `@korajs/svelte`, wired through the provider set up in the app entry. Queries are reactive stores that read synchronously from the local database; mutations expose error state that must be surfaced in the UI. Avoid loading spinners for local reads.
+Kora's Svelte package exposes store-based bindings from `@korajs/svelte`, wired through the provider set up in the app entry. Queries are reactive stores over the local database (no network, no spinner; `[]` until the first local result); mutations expose error state that must be surfaced in the UI.

package/templates/svelte-sync/server.ts

@@ -3,7 +3,9 @@ import {
 	type CreateKoraAuthServerOptions,
 	createKoraAuthServer,
 	createPostgresOAuthStores,
+	createPostgresUserStore,
 	createSqliteOAuthStores,
+	createSqliteUserStore,
 	googleProvider,
 } from '@korajs/auth/server'
 import {
@@ -101,8 +103,14 @@ async function createAuth() {
 	}
 
 	const oauth = await createOAuthConfig()
+	// Users and token revocations persist in the same database (the user store's
+	// revocation store is used automatically), so sign-outs survive restarts.
+	const userStore = process.env.DATABASE_URL
+		? await createPostgresUserStore({ connectionString: process.env.DATABASE_URL })
+		: await createSqliteUserStore({ filename: process.env.KORA_AUTH_DB || './.kora/kora-auth.db' })
 	return createKoraAuthServer({
 		jwtSecret: process.env.KORA_AUTH_SECRET,
+		userStore,
 		...(oauth ? { oauth } : {}),
 	})
 }

package/templates/svelte-sync/src/App.svelte

@@ -10,7 +10,8 @@ const auth = createAuthStore()
 const todos = createTodosStores()
 const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } = todos
 
-const filter = $state<Filter>('all')
+// biome-ignore lint/style/useConst: reassigned in the markup, which Biome does not see
+let filter = $state<Filter>('all')
 let input = $state('')
 
 const filteredTodos = $derived(

package/templates/svelte-sync/vite.config.ts

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
+import { koraServiceWorker } from '@korajs/cli/vite'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
 import type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
@@ -56,8 +57,10 @@ function sqliteWasmHotfix(): Plugin {
 	}
 }
 
+// koraServiceWorker() (build only, keep it last): precaches the built app shell so the
+// app opens offline, with a "new version available" reload prompt. See @korajs/cli/vite.
 export default defineConfig({
-	plugins: [svelte(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [svelte(), crossOriginIsolation(), sqliteWasmHotfix(), koraServiceWorker()],
 	worker: {
 		format: 'es',
 	},

package/templates/svelte-tailwind/AGENTS.md

@@ -12,7 +12,7 @@ This is a **Kora.js** application: an offline-first app where all data lives in
 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 swallow 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.
+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.
 
@@ -52,12 +52,12 @@ export default defineSchema({
 })
 ```
 
-If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+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, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- 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
@@ -73,4 +73,4 @@ Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })
 
 ## Svelte bindings
 
-Kora's Svelte package exposes store-based bindings from `@korajs/svelte`, wired through the provider set up in the app entry. Queries are reactive stores that read synchronously from the local database; mutations expose error state that must be surfaced in the UI. Avoid loading spinners for local reads.
+Kora's Svelte package exposes store-based bindings from `@korajs/svelte`, wired through the provider set up in the app entry. Queries are reactive stores over the local database (no network, no spinner; `[]` until the first local result); mutations expose error state that must be surfaced in the UI.