@korajs/cli 0.5.0 → 0.6.0

package/templates/vue-sync/README.md.hbs

@@ -0,0 +1,105 @@
+# {{projectName}}
+
+An offline-first application built with [Kora.js](https://ehoneahobed.github.io/kora/).
+
+## Getting Started
+
+```bash
+npm run dev
+```
+
+This starts both the Vite dev server and the Kora sync server.
+
+- **App**: http://localhost:5173
+- **Sync server**: ws://localhost:3001
+
+## Project Structure
+
+```
+src/
+  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
+
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Start dev server + sync server |
+| `npm run dev:server` | Start sync server only |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build |
+
+## Deployment
+
+The client and sync server must be deployed separately:
+
+- **Client**: Any static host (Vercel, Netlify, Cloudflare Pages)
+- **Sync server**: Any Node.js host with WebSocket support (Railway, Render, Fly.io)
+
+Set `VITE_SYNC_URL` to your deployed sync server URL when building:
+
+```bash
+VITE_SYNC_URL=wss://your-server.example.com npm run build
+```
+
+## Learn More
+
+- [Documentation](https://ehoneahobed.github.io/kora/)
+- [Storage Configuration](https://ehoneahobed.github.io/kora/guide/storage-configuration)
+- [Sync Configuration](https://ehoneahobed.github.io/kora/guide/sync-configuration)
+- [Deployment Guide](https://ehoneahobed.github.io/kora/guide/deployment)

package/templates/vue-sync/index.html.hbs

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

package/templates/vue-sync/kora.config.ts

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

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

@@ -0,0 +1,42 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "kora dev",
+    "dev:server": "tsx server.ts",
+    "build": "vue-tsc --noEmit && vite build",
+    "start": "node --import tsx server.ts",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "korajs": "{{koraVersion}}",
+    "@korajs/auth": "{{koraVersion}}",
+    "@korajs/vue": "{{koraVersion}}",
+    "@korajs/store": "{{koraVersion}}",
+    "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
+    "vue": "^3.5.0",
+    "ws": "^8.18.0",
+    "yjs": "^13.6.30"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild",
+      "protobufjs"
+    ]
+  },
+  "devDependencies": {
+    "@korajs/cli": "{{koraVersion}}",
+    "@korajs/server": "{{koraVersion}}",
+    "@types/ws": "^8.5.0",
+    "@vitejs/plugin-vue": "^5.2.0",
+    "better-sqlite3": "^12.9.0",
+    "postgres": "^3.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vue-tsc": "^2.2.0"
+  }
+}

package/templates/vue-sync/server.ts

@@ -0,0 +1,90 @@
+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,
+	}
+}

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

@@ -0,0 +1,135 @@
+<script setup lang="ts">
+import { useAuth } from '@korajs/auth/vue'
+import { useSyncStatus } from '@korajs/vue'
+import { computed, ref } from 'vue'
+import { useTodos } from './modules/todos/useTodos'
+
+type Filter = 'all' | 'active' | 'completed'
+
+const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } = useTodos()
+const syncStatus = useSyncStatus()
+const { user, isAuthenticated, signInWithOAuth, signOut, error } = useAuth()
+
+const filter = ref<Filter>('all')
+const input = ref('')
+
+const filteredTodos = computed(() => {
+	if (filter.value === 'active') return activeTodos.value
+	if (filter.value === 'completed') return completedTodos.value
+	return allTodos.value
+})
+
+function handleSubmit(): void {
+	const title = input.value.trim()
+	if (!title) return
+	addTodo.mutate({ title })
+	input.value = ''
+}
+
+function clearCompleted(): void {
+	for (const todo of completedTodos.value) {
+		deleteTodo.mutate(todo.id)
+	}
+}
+
+function formatTime(timestamp: number): string {
+	const date = new Date(timestamp)
+	const now = new Date()
+	if (date.toDateString() === now.toDateString()) {
+		return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+	}
+	return date.toLocaleDateString([], { month: 'short', day: 'numeric' })
+}
+</script>
+
+<template>
+	<div class="app">
+		<div class="header">
+			<h1>My Tasks</h1>
+			<div class="header-actions">
+				<div class="sync-badge">
+					<span :class="['sync-dot', syncStatus.status]" />
+					<span>{{ syncStatus.status }}</span>
+				</div>
+				<button v-if="isAuthenticated" type="button" class="auth-button" @click="signOut()">
+					{{ user?.email || 'Sign out' }}
+				</button>
+				<button v-else type="button" class="auth-button" @click="signInWithOAuth('google')">
+					Sign in
+				</button>
+			</div>
+		</div>
+
+		<div v-if="error" class="auth-error">{{ error }}</div>
+
+		<div class="stats">
+			<div class="stat-card">
+				<div class="label">Total</div>
+				<div class="value muted">{{ allTodos.length }}</div>
+			</div>
+			<div class="stat-card">
+				<div class="label">Remaining</div>
+				<div class="value warning">{{ activeTodos.length }}</div>
+			</div>
+			<div class="stat-card">
+				<div class="label">Done</div>
+				<div class="value success">{{ completedTodos.length }}</div>
+			</div>
+		</div>
+
+		<form class="add-form" @submit.prevent="handleSubmit">
+			<input v-model="input" type="text" placeholder="What needs to be done?" />
+			<button type="submit" :disabled="!input.trim()">Add</button>
+		</form>
+
+		<div class="filters">
+			<button
+				v-for="f in (['all', 'active', 'completed'] as const)"
+				:key="f"
+				type="button"
+				:class="['filter-btn', { active: filter === f }]"
+				@click="filter = f"
+			>
+				{{ f.charAt(0).toUpperCase() + f.slice(1) }}
+				<span class="badge">
+					{{
+						f === 'all'
+							? allTodos.length
+							: f === 'active'
+								? activeTodos.length
+								: completedTodos.length
+					}}
+				</span>
+			</button>
+		</div>
+
+		<div class="todo-list">
+			<div v-if="filteredTodos.length === 0" class="empty-state">
+				<template v-if="filter === 'all'">No tasks yet. Add one above!</template>
+				<template v-else-if="filter === 'active'">All caught up! No active tasks.</template>
+				<template v-else>No completed tasks yet.</template>
+			</div>
+			<div v-for="todo in filteredTodos" v-else :key="todo.id" class="todo-item">
+				<button
+					type="button"
+					:class="['toggle', { checked: todo.completed }]"
+					@click="toggleTodo.mutate(todo.id, { completed: !todo.completed })"
+				>
+					{{ todo.completed ? '✓' : '' }}
+				</button>
+				<span :class="['title', { done: todo.completed }]">{{ String(todo.title) }}</span>
+				<span v-if="todo.createdAt" class="time">{{ formatTime(Number(todo.createdAt)) }}</span>
+				<button type="button" class="delete-btn" @click="deleteTodo.mutate(todo.id)">×</button>
+			</div>
+		</div>
+
+		<div v-if="allTodos.length > 0" class="footer">
+			<span>{{ activeTodos.length }} item{{ activeTodos.length !== 1 ? 's' : '' }} left</span>
+			<button v-if="completedTodos.length > 0" type="button" @click="clearCompleted">
+				Clear completed
+			</button>
+		</div>
+
+		<p class="branding">Powered by Kora — offline-first, real-time sync</p>
+	</div>
+</template>

package/templates/vue-sync/src/auth.ts

@@ -0,0 +1,25 @@
+import { createKoraAuth } from '@korajs/auth'
+
+export const authServerUrl =
+	import.meta.env.VITE_AUTH_URL || `${window.location.protocol}//${window.location.host}`
+
+export const authClient = createKoraAuth({
+	serverUrl: authServerUrl,
+})
+
+export async function completeOAuthCallbackFromLocation(): Promise<void> {
+	const url = new URL(window.location.href)
+	const code = url.searchParams.get('code')
+	const state = url.searchParams.get('state')
+	const provider = url.searchParams.get('provider') || 'google'
+
+	if (!code || !state) {
+		return
+	}
+
+	await authClient.completeOAuthSignIn(provider, { code, state })
+	url.searchParams.delete('code')
+	url.searchParams.delete('state')
+	url.searchParams.delete('provider')
+	window.history.replaceState({}, document.title, `${url.pathname}${url.search}${url.hash}`)
+}