@korajs/cli 0.5.0 → 1.0.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (200) hide show
  1. package/LICENSE +21 -0
  2. package/dist/bin.cjs +2656 -207
  3. package/dist/bin.cjs.map +1 -1
  4. package/dist/bin.js +152 -96
  5. package/dist/bin.js.map +1 -1
  6. package/dist/chunk-5NI2FEQL.js +92 -0
  7. package/dist/chunk-5NI2FEQL.js.map +1 -0
  8. package/dist/chunk-6C4BHSRA.js +82 -0
  9. package/dist/chunk-6C4BHSRA.js.map +1 -0
  10. package/dist/{chunk-3WNFM3QB.js → chunk-B5YS4STN.js} +78 -99
  11. package/dist/chunk-B5YS4STN.js.map +1 -0
  12. package/dist/{chunk-PSRM56B7.js → chunk-BWTKRKNJ.js} +60 -7
  13. package/dist/chunk-BWTKRKNJ.js.map +1 -0
  14. package/dist/{chunk-SOTZIWIF.js → chunk-EOWLAAIV.js} +5 -3
  15. package/dist/{chunk-SOTZIWIF.js.map → chunk-EOWLAAIV.js.map} +1 -1
  16. package/dist/create.cjs +82 -7
  17. package/dist/create.cjs.map +1 -1
  18. package/dist/create.js +3 -2
  19. package/dist/create.js.map +1 -1
  20. package/dist/index.cjs +65 -3
  21. package/dist/index.cjs.map +1 -1
  22. package/dist/index.d.cts +3 -3
  23. package/dist/index.d.ts +3 -3
  24. package/dist/index.js +3 -2
  25. package/dist/lab-manager-KUDII6BT.js +280 -0
  26. package/dist/lab-manager-KUDII6BT.js.map +1 -0
  27. package/dist/schema-loader-GGHECMTM.js +9 -0
  28. package/dist/schema-loader-GGHECMTM.js.map +1 -0
  29. package/dist/spectator-manager-E2LH2P54.js +142 -0
  30. package/dist/spectator-manager-E2LH2P54.js.map +1 -0
  31. package/dist/studio-server-NIFKZI4F.js +1738 -0
  32. package/dist/studio-server-NIFKZI4F.js.map +1 -0
  33. package/package.json +8 -6
  34. package/templates/react-basic/AGENTS.md +87 -0
  35. package/templates/react-sync/AGENTS.md +87 -0
  36. package/templates/react-sync/src/App.tsx +8 -0
  37. package/templates/react-sync/src/index.css +11 -0
  38. package/templates/react-tailwind/AGENTS.md +87 -0
  39. package/templates/react-tailwind-sync/AGENTS.md +87 -0
  40. package/templates/react-tailwind-sync/src/App.tsx +28 -0
  41. package/templates/svelte-basic/.env.example +3 -0
  42. package/templates/svelte-basic/AGENTS.md +76 -0
  43. package/templates/svelte-basic/README.md.hbs +62 -0
  44. package/templates/svelte-basic/index.html.hbs +12 -0
  45. package/templates/svelte-basic/kora.config.ts +12 -0
  46. package/templates/svelte-basic/package.json.hbs +27 -0
  47. package/templates/svelte-basic/src/App.svelte +127 -0
  48. package/templates/svelte-basic/src/Root.svelte +14 -0
  49. package/templates/svelte-basic/src/index.css +287 -0
  50. package/templates/svelte-basic/src/kora-worker.ts +9 -0
  51. package/templates/svelte-basic/src/main.ts +16 -0
  52. package/templates/svelte-basic/src/modules/todos/todo.mutations.ts +25 -0
  53. package/templates/svelte-basic/src/modules/todos/todo.queries.ts +5 -0
  54. package/templates/svelte-basic/src/modules/todos/todo.schema.ts +10 -0
  55. package/templates/svelte-basic/src/modules/todos/useTodos.ts +25 -0
  56. package/templates/svelte-basic/src/schema.ts +9 -0
  57. package/templates/svelte-basic/src/vite-env.d.ts +12 -0
  58. package/templates/svelte-basic/svelte.config.js +5 -0
  59. package/templates/svelte-basic/tsconfig.json.hbs +14 -0
  60. package/templates/svelte-basic/vite.config.ts +52 -0
  61. package/templates/svelte-sync/.env.example +25 -0
  62. package/templates/svelte-sync/AGENTS.md +76 -0
  63. package/templates/svelte-sync/README.md.hbs +105 -0
  64. package/templates/svelte-sync/index.html.hbs +12 -0
  65. package/templates/svelte-sync/kora.config.ts +17 -0
  66. package/templates/svelte-sync/package.json.hbs +43 -0
  67. package/templates/svelte-sync/server.ts +90 -0
  68. package/templates/svelte-sync/src/App.svelte +150 -0
  69. package/templates/svelte-sync/src/Root.svelte +22 -0
  70. package/templates/svelte-sync/src/auth.ts +25 -0
  71. package/templates/svelte-sync/src/index.css +339 -0
  72. package/templates/svelte-sync/src/kora-worker.ts +9 -0
  73. package/templates/svelte-sync/src/main.ts +32 -0
  74. package/templates/svelte-sync/src/modules/todos/todo.mutations.ts +25 -0
  75. package/templates/svelte-sync/src/modules/todos/todo.queries.ts +5 -0
  76. package/templates/svelte-sync/src/modules/todos/todo.schema.ts +10 -0
  77. package/templates/svelte-sync/src/modules/todos/useTodos.ts +25 -0
  78. package/templates/svelte-sync/src/schema.ts +9 -0
  79. package/templates/svelte-sync/src/vite-env.d.ts +21 -0
  80. package/templates/svelte-sync/svelte.config.js +5 -0
  81. package/templates/svelte-sync/tsconfig.json.hbs +14 -0
  82. package/templates/svelte-sync/vite.config.ts +79 -0
  83. package/templates/svelte-tailwind/AGENTS.md +76 -0
  84. package/templates/svelte-tailwind/README.md.hbs +62 -0
  85. package/templates/svelte-tailwind/index.html.hbs +12 -0
  86. package/templates/svelte-tailwind/kora.config.ts +12 -0
  87. package/templates/svelte-tailwind/package.json.hbs +30 -0
  88. package/templates/svelte-tailwind/src/App.svelte +75 -0
  89. package/templates/svelte-tailwind/src/Root.svelte +14 -0
  90. package/templates/svelte-tailwind/src/index.css +7 -0
  91. package/templates/svelte-tailwind/src/kora-worker.ts +9 -0
  92. package/templates/svelte-tailwind/src/main.ts +16 -0
  93. package/templates/svelte-tailwind/src/modules/todos/todo.mutations.ts +25 -0
  94. package/templates/svelte-tailwind/src/modules/todos/todo.queries.ts +5 -0
  95. package/templates/svelte-tailwind/src/modules/todos/todo.schema.ts +10 -0
  96. package/templates/svelte-tailwind/src/modules/todos/useTodos.ts +25 -0
  97. package/templates/svelte-tailwind/src/schema.ts +9 -0
  98. package/templates/svelte-tailwind/src/vite-env.d.ts +12 -0
  99. package/templates/svelte-tailwind/svelte.config.js +5 -0
  100. package/templates/svelte-tailwind/tsconfig.json.hbs +14 -0
  101. package/templates/svelte-tailwind/vite.config.ts +53 -0
  102. package/templates/svelte-tailwind-sync/.env.example +25 -0
  103. package/templates/svelte-tailwind-sync/AGENTS.md +76 -0
  104. package/templates/svelte-tailwind-sync/README.md.hbs +105 -0
  105. package/templates/svelte-tailwind-sync/index.html.hbs +12 -0
  106. package/templates/svelte-tailwind-sync/kora.config.ts +17 -0
  107. package/templates/svelte-tailwind-sync/package.json.hbs +46 -0
  108. package/templates/svelte-tailwind-sync/server.ts +90 -0
  109. package/templates/svelte-tailwind-sync/src/App.svelte +192 -0
  110. package/templates/svelte-tailwind-sync/src/Root.svelte +26 -0
  111. package/templates/svelte-tailwind-sync/src/auth.ts +25 -0
  112. package/templates/svelte-tailwind-sync/src/index.css +7 -0
  113. package/templates/svelte-tailwind-sync/src/kora-worker.ts +9 -0
  114. package/templates/svelte-tailwind-sync/src/main.ts +32 -0
  115. package/templates/svelte-tailwind-sync/src/modules/todos/todo.mutations.ts +25 -0
  116. package/templates/svelte-tailwind-sync/src/modules/todos/todo.queries.ts +5 -0
  117. package/templates/svelte-tailwind-sync/src/modules/todos/todo.schema.ts +10 -0
  118. package/templates/svelte-tailwind-sync/src/modules/todos/useTodos.ts +25 -0
  119. package/templates/svelte-tailwind-sync/src/schema.ts +9 -0
  120. package/templates/svelte-tailwind-sync/src/vite-env.d.ts +21 -0
  121. package/templates/svelte-tailwind-sync/svelte.config.js +5 -0
  122. package/templates/svelte-tailwind-sync/tsconfig.json.hbs +14 -0
  123. package/templates/svelte-tailwind-sync/vite.config.ts +80 -0
  124. package/templates/tauri-react/AGENTS.md +91 -0
  125. package/templates/vue-basic/AGENTS.md +84 -0
  126. package/templates/vue-basic/README.md.hbs +62 -0
  127. package/templates/vue-basic/index.html.hbs +12 -0
  128. package/templates/vue-basic/kora.config.ts +12 -0
  129. package/templates/vue-basic/package.json.hbs +26 -0
  130. package/templates/vue-basic/src/App.vue +117 -0
  131. package/templates/vue-basic/src/index.css +287 -0
  132. package/templates/vue-basic/src/kora-worker.ts +9 -0
  133. package/templates/vue-basic/src/main.ts +20 -0
  134. package/templates/vue-basic/src/modules/todos/todo.mutations.ts +25 -0
  135. package/templates/vue-basic/src/modules/todos/todo.queries.ts +5 -0
  136. package/templates/vue-basic/src/modules/todos/todo.schema.ts +10 -0
  137. package/templates/vue-basic/src/modules/todos/useTodos.ts +32 -0
  138. package/templates/vue-basic/src/schema.ts +9 -0
  139. package/templates/vue-basic/src/vite-env.d.ts +17 -0
  140. package/templates/vue-basic/tsconfig.json.hbs +15 -0
  141. package/templates/vue-basic/vite.config.ts +69 -0
  142. package/templates/vue-sync/.env.example +25 -0
  143. package/templates/vue-sync/AGENTS.md +84 -0
  144. package/templates/vue-sync/README.md.hbs +105 -0
  145. package/templates/vue-sync/index.html.hbs +12 -0
  146. package/templates/vue-sync/kora.config.ts +17 -0
  147. package/templates/vue-sync/package.json.hbs +42 -0
  148. package/templates/vue-sync/server.ts +90 -0
  149. package/templates/vue-sync/src/App.vue +135 -0
  150. package/templates/vue-sync/src/auth.ts +25 -0
  151. package/templates/vue-sync/src/index.css +339 -0
  152. package/templates/vue-sync/src/kora-worker.ts +9 -0
  153. package/templates/vue-sync/src/main.ts +47 -0
  154. package/templates/vue-sync/src/modules/todos/todo.mutations.ts +25 -0
  155. package/templates/vue-sync/src/modules/todos/todo.queries.ts +5 -0
  156. package/templates/vue-sync/src/modules/todos/todo.schema.ts +10 -0
  157. package/templates/vue-sync/src/modules/todos/useTodos.ts +32 -0
  158. package/templates/vue-sync/src/schema.ts +9 -0
  159. package/templates/vue-sync/src/vite-env.d.ts +26 -0
  160. package/templates/vue-sync/tsconfig.json.hbs +15 -0
  161. package/templates/vue-sync/vite.config.ts +79 -0
  162. package/templates/vue-tailwind/AGENTS.md +84 -0
  163. package/templates/vue-tailwind/README.md.hbs +62 -0
  164. package/templates/vue-tailwind/index.html.hbs +12 -0
  165. package/templates/vue-tailwind/kora.config.ts +12 -0
  166. package/templates/vue-tailwind/package.json.hbs +29 -0
  167. package/templates/vue-tailwind/src/App.vue +135 -0
  168. package/templates/vue-tailwind/src/index.css +7 -0
  169. package/templates/vue-tailwind/src/kora-worker.ts +9 -0
  170. package/templates/vue-tailwind/src/main.ts +31 -0
  171. package/templates/vue-tailwind/src/modules/todos/todo.mutations.ts +25 -0
  172. package/templates/vue-tailwind/src/modules/todos/todo.queries.ts +5 -0
  173. package/templates/vue-tailwind/src/modules/todos/todo.schema.ts +10 -0
  174. package/templates/vue-tailwind/src/modules/todos/useTodos.ts +32 -0
  175. package/templates/vue-tailwind/src/schema.ts +9 -0
  176. package/templates/vue-tailwind/src/vite-env.d.ts +17 -0
  177. package/templates/vue-tailwind/tsconfig.json.hbs +15 -0
  178. package/templates/vue-tailwind/vite.config.ts +70 -0
  179. package/templates/vue-tailwind-sync/.env.example +25 -0
  180. package/templates/vue-tailwind-sync/AGENTS.md +84 -0
  181. package/templates/vue-tailwind-sync/README.md.hbs +105 -0
  182. package/templates/vue-tailwind-sync/index.html.hbs +12 -0
  183. package/templates/vue-tailwind-sync/kora.config.ts +17 -0
  184. package/templates/vue-tailwind-sync/package.json.hbs +45 -0
  185. package/templates/vue-tailwind-sync/server.ts +90 -0
  186. package/templates/vue-tailwind-sync/src/App.vue +245 -0
  187. package/templates/vue-tailwind-sync/src/auth.ts +25 -0
  188. package/templates/vue-tailwind-sync/src/index.css +7 -0
  189. package/templates/vue-tailwind-sync/src/kora-worker.ts +9 -0
  190. package/templates/vue-tailwind-sync/src/main.ts +56 -0
  191. package/templates/vue-tailwind-sync/src/modules/todos/todo.mutations.ts +25 -0
  192. package/templates/vue-tailwind-sync/src/modules/todos/todo.queries.ts +5 -0
  193. package/templates/vue-tailwind-sync/src/modules/todos/todo.schema.ts +10 -0
  194. package/templates/vue-tailwind-sync/src/modules/todos/useTodos.ts +32 -0
  195. package/templates/vue-tailwind-sync/src/schema.ts +9 -0
  196. package/templates/vue-tailwind-sync/src/vite-env.d.ts +26 -0
  197. package/templates/vue-tailwind-sync/tsconfig.json.hbs +15 -0
  198. package/templates/vue-tailwind-sync/vite.config.ts +80 -0
  199. package/dist/chunk-3WNFM3QB.js.map +0 -1
  200. package/dist/chunk-PSRM56B7.js.map +0 -1
@@ -0,0 +1,32 @@
1
+ import { createKoraAuthSync } from '@korajs/auth'
2
+ import { createApp as createKoraApp } from 'korajs'
3
+ import { mount } from 'svelte'
4
+ import Root from './Root.svelte'
5
+ import { authClient, completeOAuthCallbackFromLocation } from './auth'
6
+ import schema from './schema'
7
+ import './index.css'
8
+ import koraWorkerUrl from './kora-worker.ts?worker&url'
9
+
10
+ const syncUrl =
11
+ import.meta.env.VITE_SYNC_URL ||
12
+ `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/kora-sync`
13
+
14
+ const kora = createKoraApp({
15
+ schema,
16
+ sync: {
17
+ url: syncUrl,
18
+ authClient: createKoraAuthSync({ authClient, schema }),
19
+ },
20
+ store: {
21
+ workerUrl: koraWorkerUrl,
22
+ },
23
+ devtools: true,
24
+ })
25
+
26
+ kora.ready.then(() => kora.sync?.connect())
27
+
28
+ void completeOAuthCallbackFromLocation().catch((error) => {
29
+ console.error('[Kora Auth] OAuth callback failed:', error)
30
+ })
31
+
32
+ mount(Root, { target: document.getElementById('app')!, props: { kora, authClient } })
@@ -0,0 +1,25 @@
1
+ import type { CollectionAccessor } from 'korajs'
2
+
3
+ export interface CreateTodoInput {
4
+ title: string
5
+ }
6
+
7
+ export interface UpdateTodoStatusInput {
8
+ completed: boolean
9
+ }
10
+
11
+ export function createTodo(todos: CollectionAccessor, data: CreateTodoInput) {
12
+ return todos.insert({ title: data.title })
13
+ }
14
+
15
+ export function updateTodoStatus(
16
+ todos: CollectionAccessor,
17
+ id: string,
18
+ data: UpdateTodoStatusInput,
19
+ ) {
20
+ return todos.update(id, { completed: data.completed })
21
+ }
22
+
23
+ export function deleteTodo(todos: CollectionAccessor, id: string) {
24
+ return todos.delete(id)
25
+ }
@@ -0,0 +1,5 @@
1
+ import type { CollectionAccessor } from 'korajs'
2
+
3
+ export function orderedTodos(todos: CollectionAccessor) {
4
+ return todos.where({}).orderBy('createdAt', 'desc')
5
+ }
@@ -0,0 +1,10 @@
1
+ import { t } from 'korajs'
2
+
3
+ export const todos = {
4
+ fields: {
5
+ title: t.string(),
6
+ completed: t.boolean().default(false),
7
+ createdAt: t.timestamp().auto(),
8
+ },
9
+ indexes: ['completed', 'createdAt'],
10
+ }
@@ -0,0 +1,25 @@
1
+ import { createMutation, createQueryStore, getCollection } from '@korajs/svelte'
2
+ import { derived } from 'svelte/store'
3
+ import {
4
+ type CreateTodoInput,
5
+ type UpdateTodoStatusInput,
6
+ createTodo,
7
+ deleteTodo,
8
+ updateTodoStatus,
9
+ } from './todo.mutations'
10
+ import { orderedTodos } from './todo.queries'
11
+
12
+ export function createTodosStores() {
13
+ const todos = getCollection('todos')
14
+ const allTodos = createQueryStore(orderedTodos(todos))
15
+ const addTodo = createMutation((data: CreateTodoInput) => createTodo(todos, data))
16
+ const toggleTodo = createMutation((id: string, data: UpdateTodoStatusInput) =>
17
+ updateTodoStatus(todos, id, data),
18
+ )
19
+ const removeTodo = createMutation((id: string) => deleteTodo(todos, id))
20
+
21
+ const activeTodos = derived(allTodos, ($all) => $all.filter((todo) => !todo.completed))
22
+ const completedTodos = derived(allTodos, ($all) => $all.filter((todo) => !!todo.completed))
23
+
24
+ return { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo: removeTodo }
25
+ }
@@ -0,0 +1,9 @@
1
+ import { defineSchema } from 'korajs'
2
+ import { todos } from './modules/todos/todo.schema'
3
+
4
+ export default defineSchema({
5
+ version: 1,
6
+ collections: {
7
+ todos,
8
+ },
9
+ })
@@ -0,0 +1,21 @@
1
+ /// <reference types="svelte" />
2
+ /// <reference types="vite/client" />
3
+
4
+ interface ImportMetaEnv {
5
+ readonly VITE_SYNC_URL?: string
6
+ readonly VITE_AUTH_URL?: string
7
+ }
8
+
9
+ interface ImportMeta {
10
+ readonly env: ImportMetaEnv
11
+ }
12
+
13
+ declare module '*?worker&url' {
14
+ const url: string
15
+ export default url
16
+ }
17
+
18
+ declare module '*?url' {
19
+ const url: string
20
+ export default url
21
+ }
@@ -0,0 +1,5 @@
1
+ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
2
+
3
+ export default {
4
+ preprocess: vitePreprocess(),
5
+ }
@@ -0,0 +1,14 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2022",
4
+ "module": "ESNext",
5
+ "moduleResolution": "bundler",
6
+ "strict": true,
7
+ "noUncheckedIndexedAccess": true,
8
+ "esModuleInterop": true,
9
+ "skipLibCheck": true,
10
+ "types": ["vite/client"]
11
+ },
12
+ "include": ["src/**/*.ts", "src/**/*.svelte"],
13
+ "exclude": ["node_modules"]
14
+ }
@@ -0,0 +1,79 @@
1
+ import { copyFileSync, existsSync, readdirSync } from 'node:fs'
2
+ import { join, resolve } from 'node:path'
3
+ import { svelte } from '@sveltejs/vite-plugin-svelte'
4
+ import type { Plugin } from 'vite'
5
+ import { defineConfig } from 'vite'
6
+
7
+ function crossOriginIsolation(): Plugin {
8
+ return {
9
+ name: 'cross-origin-isolation',
10
+ configureServer(server) {
11
+ server.middlewares.use((_req, res, next) => {
12
+ res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
13
+ res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
14
+ next()
15
+ })
16
+ },
17
+ configurePreviewServer(server) {
18
+ server.middlewares.use((_req, res, next) => {
19
+ res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
20
+ res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
21
+ next()
22
+ })
23
+ },
24
+ }
25
+ }
26
+
27
+ function sqliteWasmHotfix(): Plugin {
28
+ return {
29
+ name: 'sqlite-wasm-hotfix',
30
+ apply: 'build',
31
+ closeBundle() {
32
+ const assetsDir = resolve('dist', 'assets')
33
+ if (!existsSync(assetsDir)) return
34
+
35
+ for (const file of readdirSync(assetsDir)) {
36
+ if (/^sqlite3-.+\.wasm$/.test(file)) {
37
+ copyFileSync(join(assetsDir, file), join(assetsDir, 'sqlite3.wasm'))
38
+ break
39
+ }
40
+ }
41
+
42
+ const proxyFile = resolve(
43
+ 'node_modules',
44
+ '@sqlite.org',
45
+ 'sqlite-wasm',
46
+ 'sqlite-wasm',
47
+ 'jswasm',
48
+ 'sqlite3-opfs-async-proxy.js',
49
+ )
50
+ if (existsSync(proxyFile)) {
51
+ copyFileSync(proxyFile, join(assetsDir, 'sqlite3-opfs-async-proxy.js'))
52
+ }
53
+ },
54
+ }
55
+ }
56
+
57
+ export default defineConfig({
58
+ plugins: [svelte(), crossOriginIsolation(), sqliteWasmHotfix()],
59
+ worker: {
60
+ format: 'es',
61
+ },
62
+ optimizeDeps: {
63
+ exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
64
+ include: ['yjs'],
65
+ },
66
+ resolve: {
67
+ dedupe: ['yjs'],
68
+ },
69
+ server: {
70
+ allowedHosts: true,
71
+ proxy: {
72
+ '/kora-sync': {
73
+ target: 'ws://localhost:3001',
74
+ ws: true,
75
+ rewriteWsOrigin: true,
76
+ },
77
+ },
78
+ },
79
+ })
@@ -0,0 +1,76 @@
1
+ # AGENTS.md
2
+
3
+ Guidance for AI coding agents working in this project. Humans: this is useful for you too.
4
+
5
+ ## What this project is
6
+
7
+ This is a **Kora.js** application: an offline-first app where all data lives in a local SQLite database (WASM + OPFS in the browser) and optionally syncs across devices through a Kora sync server. Offline is the normal state, not an error state. Full docs: https://korajs.dev and machine-readable index at https://korajs.dev/llms.txt (complete docs in one file: https://korajs.dev/llms-full.txt).
8
+
9
+ ## Golden rules
10
+
11
+ 1. **The schema is the source of truth.** All collections are defined in `src/schema.ts` with `defineSchema` and the `t.*` field builders. To add or change data shapes, edit the schema first; types flow from it automatically. Never hand-write types for records.
12
+ 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.
13
+ 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.
14
+ 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.
15
+ 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.
16
+ 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.
17
+ 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.
18
+
19
+ ## Data API cheat sheet
20
+
21
+ ```ts
22
+ await app.ready
23
+ const rec = await app.todos.insert({ title: 'x' }) // defaults and .auto() fields applied
24
+ await app.todos.update(rec.id, { completed: true }) // partial update, changed fields only
25
+ await app.todos.delete(rec.id)
26
+ const one = await app.todos.findById(rec.id)
27
+ const unsubscribe = app.todos
28
+ .where({ completed: false })
29
+ .orderBy('createdAt', 'desc')
30
+ .subscribe((rows) => {/* fires immediately, then on every change */})
31
+ ```
32
+
33
+ Schema example (`src/schema.ts`):
34
+
35
+ ```ts
36
+ import { defineSchema, t } from 'korajs'
37
+
38
+ export default defineSchema({
39
+ version: 1,
40
+ collections: {
41
+ todos: {
42
+ fields: {
43
+ title: t.string(),
44
+ completed: t.boolean().default(false),
45
+ tags: t.array(t.string()).default([]),
46
+ priority: t.enum(['low', 'medium', 'high']).default('medium'),
47
+ createdAt: t.timestamp().auto(), // set automatically; never pass it on insert
48
+ },
49
+ indexes: ['completed', 'createdAt'],
50
+ },
51
+ },
52
+ })
53
+ ```
54
+
55
+ If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
56
+
57
+ ## Project conventions
58
+
59
+ - 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).
60
+ - 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.
61
+ - `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
62
+
63
+ ## Commands
64
+
65
+ - `npm run dev` starts everything: Vite dev server (port 5173), local sync server (port 3001), and the schema watcher.
66
+ - `npm run build` type-checks and builds for production.
67
+ - `npx kora doctor` diagnoses a broken setup.
68
+ - DevTools overlay: press Ctrl+Shift+K (Cmd+Shift+K on macOS) in the running app to inspect operations, merges, and sync status.
69
+
70
+ ## Sync and auth
71
+
72
+ Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })`. In dev, the sync URL is derived from the page host and proxied by Vite; in production set `VITE_SYNC_URL`. Auth (if present in this template) uses `@korajs/auth`; the client is created in `src/auth.ts`. Local writes work without sign-in; sync requires the server to accept the connection.
73
+
74
+ ## Svelte bindings
75
+
76
+ 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.
@@ -0,0 +1,62 @@
1
+ # {{projectName}}
2
+
3
+ An offline-first application built with [Kora.js](https://ehoneahobed.github.io/kora/).
4
+
5
+ ## Getting Started
6
+
7
+ ```bash
8
+ npm run dev
9
+ ```
10
+
11
+ - **App**: http://localhost:5173
12
+
13
+ ## Project Structure
14
+
15
+ ```
16
+ src/
17
+ schema.ts # Schema entry point
18
+ main.tsx # App initialization and Kora setup
19
+ App.tsx # Main application component
20
+ modules/
21
+ todos/
22
+ todo.schema.ts # Todo collection definition
23
+ todo.queries.ts # Reusable todo query builders
24
+ todo.mutations.ts # Todo mutation helpers
25
+ useTodos.ts # React hook connecting todos to the UI
26
+ kora-worker.ts # SQLite WASM web worker
27
+ index.css # Styles
28
+ kora.config.ts # Kora configuration
29
+ ```
30
+
31
+ In a feature module, `schema` defines data shape, `queries` contain reads only, `mutations` contain
32
+ writes, and `useTodos.ts` is the React binding that exposes todo data and actions to components.
33
+
34
+ ## Scripts
35
+
36
+ | Script | Description |
37
+ |--------|-------------|
38
+ | `npm run dev` | Start dev server |
39
+ | `npm run build` | Build for production |
40
+ | `npm run preview` | Preview production build |
41
+
42
+ ## Adding Sync
43
+
44
+ To enable real-time sync across devices, update `src/main.tsx`:
45
+
46
+ ```typescript
47
+ const app = createApp({
48
+ schema,
49
+ sync: {
50
+ url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001',
51
+ },
52
+ // ...
53
+ })
54
+ ```
55
+
56
+ Then create a `server.ts` and install `@korajs/server`. See the [Sync Configuration guide](https://ehoneahobed.github.io/kora/guide/sync-configuration).
57
+
58
+ ## Learn More
59
+
60
+ - [Documentation](https://ehoneahobed.github.io/kora/)
61
+ - [Storage Configuration](https://ehoneahobed.github.io/kora/guide/storage-configuration)
62
+ - [Schema Design](https://ehoneahobed.github.io/kora/guide/schema-design)
@@ -0,0 +1,12 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>{{projectName}}</title>
7
+ </head>
8
+ <body>
9
+ <div id="app"></div>
10
+ <script type="module" src="/src/main.ts"></script>
11
+ </body>
12
+ </html>
@@ -0,0 +1,12 @@
1
+ import { defineConfig } from 'korajs/config'
2
+
3
+ export default defineConfig({
4
+ schema: './src/schema.ts',
5
+ dev: {
6
+ port: 5173,
7
+ watch: {
8
+ enabled: true,
9
+ debounceMs: 300,
10
+ },
11
+ },
12
+ })
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "{{projectName}}",
3
+ "version": "0.0.1",
4
+ "private": true,
5
+ "type": "module",
6
+ "scripts": {
7
+ "dev": "kora dev",
8
+ "build": "vite build",
9
+ "check": "svelte-check --tsconfig ./tsconfig.json",
10
+ "preview": "vite preview"
11
+ },
12
+ "dependencies": {
13
+ "korajs": "{{koraVersion}}",
14
+ "@korajs/svelte": "{{koraVersion}}",
15
+ "@korajs/store": "{{koraVersion}}",
16
+ "@lucide/svelte": "^0.468.0",
17
+ "@sqlite.org/sqlite-wasm": ">=3.51.0-build1",
18
+ "svelte": "^5.0.0",
19
+ "yjs": "^13.6.30"
20
+ },
21
+ "devDependencies": {
22
+ "@korajs/cli": "{{koraVersion}}",
23
+ "@sveltejs/vite-plugin-svelte": "^5.0.0",
24
+ "@tailwindcss/vite": "^4.0.0",
25
+ "svelte-check": "^4.1.0",
26
+ "tailwindcss": "^4.0.0",
27
+ "typescript": "^5.7.0",
28
+ "vite": "^6.0.0"
29
+ }
30
+ }
@@ -0,0 +1,75 @@
1
+ <script lang="ts">
2
+ import { CheckCircle2, Circle, ClipboardList, Plus, Trash2 } from '@lucide/svelte'
3
+ import { createTodosStores } from './modules/todos/useTodos'
4
+
5
+ type Filter = 'all' | 'active' | 'completed'
6
+
7
+ const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } =
8
+ createTodosStores()
9
+
10
+ const filter = $state<Filter>('all')
11
+ let input = $state('')
12
+
13
+ const filteredTodos = $derived(
14
+ filter === 'active' ? $activeTodos : filter === 'completed' ? $completedTodos : $allTodos,
15
+ )
16
+
17
+ function handleSubmit(event: SubmitEvent): void {
18
+ event.preventDefault()
19
+ const title = input.trim()
20
+ if (!title) return
21
+ addTodo.mutate({ title })
22
+ input = ''
23
+ }
24
+ </script>
25
+
26
+ <div class="min-h-screen bg-gray-950 text-gray-100">
27
+ <div class="mx-auto max-w-2xl px-4 py-12">
28
+ <div class="mb-8 flex items-center gap-3">
29
+ <ClipboardList class="h-8 w-8 text-indigo-400" />
30
+ <h1 class="text-2xl font-bold">My Tasks</h1>
31
+ </div>
32
+
33
+ <form class="mb-8 flex gap-3" onsubmit={handleSubmit}>
34
+ <input
35
+ bind:value={input}
36
+ type="text"
37
+ placeholder="What needs to be done?"
38
+ class="flex-1 rounded-lg border border-gray-700 bg-gray-900 px-4 py-3 text-gray-100 placeholder-gray-500 outline-none focus:border-indigo-500"
39
+ />
40
+ <button
41
+ type="submit"
42
+ disabled={!input.trim()}
43
+ class="flex items-center gap-2 rounded-lg bg-indigo-600 px-5 py-3 font-medium text-white disabled:opacity-50"
44
+ >
45
+ <Plus class="h-4 w-4" />
46
+ Add
47
+ </button>
48
+ </form>
49
+
50
+ <div class="space-y-2">
51
+ {#each filteredTodos as todo (todo.id)}
52
+ <div class="group flex items-center gap-3 rounded-lg border border-gray-800 bg-gray-900 px-4 py-3">
53
+ <button
54
+ type="button"
55
+ onclick={() => toggleTodo.mutate(todo.id, { completed: !todo.completed })}
56
+ >
57
+ {#if todo.completed}
58
+ <CheckCircle2 class="h-5 w-5 text-emerald-400" />
59
+ {:else}
60
+ <Circle class="h-5 w-5 text-gray-500" />
61
+ {/if}
62
+ </button>
63
+ <span class="flex-1 {todo.completed ? 'line-through text-gray-500' : ''}">
64
+ {String(todo.title)}
65
+ </span>
66
+ <button type="button" onclick={() => deleteTodo.mutate(todo.id)}>
67
+ <Trash2 class="h-4 w-4 text-gray-600 hover:text-red-400" />
68
+ </button>
69
+ </div>
70
+ {/each}
71
+ </div>
72
+
73
+ <p class="mt-12 text-center text-xs text-gray-700">Powered by Kora — offline-first</p>
74
+ </div>
75
+ </div>
@@ -0,0 +1,14 @@
1
+ <script lang="ts">
2
+ import type { KoraAppLike } from '@korajs/svelte'
3
+ import KoraProvider from '@korajs/svelte/KoraProvider.svelte'
4
+ import App from './App.svelte'
5
+
6
+ const { kora }: { kora: KoraAppLike } = $props()
7
+ </script>
8
+
9
+ <KoraProvider app={kora}>
10
+ {#snippet fallback()}
11
+ <div class="flex h-screen items-center justify-center bg-gray-950 text-gray-400">Loading...</div>
12
+ {/snippet}
13
+ <App />
14
+ </KoraProvider>
@@ -0,0 +1,7 @@
1
+ @import "tailwindcss";
2
+
3
+ @layer base {
4
+ body {
5
+ @apply bg-gray-950 text-gray-100 antialiased;
6
+ }
7
+ }
@@ -0,0 +1,9 @@
1
+ // Web Worker entry point for SQLite WASM.
2
+ // Loaded automatically by the Kora store to run SQLite in a background thread.
3
+
4
+ // Import the WASM binary URL so Vite resolves it with the correct content hash.
5
+ // Without this, production builds fail because sqlite3 looks for the unhashed filename.
6
+ import sqliteWasmUrl from '@sqlite.org/sqlite-wasm/sqlite3.wasm?url'
7
+ ;(globalThis as Record<string, unknown>).__KORA_SQLITE_WASM_URL = sqliteWasmUrl
8
+
9
+ import '@korajs/store/sqlite-wasm/worker'
@@ -0,0 +1,16 @@
1
+ import { createApp as createKoraApp } from 'korajs'
2
+ import { mount } from 'svelte'
3
+ import Root from './Root.svelte'
4
+ import schema from './schema'
5
+ import './index.css'
6
+ import koraWorkerUrl from './kora-worker.ts?worker&url'
7
+
8
+ const kora = createKoraApp({
9
+ schema,
10
+ store: {
11
+ workerUrl: koraWorkerUrl,
12
+ },
13
+ devtools: true,
14
+ })
15
+
16
+ mount(Root, { target: document.getElementById('app')!, props: { kora } })
@@ -0,0 +1,25 @@
1
+ import type { CollectionAccessor } from 'korajs'
2
+
3
+ export interface CreateTodoInput {
4
+ title: string
5
+ }
6
+
7
+ export interface UpdateTodoStatusInput {
8
+ completed: boolean
9
+ }
10
+
11
+ export function createTodo(todos: CollectionAccessor, data: CreateTodoInput) {
12
+ return todos.insert({ title: data.title })
13
+ }
14
+
15
+ export function updateTodoStatus(
16
+ todos: CollectionAccessor,
17
+ id: string,
18
+ data: UpdateTodoStatusInput,
19
+ ) {
20
+ return todos.update(id, { completed: data.completed })
21
+ }
22
+
23
+ export function deleteTodo(todos: CollectionAccessor, id: string) {
24
+ return todos.delete(id)
25
+ }
@@ -0,0 +1,5 @@
1
+ import type { CollectionAccessor } from 'korajs'
2
+
3
+ export function orderedTodos(todos: CollectionAccessor) {
4
+ return todos.where({}).orderBy('createdAt', 'desc')
5
+ }
@@ -0,0 +1,10 @@
1
+ import { t } from 'korajs'
2
+
3
+ export const todos = {
4
+ fields: {
5
+ title: t.string(),
6
+ completed: t.boolean().default(false),
7
+ createdAt: t.timestamp().auto(),
8
+ },
9
+ indexes: ['completed', 'createdAt'],
10
+ }
@@ -0,0 +1,25 @@
1
+ import { createMutation, createQueryStore, getCollection } from '@korajs/svelte'
2
+ import { derived } from 'svelte/store'
3
+ import {
4
+ type CreateTodoInput,
5
+ type UpdateTodoStatusInput,
6
+ createTodo,
7
+ deleteTodo,
8
+ updateTodoStatus,
9
+ } from './todo.mutations'
10
+ import { orderedTodos } from './todo.queries'
11
+
12
+ export function createTodosStores() {
13
+ const todos = getCollection('todos')
14
+ const allTodos = createQueryStore(orderedTodos(todos))
15
+ const addTodo = createMutation((data: CreateTodoInput) => createTodo(todos, data))
16
+ const toggleTodo = createMutation((id: string, data: UpdateTodoStatusInput) =>
17
+ updateTodoStatus(todos, id, data),
18
+ )
19
+ const removeTodo = createMutation((id: string) => deleteTodo(todos, id))
20
+
21
+ const activeTodos = derived(allTodos, ($all) => $all.filter((todo) => !todo.completed))
22
+ const completedTodos = derived(allTodos, ($all) => $all.filter((todo) => !!todo.completed))
23
+
24
+ return { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo: removeTodo }
25
+ }
@@ -0,0 +1,9 @@
1
+ import { defineSchema } from 'korajs'
2
+ import { todos } from './modules/todos/todo.schema'
3
+
4
+ export default defineSchema({
5
+ version: 1,
6
+ collections: {
7
+ todos,
8
+ },
9
+ })
@@ -0,0 +1,12 @@
1
+ /// <reference types="svelte" />
2
+ /// <reference types="vite/client" />
3
+
4
+ declare module '*?worker&url' {
5
+ const url: string
6
+ export default url
7
+ }
8
+
9
+ declare module '*?url' {
10
+ const url: string
11
+ export default url
12
+ }
@@ -0,0 +1,5 @@
1
+ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
2
+
3
+ export default {
4
+ preprocess: vitePreprocess(),
5
+ }