@korajs/cli 0.4.0 → 0.6.0

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

@@ -1,24 +1,31 @@
-import { createApp } from 'korajs'
 import { KoraProvider } from '@korajs/react'
+import { createApp } from 'korajs'
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
-import schema from './schema'
 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: true,
+	schema,
+	store: {
+		workerUrl: koraWorkerUrl,
+	},
+	devtools: true,
 })
 
 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>,
+	<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

@@ -1,15 +1,9 @@
-import { defineSchema, t } from 'korajs'
+import { defineSchema } from 'korajs'
+import { todos } from './modules/todos/todo.schema'
 
 export default defineSchema({
-  version: 1,
-  collections: {
-    todos: {
-      fields: {
-        title: t.string(),
-        completed: t.boolean().default(false),
-        createdAt: t.timestamp().auto(),
-      },
-      indexes: ['completed'],
-    },
-  },
+	version: 1,
+	collections: {
+		todos,
+	},
 })

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

@@ -0,0 +1,17 @@
+interface ImportMetaEnv {
+	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 → tsconfig.json.hbs}

@@ -8,8 +8,7 @@
     "noUncheckedIndexedAccess": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "outDir": "dist",
-    "types": ["vite/client"]
+    "outDir": "dist"
   },
   "include": ["src"]
 }

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

@@ -1,5 +1,5 @@
-import { existsSync, readdirSync, copyFileSync } from 'node:fs'
-import { resolve, join } from 'node:path'
+import { copyFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
 import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
@@ -11,23 +11,23 @@ import { defineConfig } from 'vite'
  * cannot be used and SQLite WASM falls back to in-memory storage (no persistence).
  */
 function crossOriginIsolation(): Plugin {
-  return {
-    name: 'cross-origin-isolation',
-    configureServer(server) {
-      server.middlewares.use((_req, res, next) => {
-        res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-        res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
-        next()
-      })
-    },
-    configurePreviewServer(server) {
-      server.middlewares.use((_req, res, next) => {
-        res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-        res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
-        next()
-      })
-    },
-  }
+	return {
+		name: 'cross-origin-isolation',
+		configureServer(server) {
+			server.middlewares.use((_req, res, next) => {
+				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				next()
+			})
+		},
+		configurePreviewServer(server) {
+			server.middlewares.use((_req, res, next) => {
+				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				next()
+			})
+		},
+	}
 }
 
 /**
@@ -37,40 +37,47 @@ function crossOriginIsolation(): Plugin {
  *    sqlite3 loads it dynamically) so the full OPFS VFS can initialize without errors
  */
 function sqliteWasmHotfix(): Plugin {
-  return {
-    name: 'sqlite-wasm-hotfix',
-    apply: 'build',
-    closeBundle() {
-      const assetsDir = resolve('dist', 'assets')
-      if (!existsSync(assetsDir)) return
+	return {
+		name: 'sqlite-wasm-hotfix',
+		apply: 'build',
+		closeBundle() {
+			const assetsDir = resolve('dist', 'assets')
+			if (!existsSync(assetsDir)) return
 
-      // Copy hashed sqlite3.wasm to unhashed name
-      for (const file of readdirSync(assetsDir)) {
-        if (/^sqlite3-.+\.wasm$/.test(file)) {
-          copyFileSync(join(assetsDir, file), join(assetsDir, 'sqlite3.wasm'))
-          break
-        }
-      }
+			// Copy hashed sqlite3.wasm to unhashed name
+			for (const file of readdirSync(assetsDir)) {
+				if (/^sqlite3-.+\.wasm$/.test(file)) {
+					copyFileSync(join(assetsDir, file), join(assetsDir, 'sqlite3.wasm'))
+					break
+				}
+			}
 
-      // Copy OPFS async proxy worker (dynamically loaded by sqlite3, not detected by Vite)
-      const proxyFile = resolve('node_modules', '@sqlite.org', 'sqlite-wasm', 'sqlite-wasm', 'jswasm', 'sqlite3-opfs-async-proxy.js')
-      if (existsSync(proxyFile)) {
-        copyFileSync(proxyFile, join(assetsDir, 'sqlite3-opfs-async-proxy.js'))
-      }
-    },
-  }
+			// Copy OPFS async proxy worker (dynamically loaded by sqlite3, not detected by Vite)
+			const proxyFile = resolve(
+				'node_modules',
+				'@sqlite.org',
+				'sqlite-wasm',
+				'sqlite-wasm',
+				'jswasm',
+				'sqlite3-opfs-async-proxy.js',
+			)
+			if (existsSync(proxyFile)) {
+				copyFileSync(proxyFile, join(assetsDir, 'sqlite3-opfs-async-proxy.js'))
+			}
+		},
+	}
 }
 
 export default defineConfig({
-  plugins: [react(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
-  worker: {
-    format: 'es',
-  },
-  optimizeDeps: {
-    exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
-    include: ['yjs'],
-  },
-  resolve: {
-    dedupe: ['yjs'],
-  },
+	plugins: [react(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+	worker: {
+		format: 'es',
+	},
+	optimizeDeps: {
+		exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
+		include: ['yjs'],
+	},
+	resolve: {
+		dedupe: ['yjs'],
+	},
 })

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

@@ -4,3 +4,22 @@ VITE_SYNC_URL=ws://localhost:3001
 
 # Sync server port
 PORT=3001
+
+# Server database
+# Leave DATABASE_URL empty to use SQLite at KORA_SERVER_DB.
+KORA_SERVER_DB=./kora-server.db
+DATABASE_URL=
+
+# Operational endpoints (/__kora, /__kora/status, /__kora/events, /__kora/metrics, backups)
+# Set these in production. Use Authorization: Bearer <token> when calling protected endpoints.
+KORA_ADMIN_TOKEN=
+KORA_METRICS_TOKEN=
+KORA_BACKUP_TOKEN=
+
+# Optional sync path
+KORA_SYNC_PATH=/kora-sync
+
+# Auth
+# Set this to enable built-in /auth/* routes and authenticated sync.
+# Generate with: node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
+KORA_AUTH_SECRET=

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

@@ -17,21 +17,63 @@ This starts both the Vite dev server and the Kora sync server.
 
 ```
 src/
-  schema.ts        # Data schema definition
+  schema.ts        # Schema entry point
+  auth.ts          # Auth client and OAuth callback handling
   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
 server.ts          # Kora sync server
 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.
+
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `VITE_SYNC_URL` | `ws://localhost:3001` | WebSocket URL for the sync server |
+| `VITE_AUTH_URL` | current origin | 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 |
+| `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 |
+| `KORA_GOOGLE_CLIENT_ID` | (none) | Enables Google OAuth when set with `KORA_GOOGLE_REDIRECT_URI` |
+| `KORA_GOOGLE_CLIENT_SECRET` | (none) | Google OAuth client secret for confidential web clients |
+| `KORA_GOOGLE_REDIRECT_URI` | (none) | OAuth callback URL, usually your app URL that handles `code` and `state` |
+| `KORA_OAUTH_PKCE` | `true` when no client secret | Enables PKCE for public desktop/mobile OAuth clients |
+| `KORA_ADMIN_TOKEN` | (none) | Protects `/__kora`, `/__kora/status`, and `/__kora/events` |
+| `KORA_METRICS_TOKEN` | (none) | Protects `/__kora/metrics` |
+| `KORA_BACKUP_TOKEN` | (none) | Protects server backup and restore endpoints |
+
+## Authentication
+
+Set `KORA_AUTH_SECRET` to enable built-in auth on the sync server. Generate a secret with:
+
+```bash
+node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
+```
+
+The template already creates `src/auth.ts`, wraps the app in `AuthProvider`, and wires sync with `createKoraAuthSync({ authClient, schema })`. To enable Google OAuth, set:
+
+```bash
+KORA_AUTH_SECRET=...
+KORA_GOOGLE_CLIENT_ID=...
+KORA_GOOGLE_CLIENT_SECRET=...
+KORA_GOOGLE_REDIRECT_URI=http://localhost:5173
+```
+
+Use `authClient.signInWithOAuth('google')` for web redirect sign-in, or `authClient.getOAuthAuthorizationUrl('google')` plus `authClient.completeOAuthSignIn('google', { code, state })` for custom handoff flows. See the [Authentication Guide](https://ehoneahobed.github.io/kora/guide/authentication).
 
 ## Scripts
 

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

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "korajs": "{{koraVersion}}",
+    "@korajs/auth": "{{koraVersion}}",
     "@korajs/react": "{{koraVersion}}",
     "@korajs/store": "{{koraVersion}}",
     "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
@@ -36,6 +37,8 @@
     "@types/react-dom": "^19.0.0",
     "@types/ws": "^8.5.0",
     "@vitejs/plugin-react": "^4.3.0",
+    "better-sqlite3": "^12.9.0",
+    "postgres": "^3.4.0",
     "tailwindcss": "^4.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",

package/templates/react-tailwind-sync/server.ts

@@ -1,26 +1,90 @@
-import { createProductionServer, createSqliteServerStore } from '@korajs/server'
-
-// SQLite persists data to disk — survives server restarts
-const store = createSqliteServerStore({ filename: './kora-server.db' })
-
-// To use PostgreSQL instead:
-// 1. Install: pnpm add postgres
-// 2. Replace the store above with:
-//
-// import { createPostgresServerStore } from '@korajs/server'
-// const store = await createPostgresServerStore({
-//   connectionString: 'postgresql://user:password@localhost:5432/mydb',
-// })
-
-// Production server: serves static files + WebSocket sync on a single port.
-// One port means one tunnel (ngrok, cloudflared) handles everything.
-const server = createProductionServer({
-  store,
-  port: Number(process.env.PORT) || 3001,
-  staticDir: './dist',
-  syncPath: '/kora-sync',
-})
-
-server.start().then((url) => {
-  console.log(`Kora app running at ${url}`)
-})
+import {
+	type CreateKoraAuthServerOptions,
+	createKoraAuthServer,
+	createPostgresOAuthStores,
+	createSqliteOAuthStores,
+	googleProvider,
+} from '@korajs/auth/server'
+import {
+	createPostgresServerStore,
+	createProductionServer,
+	createSqliteServerStore,
+} from '@korajs/server'
+import schema from './src/schema'
+
+async function createStore() {
+	if (process.env.DATABASE_URL) {
+		return createPostgresServerStore({
+			connectionString: process.env.DATABASE_URL,
+		})
+	}
+
+	return createSqliteServerStore({
+		filename: process.env.KORA_SERVER_DB || './kora-server.db',
+	})
+}
+
+async function start() {
+	const store = await createStore()
+	await store.setSchema(schema)
+
+	const syncPath = process.env.KORA_SYNC_PATH || '/kora-sync'
+	const auth = await createAuth()
+	const server = createProductionServer({
+		store,
+		port: Number(process.env.PORT) || 3001,
+		staticDir: './dist',
+		syncPath,
+		httpRoutes: auth ? [{ path: '/auth', handle: auth.handleRequest }] : undefined,
+		syncOptions: auth ? { auth: auth.auth } : undefined,
+		operationalAuth: {
+			adminToken: process.env.KORA_ADMIN_TOKEN,
+			metricsToken: process.env.KORA_METRICS_TOKEN,
+			backupToken: process.env.KORA_BACKUP_TOKEN,
+		},
+	})
+
+	const url = await server.start()
+	console.log(`Kora app running at ${url}`)
+	console.log(`  Sync endpoint: ${url.replace('http', 'ws')}${syncPath}`)
+	if (auth) console.log(`  Auth endpoint: ${url}/auth`)
+}
+
+void start()
+
+async function createAuth() {
+	if (!process.env.KORA_AUTH_SECRET) {
+		return null
+	}
+
+	const oauth = await createOAuthConfig()
+	return createKoraAuthServer({
+		jwtSecret: process.env.KORA_AUTH_SECRET,
+		...(oauth ? { oauth } : {}),
+	})
+}
+
+async function createOAuthConfig(): Promise<CreateKoraAuthServerOptions['oauth'] | undefined> {
+	if (!process.env.KORA_GOOGLE_CLIENT_ID || !process.env.KORA_GOOGLE_REDIRECT_URI) {
+		return undefined
+	}
+
+	const oauthStores = process.env.DATABASE_URL
+		? await createPostgresOAuthStores({ connectionString: process.env.DATABASE_URL })
+		: await createSqliteOAuthStores({
+				filename: process.env.KORA_AUTH_DB || './kora-auth.db',
+			})
+
+	return {
+		providers: [
+			googleProvider({
+				clientId: process.env.KORA_GOOGLE_CLIENT_ID,
+				clientSecret: process.env.KORA_GOOGLE_CLIENT_SECRET,
+				redirectUri: process.env.KORA_GOOGLE_REDIRECT_URI,
+				pkce: process.env.KORA_OAUTH_PKCE === 'true' || !process.env.KORA_GOOGLE_CLIENT_SECRET,
+			}),
+		],
+		stateStore: oauthStores.stateStore,
+		linkedIdentityStore: oauthStores.linkedIdentityStore,
+	}
+}