@korajs/cli 1.0.0-beta.12 → 1.0.0-beta.14

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

@@ -13,17 +13,23 @@
     "korajs": "{{koraVersion}}",
     "@korajs/svelte": "{{koraVersion}}",
     "@korajs/store": "{{koraVersion}}",
-    "@lucide/svelte": "^0.468.0",
+    "@lucide/svelte": "^0.479.0",
     "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
     "svelte": "^5.0.0",
     "yjs": "^13.6.30"
   },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
   "devDependencies": {
     "@korajs/cli": "{{koraVersion}}",
     "@sveltejs/vite-plugin-svelte": "^5.0.0",
     "@tailwindcss/vite": "^4.0.0",
     "svelte-check": "^4.1.0",
     "tailwindcss": "^4.0.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0"
   }

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

@@ -7,7 +7,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-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 { svelte } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
 import type { Plugin } from 'vite'
@@ -44,8 +45,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: [svelte(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [
+		svelte(),
+		tailwindcss(),
+		crossOriginIsolation(),
+		sqliteWasmHotfix(),
+		koraServiceWorker(),
+	],
 	worker: { format: 'es' },
 	optimizeDeps: {
 		exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],

package/templates/svelte-tailwind-sync/.env.example

@@ -7,7 +7,7 @@ PORT=3001
 
 # Server database
 # Leave DATABASE_URL empty to use SQLite at KORA_SERVER_DB.
-KORA_SERVER_DB=./kora-server.db
+KORA_SERVER_DB=./.kora/kora-server.db
 DATABASE_URL=
 
 # Operational endpoints (/__kora, /__kora/status, /__kora/events, /__kora/metrics, backups)

package/templates/svelte-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
@@ -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-tailwind-sync/package.json.hbs

@@ -16,7 +16,7 @@
     "@korajs/auth": "{{koraVersion}}",
     "@korajs/svelte": "{{koraVersion}}",
     "@korajs/store": "{{koraVersion}}",
-    "@lucide/svelte": "^0.468.0",
+    "@lucide/svelte": "^0.479.0",
     "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
     "svelte": "^5.0.0",
     "ws": "^8.18.0",

package/templates/svelte-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/svelte-tailwind-sync/src/App.svelte

@@ -21,7 +21,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-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 { svelte } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
 import type { Plugin } from 'vite'
@@ -57,8 +58,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: [svelte(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [
+		svelte(),
+		tailwindcss(),
+		crossOriginIsolation(),
+		sqliteWasmHotfix(),
+		koraServiceWorker(),
+	],
 	worker: {
 		format: 'es',
 	},

package/templates/tauri-react/.env.example

@@ -9,7 +9,7 @@ PORT=3001
 # Server database
 # Leave DATABASE_URL empty to use SQLite at KORA_SERVER_DB.
 # Set DATABASE_URL for cloud Postgres deployments.
-KORA_SERVER_DB=./kora-server.db
+KORA_SERVER_DB=./.kora/kora-server.db
 DATABASE_URL=
 
 # Operational endpoints (/__kora, /__kora/status, /__kora/events, /__kora/metrics, backups)

package/templates/tauri-react/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,14 +77,14 @@ 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".
 
 ## Tauri specifics
 

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

@@ -136,8 +136,8 @@ Users can also skip setup and use the app offline — they can connect later fro
 | `VITE_SYNC_URL` | (none) | Pre-configure sync URL at build time |
 | `VITE_AUTH_URL` | derived from sync URL | HTTP URL for `/auth/*` routes |
 | `PORT` | `3001` | Sync server port |
-| `KORA_SERVER_DB` | `./kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
-| `KORA_AUTH_DB` | `./kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
+| `KORA_SERVER_DB` | `./.kora/kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
+| `KORA_AUTH_DB` | `./.kora/kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
 | `DATABASE_URL` | (none) | PostgreSQL connection string for production sync server deployments |
 | `KORA_SYNC_PATH` | `/kora-sync` | WebSocket path exposed by the sync server |
 | `KORA_AUTH_SECRET` | (none) | Enables built-in `/auth/*` routes and authenticated sync when set |

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

@@ -16,7 +16,7 @@
     "@korajs/auth": "{{koraVersion}}",
     "@korajs/core": "{{koraVersion}}",
     "@korajs/react": "{{koraVersion}}",
-    "@korajs/tauri": "{{koraVersion}}",
+    "@korajs/tauri": "{{tauriVersion}}",
     "@tauri-apps/api": "^2.0.0",
     "@tauri-apps/plugin-updater": "^2.0.0",
     "lucide-react": "^0.468.0",

package/templates/tauri-react/server.ts

@@ -3,7 +3,9 @@ import {
 	type CreateKoraAuthServerOptions,
 	createKoraAuthServer,
 	createPostgresOAuthStores,
+	createPostgresUserStore,
 	createSqliteOAuthStores,
+	createSqliteUserStore,
 	googleProvider,
 } from '@korajs/auth/server'
 import {
@@ -68,7 +70,7 @@ async function createStore() {
 	}
 
 	return createSqliteServerStore({
-		filename: process.env.KORA_SERVER_DB || './kora-server.db',
+		filename: process.env.KORA_SERVER_DB || './.kora/kora-server.db',
 	})
 }
 
@@ -108,8 +110,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 } : {}),
 	})
 }
@@ -122,7 +130,7 @@ async function createOAuthConfig(): Promise<CreateKoraAuthServerOptions['oauth']
 	const oauthStores = process.env.DATABASE_URL
 		? await createPostgresOAuthStores({ connectionString: process.env.DATABASE_URL })
 		: await createSqliteOAuthStores({
-				filename: process.env.KORA_AUTH_DB || './kora-auth.db',
+				filename: process.env.KORA_AUTH_DB || './.kora/kora-auth.db',
 			})
 
 	return {

package/templates/tauri-react/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/vue-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
@@ -81,4 +81,4 @@ const rows = useQuery(orderedTodos(todos))   // readonly reactive ref
 const addTodo = useMutation((data) => todos.insert(data))
 ```
 
-Rules: always surface the mutation's error state in the UI. `useQuery` reads synchronously from the local store, so avoid loading spinners for local data. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.
+Rules: always surface the mutation's error state in the UI. `useQuery` reads the local store (no network, no spinner); the ref holds `[]` until the first local result. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.

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

@@ -16,9 +16,15 @@
     "vue": "^3.5.0",
     "yjs": "^13.6.30"
   },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
   "devDependencies": {
     "@korajs/cli": "{{koraVersion}}",
     "@vitejs/plugin-vue": "^5.2.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0",
     "vue-tsc": "^2.2.0"

package/templates/vue-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 vue from '@vitejs/plugin-vue'
 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: [vue(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [vue(), crossOriginIsolation(), sqliteWasmHotfix(), koraServiceWorker()],
 	worker: {
 		format: 'es',
 	},

package/templates/vue-sync/.env.example

@@ -7,7 +7,7 @@ PORT=3001
 
 # Server database
 # Leave DATABASE_URL empty to use SQLite at KORA_SERVER_DB.
-KORA_SERVER_DB=./kora-server.db
+KORA_SERVER_DB=./.kora/kora-server.db
 DATABASE_URL=
 
 # Operational endpoints (/__kora, /__kora/status, /__kora/events, /__kora/metrics, backups)

package/templates/vue-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
@@ -81,4 +81,4 @@ const rows = useQuery(orderedTodos(todos))   // readonly reactive ref
 const addTodo = useMutation((data) => todos.insert(data))
 ```
 
-Rules: always surface the mutation's error state in the UI. `useQuery` reads synchronously from the local store, so avoid loading spinners for local data. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.
+Rules: always surface the mutation's error state in the UI. `useQuery` reads the local store (no network, no spinner); the ref holds `[]` until the first local result. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.

package/templates/vue-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/vue-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 vue from '@vitejs/plugin-vue'
 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: [vue(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [vue(), crossOriginIsolation(), sqliteWasmHotfix(), koraServiceWorker()],
 	worker: {
 		format: 'es',
 	},

package/templates/vue-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
@@ -81,4 +81,4 @@ const rows = useQuery(orderedTodos(todos))   // readonly reactive ref
 const addTodo = useMutation((data) => todos.insert(data))
 ```
 
-Rules: always surface the mutation's error state in the UI. `useQuery` reads synchronously from the local store, so avoid loading spinners for local data. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.
+Rules: always surface the mutation's error state in the UI. `useQuery` reads the local store (no network, no spinner); the ref holds `[]` until the first local result. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.

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

@@ -17,11 +17,17 @@
     "vue": "^3.5.0",
     "yjs": "^13.6.30"
   },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
   "devDependencies": {
     "@korajs/cli": "{{koraVersion}}",
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-vue": "^5.2.0",
     "tailwindcss": "^4.0.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0",
     "vue-tsc": "^2.2.0"

package/templates/vue-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 vue from '@vitejs/plugin-vue'
 import type { Plugin } from 'vite'
@@ -57,8 +58,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: [vue(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [vue(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix(), koraServiceWorker()],
 	worker: {
 		format: 'es',
 	},

package/templates/vue-tailwind-sync/.env.example

@@ -7,7 +7,7 @@ PORT=3001
 
 # Server database
 # Leave DATABASE_URL empty to use SQLite at KORA_SERVER_DB.
-KORA_SERVER_DB=./kora-server.db
+KORA_SERVER_DB=./.kora/kora-server.db
 DATABASE_URL=
 
 # Operational endpoints (/__kora, /__kora/status, /__kora/events, /__kora/metrics, backups)

package/templates/vue-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
@@ -81,4 +81,4 @@ const rows = useQuery(orderedTodos(todos))   // readonly reactive ref
 const addTodo = useMutation((data) => todos.insert(data))
 ```
 
-Rules: always surface the mutation's error state in the UI. `useQuery` reads synchronously from the local store, so avoid loading spinners for local data. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.
+Rules: always surface the mutation's error state in the UI. `useQuery` reads the local store (no network, no spinner); the ref holds `[]` until the first local result. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.

package/templates/vue-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/vue-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 vue from '@vitejs/plugin-vue'
 import type { Plugin } from 'vite'
@@ -57,8 +58,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: [vue(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [vue(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix(), koraServiceWorker()],
 	worker: {
 		format: 'es',
 	},