@korajs/cli 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korajs/cli",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Kora.js CLI tooling and project scaffolding",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -30,16 +30,6 @@
     "dist",
     "templates"
   ],
-  "dependencies": {
-    "citty": "^0.1.6",
-    "@korajs/core": "0.1.3"
-  },
-  "devDependencies": {
-    "typescript": "^5.7.3",
-    "tsup": "^8.3.6",
-    "vitest": "^3.0.4"
-  },
-  "license": "MIT",
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
@@ -48,5 +38,15 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome check src/ tests/",
     "clean": "rm -rf dist .turbo coverage"
-  }
-}
+  },
+  "dependencies": {
+    "@korajs/core": "workspace:*",
+    "citty": "^0.1.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "tsup": "^8.3.6",
+    "vitest": "^3.0.4"
+  },
+  "license": "MIT"
+}

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

@@ -0,0 +1,3 @@
+# No environment variables required for local-only mode.
+# To enable sync, see the README for instructions.
+# VITE_SYNC_URL=ws://localhost:3001

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

@@ -0,0 +1,53 @@
+# {{projectName}}
+
+An offline-first application built with [Kora.js](https://ehoneahobed.github.io/kora/).
+
+## Getting Started
+
+```bash
+npm run dev
+```
+
+- **App**: http://localhost:5173
+
+## Project Structure
+
+```
+src/
+  schema.ts        # Data schema definition
+  main.tsx         # App initialization and Kora setup
+  App.tsx          # Main application component
+  kora-worker.ts   # SQLite WASM web worker
+  index.css        # Styles
+kora.config.ts     # Kora configuration
+```
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Start dev server |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build |
+
+## Adding Sync
+
+To enable real-time sync across devices, update `src/main.tsx`:
+
+```typescript
+const app = createApp({
+  schema,
+  sync: {
+    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001',
+  },
+  // ...
+})
+```
+
+Then create a `server.ts` and install `@korajs/server`. See the [Sync Configuration guide](https://ehoneahobed.github.io/kora/guide/sync-configuration).
+
+## Learn More
+
+- [Documentation](https://ehoneahobed.github.io/kora/)
+- [Storage Configuration](https://ehoneahobed.github.io/kora/guide/storage-configuration)
+- [Schema Design](https://ehoneahobed.github.io/kora/guide/schema-design)

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

@@ -14,7 +14,14 @@
     "@korajs/store": "{{koraVersion}}",
     "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "yjs": "^13.6.30"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "protobufjs"
+    ]
   },
   "devDependencies": {
     "@korajs/cli": "{{koraVersion}}",

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

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

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

@@ -5,11 +5,12 @@ import { createRoot } from 'react-dom/client'
 import schema from './schema'
 import { App } from './App'
 import './index.css'
+import koraWorkerUrl from './kora-worker.ts?worker&url'
 
 const app = createApp({
   schema,
   store: {
-    workerUrl: new URL('./kora-worker.ts', import.meta.url),
+    workerUrl: koraWorkerUrl,
   },
   devtools: true,
 })

package/templates/react-basic/tsconfig.json

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

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

@@ -1,3 +1,5 @@
+import { existsSync, readdirSync, copyFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
@@ -27,8 +29,42 @@ function crossOriginIsolation(): Plugin {
   }
 }
 
+/**
+ * Fixes sqlite3 WASM assets in production builds:
+ * 1. Copies the hashed sqlite3.wasm to an unhashed name so Emscripten's locateFile works
+ * 2. Copies sqlite3-opfs-async-proxy.js from node_modules (not bundled by Vite since
+ *    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
+
+      // 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'))
+      }
+    },
+  }
+}
+
 export default defineConfig({
-  plugins: [react(), crossOriginIsolation()],
+  plugins: [react(), crossOriginIsolation(), sqliteWasmHotfix()],
+  worker: {
+    format: 'es',
+  },
   optimizeDeps: {
     exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
     include: ['yjs'],

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

@@ -0,0 +1,6 @@
+# Kora Sync Server
+# WebSocket URL for the sync server (used by the client)
+VITE_SYNC_URL=ws://localhost:3001
+
+# Sync server port
+PORT=3001

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

@@ -0,0 +1,63 @@
+# {{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        # Data schema definition
+  main.tsx         # App initialization and Kora setup
+  App.tsx          # Main application component
+  kora-worker.ts   # SQLite WASM web worker
+  index.css        # Styles
+server.ts          # Kora sync server
+kora.config.ts     # Kora configuration
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VITE_SYNC_URL` | `ws://localhost:3001` | WebSocket URL for the sync server |
+| `PORT` | `3001` | Sync server port |
+
+## 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/react-sync/package.json.hbs

@@ -7,6 +7,7 @@
     "dev": "kora dev",
     "dev:server": "tsx server.ts",
     "build": "tsc && vite build",
+    "start": "node --import tsx server.ts",
     "preview": "vite preview"
   },
   "dependencies": {
@@ -15,13 +16,23 @@
     "@korajs/store": "{{koraVersion}}",
     "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "ws": "^8.18.0",
+    "yjs": "^13.6.30"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild",
+      "protobufjs"
+    ]
   },
   "devDependencies": {
     "@korajs/cli": "{{koraVersion}}",
     "@korajs/server": "{{koraVersion}}",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@types/ws": "^8.5.0",
     "@vitejs/plugin-react": "^4.3.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",

package/templates/react-sync/server.ts

@@ -1,4 +1,4 @@
-import { createKoraServer, createSqliteServerStore } from '@korajs/server'
+import { createProductionServer, createSqliteServerStore } from '@korajs/server'
 
 // SQLite persists data to disk — survives server restarts
 const store = createSqliteServerStore({ filename: './kora-server.db' })
@@ -12,11 +12,15 @@ const store = createSqliteServerStore({ filename: './kora-server.db' })
 //   connectionString: 'postgresql://user:password@localhost:5432/mydb',
 // })
 
-const server = createKoraServer({
+// 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: 3001,
+  port: Number(process.env.PORT) || 3001,
+  staticDir: './dist',
+  syncPath: '/kora-sync',
 })
 
-server.start().then(() => {
-  console.log('Kora sync server running on ws://localhost:3001')
+server.start().then((url) => {
+  console.log(`Kora app running at ${url}`)
 })

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

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

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

@@ -5,14 +5,21 @@ import { createRoot } from 'react-dom/client'
 import schema from './schema'
 import { App } from './App'
 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: 'ws://localhost:3001',
+    url: syncUrl,
   },
   store: {
-    workerUrl: new URL('./kora-worker.ts', import.meta.url),
+    workerUrl: koraWorkerUrl,
   },
   devtools: true,
 })

package/templates/react-sync/tsconfig.json

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

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

@@ -1,3 +1,5 @@
+import { existsSync, readdirSync, copyFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
@@ -27,8 +29,42 @@ function crossOriginIsolation(): Plugin {
   }
 }
 
+/**
+ * Fixes sqlite3 WASM assets in production builds:
+ * 1. Copies the hashed sqlite3.wasm to an unhashed name so Emscripten's locateFile works
+ * 2. Copies sqlite3-opfs-async-proxy.js from node_modules (not bundled by Vite since
+ *    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
+
+      // 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'))
+      }
+    },
+  }
+}
+
 export default defineConfig({
-  plugins: [react(), crossOriginIsolation()],
+  plugins: [react(), crossOriginIsolation(), sqliteWasmHotfix()],
+  worker: {
+    format: 'es',
+  },
   optimizeDeps: {
     exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
     include: ['yjs'],
@@ -36,4 +72,14 @@ export default defineConfig({
   resolve: {
     dedupe: ['yjs'],
   },
+  server: {
+    allowedHosts: true,
+    proxy: {
+      '/kora-sync': {
+        target: 'ws://localhost:3001',
+        ws: true,
+        rewriteWsOrigin: true,
+      },
+    },
+  },
 })

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

@@ -0,0 +1,3 @@
+# No environment variables required for local-only mode.
+# To enable sync, see the README for instructions.
+# VITE_SYNC_URL=ws://localhost:3001

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

@@ -0,0 +1,53 @@
+# {{projectName}}
+
+An offline-first application built with [Kora.js](https://ehoneahobed.github.io/kora/).
+
+## Getting Started
+
+```bash
+npm run dev
+```
+
+- **App**: http://localhost:5173
+
+## Project Structure
+
+```
+src/
+  schema.ts        # Data schema definition
+  main.tsx         # App initialization and Kora setup
+  App.tsx          # Main application component
+  kora-worker.ts   # SQLite WASM web worker
+  index.css        # Styles
+kora.config.ts     # Kora configuration
+```
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Start dev server |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build |
+
+## Adding Sync
+
+To enable real-time sync across devices, update `src/main.tsx`:
+
+```typescript
+const app = createApp({
+  schema,
+  sync: {
+    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001',
+  },
+  // ...
+})
+```
+
+Then create a `server.ts` and install `@korajs/server`. See the [Sync Configuration guide](https://ehoneahobed.github.io/kora/guide/sync-configuration).
+
+## Learn More
+
+- [Documentation](https://ehoneahobed.github.io/kora/)
+- [Storage Configuration](https://ehoneahobed.github.io/kora/guide/storage-configuration)
+- [Schema Design](https://ehoneahobed.github.io/kora/guide/schema-design)

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

@@ -15,7 +15,14 @@
     "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
     "lucide-react": "^0.468.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "yjs": "^13.6.30"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "protobufjs"
+    ]
   },
   "devDependencies": {
     "@korajs/cli": "{{koraVersion}}",

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

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

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

@@ -5,11 +5,12 @@ import { createRoot } from 'react-dom/client'
 import schema from './schema'
 import { App } from './App'
 import './index.css'
+import koraWorkerUrl from './kora-worker.ts?worker&url'
 
 const app = createApp({
   schema,
   store: {
-    workerUrl: new URL('./kora-worker.ts', import.meta.url),
+    workerUrl: koraWorkerUrl,
   },
   devtools: true,
 })

package/templates/react-tailwind/tsconfig.json

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

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

@@ -1,3 +1,5 @@
+import { existsSync, readdirSync, copyFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
 import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
@@ -28,8 +30,42 @@ function crossOriginIsolation(): Plugin {
   }
 }
 
+/**
+ * Fixes sqlite3 WASM assets in production builds:
+ * 1. Copies the hashed sqlite3.wasm to an unhashed name so Emscripten's locateFile works
+ * 2. Copies sqlite3-opfs-async-proxy.js from node_modules (not bundled by Vite since
+ *    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
+
+      // 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'))
+      }
+    },
+  }
+}
+
 export default defineConfig({
-  plugins: [react(), tailwindcss(), crossOriginIsolation()],
+  plugins: [react(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+  worker: {
+    format: 'es',
+  },
   optimizeDeps: {
     exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
     include: ['yjs'],

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

@@ -0,0 +1,6 @@
+# Kora Sync Server
+# WebSocket URL for the sync server (used by the client)
+VITE_SYNC_URL=ws://localhost:3001
+
+# Sync server port
+PORT=3001

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

@@ -0,0 +1,63 @@
+# {{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        # Data schema definition
+  main.tsx         # App initialization and Kora setup
+  App.tsx          # Main application component
+  kora-worker.ts   # SQLite WASM web worker
+  index.css        # Styles
+server.ts          # Kora sync server
+kora.config.ts     # Kora configuration
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VITE_SYNC_URL` | `ws://localhost:3001` | WebSocket URL for the sync server |
+| `PORT` | `3001` | Sync server port |
+
+## 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/react-tailwind-sync/package.json.hbs

@@ -7,6 +7,7 @@
     "dev": "kora dev",
     "dev:server": "tsx server.ts",
     "build": "tsc && vite build",
+    "start": "node --import tsx server.ts",
     "preview": "vite preview"
   },
   "dependencies": {
@@ -16,7 +17,16 @@
     "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
     "lucide-react": "^0.468.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "ws": "^8.18.0",
+    "yjs": "^13.6.30"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild",
+      "protobufjs"
+    ]
   },
   "devDependencies": {
     "@korajs/cli": "{{koraVersion}}",
@@ -24,6 +34,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@types/ws": "^8.5.0",
     "@vitejs/plugin-react": "^4.3.0",
     "tailwindcss": "^4.0.0",
     "tsx": "^4.19.0",

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

@@ -1,4 +1,4 @@
-import { createKoraServer, createSqliteServerStore } from '@korajs/server'
+import { createProductionServer, createSqliteServerStore } from '@korajs/server'
 
 // SQLite persists data to disk — survives server restarts
 const store = createSqliteServerStore({ filename: './kora-server.db' })
@@ -12,11 +12,15 @@ const store = createSqliteServerStore({ filename: './kora-server.db' })
 //   connectionString: 'postgresql://user:password@localhost:5432/mydb',
 // })
 
-const server = createKoraServer({
+// 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: 3001,
+  port: Number(process.env.PORT) || 3001,
+  staticDir: './dist',
+  syncPath: '/kora-sync',
 })
 
-server.start().then(() => {
-  console.log('Kora sync server running on ws://localhost:3001')
+server.start().then((url) => {
+  console.log(`Kora app running at ${url}`)
 })

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

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

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

@@ -5,14 +5,21 @@ import { createRoot } from 'react-dom/client'
 import schema from './schema'
 import { App } from './App'
 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: 'ws://localhost:3001',
+    url: syncUrl,
   },
   store: {
-    workerUrl: new URL('./kora-worker.ts', import.meta.url),
+    workerUrl: koraWorkerUrl,
   },
   devtools: true,
 })

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

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

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

@@ -1,3 +1,5 @@
+import { existsSync, readdirSync, copyFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
 import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
@@ -28,8 +30,42 @@ function crossOriginIsolation(): Plugin {
   }
 }
 
+/**
+ * Fixes sqlite3 WASM assets in production builds:
+ * 1. Copies the hashed sqlite3.wasm to an unhashed name so Emscripten's locateFile works
+ * 2. Copies sqlite3-opfs-async-proxy.js from node_modules (not bundled by Vite since
+ *    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
+
+      // 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'))
+      }
+    },
+  }
+}
+
 export default defineConfig({
-  plugins: [react(), tailwindcss(), crossOriginIsolation()],
+  plugins: [react(), tailwindcss(), crossOriginIsolation(), sqliteWasmHotfix()],
+  worker: {
+    format: 'es',
+  },
   optimizeDeps: {
     exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
     include: ['yjs'],
@@ -37,4 +73,14 @@ export default defineConfig({
   resolve: {
     dedupe: ['yjs'],
   },
+  server: {
+    allowedHosts: true,
+    proxy: {
+      '/kora-sync': {
+        target: 'ws://localhost:3001',
+        ws: true,
+        rewriteWsOrigin: true,
+      },
+    },
+  },
 })