@acryldev/create-blends 0.0.0-stage → 1.7.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 (103) hide show
  1. package/README.md +104 -2
  2. package/bin/create-acrylblends.js +12 -0
  3. package/dist/index.d.ts +94 -0
  4. package/dist/index.js +1069 -0
  5. package/dist/index.js.map +1 -0
  6. package/docs/framework/LICENSE +23 -0
  7. package/docs/framework/README.md +70 -0
  8. package/docs/framework/agents/index.md +59 -0
  9. package/docs/framework/api/acryl.md +247 -0
  10. package/docs/framework/api/context.md +478 -0
  11. package/docs/framework/api/exception.md +80 -0
  12. package/docs/framework/api/index.md +12 -0
  13. package/docs/framework/api/presets.md +62 -0
  14. package/docs/framework/api/request.md +396 -0
  15. package/docs/framework/api/routing.md +303 -0
  16. package/docs/framework/api/summary.md +143 -0
  17. package/docs/framework/concepts/benchmarks.md +26 -0
  18. package/docs/framework/concepts/developer-experience.md +5 -0
  19. package/docs/framework/concepts/middleware.md +21 -0
  20. package/docs/framework/concepts/motivation.md +14 -0
  21. package/docs/framework/concepts/routers.md +63 -0
  22. package/docs/framework/concepts/stacks.md +235 -0
  23. package/docs/framework/concepts/web-standard.md +27 -0
  24. package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
  25. package/docs/framework/cordis/concepts.md +105 -0
  26. package/docs/framework/cordis/middleware.md +8 -0
  27. package/docs/framework/cordis/migration-from-0-3.md +111 -0
  28. package/docs/framework/cordis/migration-from-0-4.md +14 -0
  29. package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
  30. package/docs/framework/cordis/migration-to-1-0.md +46 -0
  31. package/docs/framework/cordis/mounting.md +85 -0
  32. package/docs/framework/cordis/node-server.md +100 -0
  33. package/docs/framework/cordis/plugin-lifecycle.md +111 -0
  34. package/docs/framework/cordis/surfaces.md +71 -0
  35. package/docs/framework/cordis/transport-and-cancellation.md +57 -0
  36. package/docs/framework/cordis/validation.md +135 -0
  37. package/docs/framework/getting-started/basic.md +201 -0
  38. package/docs/framework/getting-started/bun.md +219 -0
  39. package/docs/framework/getting-started/deploy.md +133 -0
  40. package/docs/framework/getting-started/desktop.md +80 -0
  41. package/docs/framework/getting-started/nodejs.md +365 -0
  42. package/docs/framework/getting-started/other-runtimes.md +30 -0
  43. package/docs/framework/guides/best-practices.md +231 -0
  44. package/docs/framework/guides/bring-your-own-tool.md +218 -0
  45. package/docs/framework/guides/client-modules.md +210 -0
  46. package/docs/framework/guides/create-acrylblends.md +143 -0
  47. package/docs/framework/guides/data.md +314 -0
  48. package/docs/framework/guides/examples.md +3 -0
  49. package/docs/framework/guides/faq.md +19 -0
  50. package/docs/framework/guides/forms-and-sessions.md +235 -0
  51. package/docs/framework/guides/helpers.md +33 -0
  52. package/docs/framework/guides/jsx-dom.md +301 -0
  53. package/docs/framework/guides/jsx.md +487 -0
  54. package/docs/framework/guides/middleware.md +253 -0
  55. package/docs/framework/guides/production.md +80 -0
  56. package/docs/framework/guides/rpc.md +878 -0
  57. package/docs/framework/guides/testing.md +133 -0
  58. package/docs/framework/guides/validation.md +470 -0
  59. package/docs/framework/helpers/accepts.md +60 -0
  60. package/docs/framework/helpers/adapter.md +57 -0
  61. package/docs/framework/helpers/conninfo.md +77 -0
  62. package/docs/framework/helpers/cookie.md +232 -0
  63. package/docs/framework/helpers/css.md +282 -0
  64. package/docs/framework/helpers/dev.md +64 -0
  65. package/docs/framework/helpers/factory.md +180 -0
  66. package/docs/framework/helpers/html.md +123 -0
  67. package/docs/framework/helpers/jwt.md +184 -0
  68. package/docs/framework/helpers/proxy.md +115 -0
  69. package/docs/framework/helpers/route.md +143 -0
  70. package/docs/framework/helpers/ssg.md +390 -0
  71. package/docs/framework/helpers/streaming.md +224 -0
  72. package/docs/framework/helpers/testing.md +118 -0
  73. package/docs/framework/helpers/websocket.md +208 -0
  74. package/docs/framework/middleware/builtin/basic-auth.md +165 -0
  75. package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
  76. package/docs/framework/middleware/builtin/body-limit.md +71 -0
  77. package/docs/framework/middleware/builtin/cache.md +99 -0
  78. package/docs/framework/middleware/builtin/combine.md +94 -0
  79. package/docs/framework/middleware/builtin/compress.md +59 -0
  80. package/docs/framework/middleware/builtin/context-storage.md +74 -0
  81. package/docs/framework/middleware/builtin/cors.md +134 -0
  82. package/docs/framework/middleware/builtin/csrf.md +105 -0
  83. package/docs/framework/middleware/builtin/etag.md +54 -0
  84. package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
  85. package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
  86. package/docs/framework/middleware/builtin/jwk.md +192 -0
  87. package/docs/framework/middleware/builtin/jwt.md +145 -0
  88. package/docs/framework/middleware/builtin/language.md +232 -0
  89. package/docs/framework/middleware/builtin/logger.md +74 -0
  90. package/docs/framework/middleware/builtin/loopback-only.md +31 -0
  91. package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
  92. package/docs/framework/middleware/builtin/method-override.md +80 -0
  93. package/docs/framework/middleware/builtin/mount.md +103 -0
  94. package/docs/framework/middleware/builtin/pretty-json.md +53 -0
  95. package/docs/framework/middleware/builtin/request-id.md +87 -0
  96. package/docs/framework/middleware/builtin/secure-headers.md +247 -0
  97. package/docs/framework/middleware/builtin/timeout.md +98 -0
  98. package/docs/framework/middleware/builtin/timing.md +100 -0
  99. package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
  100. package/docs/framework/middleware/third-party.md +4 -0
  101. package/docs/framework/workshop/README.md +294 -0
  102. package/docs/framework/workshop/facilitator.md +101 -0
  103. package/package.json +54 -3
@@ -0,0 +1,218 @@
1
+ # Bring your own tool: a provider of a port
2
+
3
+ Every choice in an app is a plugin behind a port, and what the app starts with is only a fallback. Any outside npm tool (a database, a store, a renderer, an auth library) joins the
4
+ app as another **provider** of the same port: a plugin that implements the port's interface on top of the tool and provides the service by its name. The code that uses the port
5
+ does not change. The port's **conformance suite** decides whether your provider is accepted, whoever wrote it. And because Cordis finds services by name, the app can swap the
6
+ provider **while it runs**: the plugins that use the port wait, and carry on when the new provider arrives. A person does it, or an agent working in the app folder, through the door.
7
+
8
+ This page does it once, from start to end, with a real tool: [lowdb](https://github.com/typicode/lowdb), a small JSON-file database, becomes a provider of the `kv` port ([Data](data.md#a-tiny-app-kv)).
9
+ Every step runs as written: the code on this page is extracted and run against a fresh app by `scripts/verify-byo-tool.mjs`.
10
+
11
+ You need an app with the `extensions` plugin, which installs plugins while the app runs: `npx acrylblends init my-app --template agent`, then `cd my-app` and `npm install`.
12
+
13
+ ## 1. Bring the port, its suite and a way to run it
14
+
15
+ ```sh
16
+ npx acrylblends add kv --suite
17
+ npm install
18
+ ```
19
+
20
+ `add kv` copies the port (`plugins/kv`) and the JSON-file provider (`plugins/kv-json`) and gives your plugins the names `#acryl-kv` and `#acryl-kv-json` (entries in `package.json` "imports").
21
+ `--suite` also copies the port's conformance suite (`#acryl-kv/conformance`) and adds `vitest`, which runs it. The same works for the `db` port: `npx acrylblends add db --suite`.
22
+
23
+ ## 2. Install the tool
24
+
25
+ ```sh
26
+ npm install lowdb
27
+ ```
28
+
29
+ ## 3. Write the provider
30
+
31
+ A provider is a folder in `plugins/` with an `index.ts` that exports `name`, and `apply(ctx)` which provides the service. Keep the tool behind a plain function that returns the port's interface (`openKv`
32
+ here), so tests and plain code use it without Cordis, and let `apply` be a thin wrapper that provides it for as long as the plugin runs.
33
+
34
+ The port gives you the checks every provider must make alike (`checkKey`, `encodeValue`, `decodeValue`, `runChange`, `compareKeys`), so a bad call fails the same way on a file, on SQL and on your tool.
35
+
36
+ ```ts no-check
37
+ // plugins/kv-lowdb/index.ts
38
+ import { join } from 'node:path'
39
+ import type { Context } from '@deepseek-ai/cordis'
40
+ import { checkKey, compareKeys, decodeValue, encodeValue, KV_SERVICE, runChange } from '#acryl-kv'
41
+ import type { Kv, KvOpened } from '#acryl-kv'
42
+ import { Low } from 'lowdb'
43
+ import { JSONFile } from 'lowdb/node'
44
+
45
+ /** The kv port on lowdb: one JSON file, written atomically by lowdb after every change. */
46
+ export async function openKv({ path }: { path: string }): Promise<KvOpened> {
47
+ const db = new Low<Record<string, unknown>>(new JSONFile(path), {})
48
+ await db.read()
49
+ // One call at a time, in order: that is what makes `update` atomic and lets `close` wait for the writes in flight.
50
+ let queue: Promise<unknown> = Promise.resolve()
51
+ let closed = false
52
+ const run = <T>(work: () => Promise<T>): Promise<T> => {
53
+ if (closed) return Promise.reject(new Error('the kv store is closed'))
54
+ const result = queue.then(work)
55
+ queue = result.catch(() => {})
56
+ return result
57
+ }
58
+ // A copy of the stored value, so changing what `get` returned changes nothing stored.
59
+ const copy = (key: string): unknown =>
60
+ key in db.data ? decodeValue(encodeValue(db.data[key])) : undefined
61
+ const kv: Kv = {
62
+ get: <T>(key: string) =>
63
+ run(async () => {
64
+ checkKey(key)
65
+ return copy(key) as T | undefined
66
+ }),
67
+ set: (key, value) =>
68
+ run(async () => {
69
+ checkKey(key)
70
+ db.data[key] = decodeValue(encodeValue(value))
71
+ await db.write()
72
+ }),
73
+ update: <T>(key: string, change: (current: T | undefined) => T) =>
74
+ run(async () => {
75
+ checkKey(key)
76
+ const next = runChange(change, copy(key) as T | undefined)
77
+ db.data[key] = decodeValue(encodeValue(next))
78
+ await db.write()
79
+ return copy(key) as T
80
+ }),
81
+ delete: (key) =>
82
+ run(async () => {
83
+ checkKey(key)
84
+ delete db.data[key]
85
+ await db.write()
86
+ }),
87
+ list: (prefix = '') =>
88
+ run(async () =>
89
+ Object.keys(db.data)
90
+ .filter((key) => key.startsWith(prefix))
91
+ .sort(compareKeys),
92
+ ),
93
+ }
94
+ return {
95
+ kv,
96
+ async close() {
97
+ closed = true
98
+ await queue
99
+ },
100
+ }
101
+ }
102
+
103
+ export const name = 'kv-lowdb'
104
+
105
+ /** As a plugin: provide `kv` for as long as the plugin runs; the store closes after `kv` is withdrawn. */
106
+ export async function apply(ctx: Context, config: { path?: string } = {}): Promise<void> {
107
+ const file = config.path ?? join(ctx.appInstance.home, 'kv-lowdb.json')
108
+ await ctx.effect(async function* () {
109
+ const opened = await openKv({ path: file })
110
+ yield () => opened.close()
111
+ yield ctx.reflect.provide(KV_SERVICE, opened.kv)
112
+ }, `kv-lowdb: ${file}`)
113
+ }
114
+ ```
115
+
116
+ (A block whose first line is a path comment is the file of that name.)
117
+
118
+ ## 4. Pass the suite
119
+
120
+ The suite is the contract: it runs the same cases against every provider. A test gives it a fresh store for each case and a way to reopen the same storage.
121
+
122
+ The suite imports `vitest` from your project, where `--suite` put it as a dev dependency. The same suite is in the package as `acrylblends/kv/conformance` (and `acrylblends/db/conformance`), and there it runs on the vitest your test hands it: `import * as vitest from 'vitest'` and `describeKvConformance('my-provider', open, vitest)`. The package does not declare `vitest` as a peer, so a production install of an app that uses `acrylblends` carries no vitest, vite or native build tools (1.0.10 and later; before that, `pnpm deploy --prod` pulled them in).
123
+
124
+ ```ts no-check
125
+ // test/kv-lowdb.spec.ts
126
+ import { mkdir, mkdtemp } from 'node:fs/promises'
127
+ import { join } from 'node:path'
128
+ import { describeKvConformance, type KvUnderTest } from '#acryl-kv/conformance'
129
+ import { openKv } from '../plugins/kv-lowdb/index.ts'
130
+
131
+ const underTest = async (path: string): Promise<KvUnderTest> => {
132
+ const opened = await openKv({ path })
133
+ return {
134
+ kv: opened.kv,
135
+ close: opened.close,
136
+ reopen: async () => {
137
+ await opened.close()
138
+ return underTest(path)
139
+ },
140
+ }
141
+ }
142
+
143
+ // A fresh file per case, in a folder of the project (a sandboxed agent may not write to the system temp folder).
144
+ describeKvConformance('kv-lowdb', async () => {
145
+ await mkdir('.acrylblends', { recursive: true })
146
+ return underTest(join(await mkdtemp(join('.acrylblends', 'kv-lowdb-')), 'kv.json'))
147
+ })
148
+ ```
149
+
150
+ ```sh
151
+ npx vitest run test/kv-lowdb.spec.ts
152
+ ```
153
+
154
+ All the cases must pass. A failure names the rule that broke (`counts fifty concurrent updates to exactly fifty`, `keeps what was written across close and reopen`, ...): fix the provider, not the test.
155
+
156
+ ## 5. Make the default swappable, and swap
157
+
158
+ A provider that the app's code mounts at start (a row of `blend.yaml`) is fixed until the next start. To swap while the app runs, install both the default and yours as plugins of the app. A one-line plugin
159
+ names the default:
160
+
161
+ ```ts no-check
162
+ // plugins/kv-default/index.ts
163
+ export { apply, Config } from '#acryl-kv-json'
164
+ export const name = 'kv-default'
165
+ ```
166
+
167
+ Start the app and open it in a browser (`npm run dev`). The door is the command `.acryl/bin/acryl` in the app folder:
168
+
169
+ ```sh
170
+ .acryl/bin/acryl plugin add plugins/kv-default
171
+ ```
172
+
173
+ Any plugin that declares `inject: ['kv']` now has a store. This one counts visits:
174
+
175
+ ```ts no-check
176
+ // plugins/visits/index.ts
177
+ import type { Context } from '@deepseek-ai/cordis'
178
+ import { Acryl } from '@acryldev/blends'
179
+ import type {} from '#acryl-kv'
180
+
181
+ export const name = 'visits'
182
+ export const inject = ['router', 'kv']
183
+
184
+ /** GET /visits counts the visits in the kv store, whichever provider holds it. */
185
+ export function apply(ctx: Context): void {
186
+ ctx.router.route(
187
+ '/',
188
+ new Acryl().get('/visits', async (c) =>
189
+ c.json({ visits: await ctx.kv.update<number>('visits', (n) => (n ?? 0) + 1) }),
190
+ ),
191
+ )
192
+ }
193
+ ```
194
+
195
+ ```sh
196
+ .acryl/bin/acryl plugin add plugins/visits
197
+ curl <the address npm run dev printed>/visits # {"visits":1}, then 2, then 3
198
+ ```
199
+
200
+ Now swap. Two providers of one service cannot run together (the second is refused and nothing changes), so take the default out and put yours in:
201
+
202
+ ```sh
203
+ .acryl/bin/acryl plugin remove kv-default
204
+ .acryl/bin/acryl plugin list # visits: pending, missing kv
205
+ .acryl/bin/acryl plugin add plugins/kv-lowdb
206
+ curl <the address>/visits # {"visits":1}: served again, by the same process
207
+ ```
208
+
209
+ `visits` was never edited. While no provider existed its route was gone and its state was `pending`; the moment `kv-lowdb` provided `kv` it started again. The process did not restart, and the swap survives a
210
+ restart: the app remembers what was installed.
211
+
212
+ ## What to know
213
+
214
+ - **Data does not move by itself.** The new store starts empty (the visits counted from 1 again). To carry it over, copy before you swap, in a script or a plugin: `copyKv(source, target)` from `#acryl-kv` copies one store into another.
215
+ - **A failed install changes nothing.** A provider that throws on start, or that cannot import something, is refused and the previous state stays. To go back: `plugin remove kv-lowdb`, then `plugin add plugins/kv`.
216
+ - **The suite checks the port, not your tool.** It cannot know that lowdb loses a write on a power cut. Read what the tool promises about durability before you trust it with more than a demo.
217
+ - **Other ports and tools work the same way.** `db`: `npx acrylblends add db --suite`, wrap a driver or an ORM behind `Db`, pass `describeDbConformance`. Keep the opener rule ([Data](data.md#why-the-database-is-opened-in-one-place)): only the file that mounts the provider imports the tool.
218
+ - **An agent can do all of it.** Give a coding agent in the app folder the page and one line: "wrap `<package>` as a provider of the `kv` port, pass its suite, and swap it in through the door". `AGENTS.md` in the app names the door.
@@ -0,0 +1,210 @@
1
+ # Client components without a bundler
2
+
3
+ A page can run [client components](jsx-dom.md) written in TypeScript and JSX with no bundler and no build configuration. `clientModules` from
4
+ `acrylblends/node-server` serves a folder of client modules to the browser: each `.tsx`, `.ts` or `.jsx` file is compiled when the browser asks
5
+ for it, with your app's own `typescript`, and the framework's browser imports are pointed at the browser builds the package ships. The page
6
+ needs one script tag.
7
+
8
+ It runs on Node, the runtime the framework targets. For a large client app with many npm packages, a bundler (Vite, esbuild) remains the
9
+ better tool; see [The `acrylblends/jsx/dom` runtime](jsx-dom.md#the-acrylblendsjsxdom-runtime).
10
+
11
+ ## Set up
12
+
13
+ The routes, with the type the browser's typed client uses, in a file of their own (`app.ts`):
14
+
15
+ ```ts
16
+ import { Acryl } from '@acryldev/blends'
17
+
18
+ export const app = new Acryl()
19
+ .get('/', (c) =>
20
+ c.html(
21
+ '<!doctype html><div id="counter"></div><p id="greeting"></p>' +
22
+ '<script type="module" src="/client/counter.tsx"></script>'
23
+ )
24
+ )
25
+ .get('/api/hello', (c) => c.json({ hello: 'browser' }))
26
+
27
+ export type AppType = typeof app
28
+ ```
29
+
30
+ The Node entry routes the client modules next to them (`site.ts`):
31
+
32
+ ```ts
33
+ import { Acryl } from '@acryldev/blends'
34
+ import { clientModules, serve } from '@acryldev/blends/node-server'
35
+ import { app } from './app.ts'
36
+
37
+ const site = new Acryl()
38
+ .route('/', app)
39
+ .route('/client', clientModules({ root: 'src/client', compiled: 'dist/client' }))
40
+
41
+ serve({ fetch: site.fetch, port: 3000 })
42
+ ```
43
+
44
+ A client component (`src/client/counter.tsx`), with a helper module beside it (`src/client/parts/label.ts`):
45
+
46
+ ```tsx
47
+ import { render, useState } from '@acryldev/blends/jsx/dom'
48
+ import { hc } from '@acryldev/blends/client'
49
+ import type { AppType } from '../../app.ts'
50
+ import { label } from './parts/label.ts'
51
+
52
+ const Counter = () => {
53
+ const [count, setCount] = useState(0)
54
+ return <button onClick={() => setCount(count + 1)}>{label(count)}</button>
55
+ }
56
+
57
+ render(<Counter />, document.getElementById('counter')!)
58
+
59
+ const client = hc<AppType>(location.origin)
60
+ const { hello } = await (await client.api.hello.$get()).json()
61
+ document.getElementById('greeting')!.textContent = `hello ${hello}`
62
+ ```
63
+
64
+ ```ts
65
+ export const label = (count: number): string => `Count ${count}`
66
+ ```
67
+
68
+ Start the site with `node site.ts` and open `http://localhost:3000`. Edit `counter.tsx` and reload: the module is compiled again.
69
+
70
+ Your editor checks the client folder as browser code with its own `src/client/tsconfig.json`: the DOM library, the DOM renderer, no Node
71
+ types. This is why `AppType` comes from `app.ts`, which does not import the Node adapter.
72
+
73
+ ```json
74
+ {
75
+ "compilerOptions": {
76
+ "target": "ES2024",
77
+ "lib": ["ES2024", "DOM", "DOM.Iterable"],
78
+ "module": "NodeNext",
79
+ "moduleResolution": "NodeNext",
80
+ "strict": true,
81
+ "noEmit": true,
82
+ "allowImportingTsExtensions": true,
83
+ "jsx": "react-jsx",
84
+ "jsxImportSource": "@acryldev/blends/jsx/dom",
85
+ "types": []
86
+ },
87
+ "include": ["**/*.ts", "**/*.tsx"]
88
+ }
89
+ ```
90
+
91
+ ## Server markup and `hydrateRoot`
92
+
93
+ A page can carry server-rendered markup for an island and take it over in the browser with `hydrateRoot` from `acrylblends/jsx/dom/client`:
94
+
95
+ ```tsx
96
+ import { useState } from '@acryldev/blends/jsx/dom'
97
+ import { hydrateRoot } from '@acryldev/blends/jsx/dom/client'
98
+
99
+ const Counter = () => {
100
+ const [count, setCount] = useState(0)
101
+ return <button onClick={() => setCount(count + 1)}>Count {count}</button>
102
+ }
103
+
104
+ hydrateRoot(document.getElementById('island')!, <Counter />)
105
+ ```
106
+
107
+ The DOM renderer does not reuse server markup: `hydrateRoot` renders the component and replaces the element's children with its output
108
+ in one step, so the page shows the server markup until the module runs and the component from then on, with no empty frame between. The
109
+ server's nodes are gone afterwards, together with anything the visitor did to them before the module ran: focus, a selection, text typed
110
+ into an input. Keep the server markup the same as the component's first render, so the swap does not show, and keep inputs out of the
111
+ server markup of an island, or render them only in the browser.
112
+
113
+ ## A form and its state in an island
114
+
115
+ An island that owns an input keeps the text in state and writes it back to the element, so typing and clearing the box both work:
116
+
117
+ ```tsx
118
+ import { render, useState } from '@acryldev/blends/jsx/dom'
119
+
120
+ const Ask = () => {
121
+ const [text, setText] = useState('')
122
+ const [sent, setSent] = useState<string[]>([])
123
+ const submit = (event: Event) => {
124
+ event.preventDefault()
125
+ if (text.trim() === '') return
126
+ setSent([...sent, text.trim()])
127
+ setText('')
128
+ }
129
+ return (
130
+ <form onSubmit={submit}>
131
+ <textarea value={text} onInput={(e) => setText((e.target as HTMLTextAreaElement).value)} />
132
+ <button type="submit">Send</button>
133
+ <ul>
134
+ {sent.map((message) => (
135
+ <li>{message}</li>
136
+ ))}
137
+ </ul>
138
+ </form>
139
+ )
140
+ }
141
+
142
+ render(<Ask />, document.getElementById('ask')!)
143
+ ```
144
+
145
+ For a request that streams its answer and a Stop button (an `AbortController` kept in a `useRef`), see [Streaming an answer from a model](../helpers/streaming.md#streaming-an-answer-from-a-model).
146
+
147
+ ## How the imports reach the browser
148
+
149
+ - JSX in a client module always compiles for the DOM renderer (`acrylblends/jsx/dom`), whatever the server's `tsconfig.json` says. A file's
150
+ own `/** @jsxImportSource ... */` comment still wins.
151
+ - `acrylblends/jsx/dom`, its `jsx-runtime`, `jsx-dev-runtime` and `client` are one browser module (`@acryldev/jsx-dom.js`), and
152
+ `acrylblends/client` is another (`@acryldev/client.js`), and `acrylblends/read-sse` (the reader of a POST event stream, see
153
+ [Streaming](../helpers/streaming.md#reading-a-post-event-stream-in-the-browser)) a third (`@acryldev/read-sse.js`). None imports anything. The same app
154
+ serves them, and each import is rewritten to a URL relative to the module, so the setup works under whatever path you route `clientModules` at.
155
+ - Import your own modules with their file names, as the browser fetches them: `import { label } from './parts/label.ts'`.
156
+ - Another package (`import confetti from 'canvas-confetti'`) is left as it is: add an
157
+ [import map](https://developer.mozilla.org/docs/Web/HTML/Element/script/type/importmap) to the page for it, or use a bundler.
158
+ - `.js` and `.mjs` files are served unchanged.
159
+
160
+ A module is compiled once and kept in memory until its file changes, up to 16 MiB of compiled code (the least recently served goes first;
161
+ set `cacheBytes` to change the bound). Responses carry an `ETag` and `Cache-Control: no-cache`, so the browser revalidates and an edit shows
162
+ on the next reload. Only files inside the folder are served: a path with `..` or a dot segment, a `.d.ts` file, a symbolic link out of the
163
+ folder and other file types answer 404.
164
+
165
+ ## In production
166
+
167
+ Templates install `typescript` as a development dependency, and a deploy that leaves those out (`npm ci --omit=dev`) has no compiler.
168
+ Compile the client folder once when you build, as the `build` script of your `package.json`:
169
+
170
+ ```json
171
+ {
172
+ "scripts": {
173
+ "build": "acrylblends build-client"
174
+ }
175
+ }
176
+ ```
177
+
178
+ `acrylblends build-client [root] [outDir]` (from acrylblends 0.7.2; `src/client` and `dist/client` when not given) calls
179
+ `buildClientModules`. With an earlier version, or without the command line tool, call the function itself:
180
+
181
+ ```json
182
+ {
183
+ "scripts": {
184
+ "build": "node --input-type=module -e \"import { buildClientModules } from '@acryldev/blends/node-server'; buildClientModules({ root: 'src/client', outDir: 'dist/client' })\""
185
+ }
186
+ }
187
+ ```
188
+
189
+ It writes each module compiled to `dist/client` at the same path and file name, so the page's URLs stay the same, and copies the three
190
+ browser modules to `dist/client/@acryldev/`. Run it where `typescript` is installed, before the development dependencies are removed.
191
+
192
+ With `NODE_ENV=production` and the `compiled` option set, `clientModules` serves only that folder and compiles nothing. A module that is in
193
+ `src/client` but missing from `dist/client` answers 500 with a message to build again, and a `compiled` folder that does not exist stops the
194
+ server at startup. Outside production, modules are always compiled on request, so a stale `dist/client` never hides an edit.
195
+
196
+ When `typescript` is missing where a module has to be compiled, the module answers 500 with the message
197
+ `... is a client module, and compiling it needs the typescript package in this app: npm install --save-dev typescript`.
198
+
199
+ ## Reference
200
+
201
+ `clientModules(options)` returns an app; route it where the page's script tags point.
202
+
203
+ | Option | Meaning |
204
+ | --- | --- |
205
+ | `root` | The folder of client modules, absolute or relative to the working directory. |
206
+ | `compiled` | The folder `buildClientModules` wrote. Served instead of compiling when `NODE_ENV` is `production`. |
207
+ | `cacheBytes` | The bound of the in-memory cache of compiled modules, in bytes. 16 MiB when not given. |
208
+
209
+ `buildClientModules({ root, outDir })` compiles every module below `root` (dot files, `node_modules` and `.d.ts` files skipped) into `outDir`,
210
+ which must not lie inside `root`, and returns the paths it wrote. Files already in `outDir` that no source produces are left there.
@@ -0,0 +1,143 @@
1
+ # create-acrylblends
2
+
3
+ `create-acrylblends` is the project initializer that runs when you run `npm create @acryldev/blends@latest`, `npx create-acrylblends@latest`, `pnpm create @acryldev/blends@latest`,
4
+ `yarn create acrylblends` or `bun create acrylblends@latest`. It creates a folder with a working Acryl application for the runtime you choose.
5
+
6
+ ## Templates
7
+
8
+ | Template | What you get |
9
+ | --- | --- |
10
+ | `blank` | the smallest app: the router, a server and one route, with a test |
11
+ | `nodejs` | a web app: routes, a server-rendered JSX page and a client component, mounted by the app's own plugin; run with Node.js 22.19 or newer |
12
+ | `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the [`db` port](data.md) with numbered migrations, validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
13
+ | `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite through the [`db` port](data.md), tests with a mock model |
14
+ | `todo` | a to-do list on the router and state: CRUD routes, a page, tests |
15
+ | `agent` | the blank app with an offline agent that builds plugins into the running app, through the door (`acryl-app` is the old name for it and still works) |
16
+
17
+ Every template is a Cordis app: `blend.yaml` lists the plugins that are mounted, every plugin is a folder in `plugins/`, and the app is started by `src/main.ts`. A bare template name after the directory is the same as `--template`: `npm create @acryldev/blends@latest my-app notes`. `bun` is no longer a template; the framework still runs on Bun (see [Bun](../getting-started/bun.md)), but a new app is a Cordis app on Node.
18
+
19
+ Every template includes `AGENTS.md` and `CLAUDE.md` (the same text), two skills (`acryl-app`, `cordis-plugin`) in `.claude/skills/` and `.agents/skills/`, and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
20
+ API from the folder.
21
+
22
+ ## Passing arguments
23
+
24
+ When you use `npm create` (or `npx`), arguments meant for the initializer must be placed **after** `--`. Anything after `--` is forwarded to the initializer.
25
+
26
+ **npm**
27
+
28
+ ```sh
29
+ npm create @acryldev/blends@latest my-app -- --template nodejs
30
+ ```
31
+
32
+ **yarn**
33
+
34
+ ```sh
35
+ yarn create acrylblends my-app --template nodejs
36
+ ```
37
+
38
+ **pnpm**
39
+
40
+ ```sh
41
+ pnpm create @acryldev/blends@latest my-app --template nodejs
42
+ ```
43
+
44
+ **bun**
45
+
46
+ ```sh
47
+ bun create acrylblends@latest my-app --template nodejs
48
+ ```
49
+
50
+ ## Arguments
51
+
52
+ | Argument | Description | Example |
53
+ | :-- | :-- | :-- |
54
+ | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
55
+ | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
56
+ | `--template <template>` | One of `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (the same list as `acrylblends init --template`; `acryl-app` is accepted as `agent`). Skips the template question; a bare name after the directory means the same. | `--template notes` |
57
+ | `--from <id \| source>` | A starter from the registry by its id (`acrylblends.notes-desktop`), or any source above. Only starters that declare `runtime: acrylblends` are made; an ACRYL app starter is refused. See [Starters from the registry](#starters-from-the-registry). | `-- --from acrylblends.notes-desktop` |
58
+ | `--registry <source>` | Read the ids from this registry instead of the public one: `github:owner/repo`, an `https://` address, or a folder, with an `index.json` (at its root or in `registry/`). | `-- --from login.thing --registry github:acryldev/workshop-2026-11-20` |
59
+ | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
60
+ | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
61
+ | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
62
+ | `--help` | Print the arguments. | `--help` |
63
+
64
+ The templates are inside the package, so creating a project needs no network except for `--install`.
65
+
66
+ ## Starters from the registry
67
+
68
+ The [registry](https://acrylblends.github.io/blends) lists starters people published. Each is a whole app (`blend.yaml`, `plugins/`, `src/`, `package.json`, `README.md`) that other people can start from, and its index says which runtime it is for:
69
+
70
+ ```sh
71
+ npm create @acryldev/blends@latest my-notes -- --from acrylblends.notes-desktop
72
+ cd my-notes
73
+ npm install
74
+ npm run dev
75
+ ```
76
+
77
+ - npm needs the `--` before `--from`; with `pnpm`, `yarn` and `bun` it is not needed.
78
+ - A starter with `runtime: acrylblends` is an `acrylblends` app: this command downloads its folder, gives the manifest to the new app (`metadata.id: acrylblends.my-notes`, `visibility: private`; the starter's id and licence stay the starter's), checks it for anything that looks like a secret, and writes it. Nothing in it is installed or run: `npm install` is yours to run, and the dependencies of the starter (a desktop starter brings `electron`) are in its `package.json`.
79
+ - A starter for the ACRYL app (`runtime: acryl`, the older `acryl.*` entries) is refused with one line that says so, because its plugins run only inside the ACRYL app. Nothing is written.
80
+ - An unknown id lists the starters this command can make.
81
+ - The ids come from `https://acrylblends.github.io/registry/index.json`, and only the starter you asked for is downloaded, as one archive checked against the integrity in the index; an archive that does not match is refused. When the site cannot give the starter, the registry's repository is read instead. `--registry github:owner/repo` reads another registry with the same layout (`index.json` and `blends/<id>/`), a team's own or a workshop's; `--registry ./folder` reads one on disk.
82
+
83
+ A registry on any static host works with `--registry https://...`, if its `index.json` names an `archive` and an `integrity` for each entry: `workshop-registry/scripts/registry-archives.mjs` in this repository writes both when you deploy, on the copy you publish.
84
+
85
+ To publish a starter of your own, see [the registry README](https://github.com/acrylblends/acrylblends.github.io/tree/main/registry): the folder of your app under `blends/<id>/` with an `acryl.template.json`, in a pull request.
86
+
87
+ ## Templates from a repository or a package
88
+
89
+ A second argument after the directory makes the app from someone else's template:
90
+
91
+ ```sh
92
+ npm create @acryldev/blends@latest my-app github:acme/starter # a GitHub repository (the default branch)
93
+ npm create @acryldev/blends@latest my-app github:acme/starter#v1.2 # a tag, branch or commit
94
+ npm create @acryldev/blends@latest my-app @acme/starter # an npm package
95
+ npm create @acryldev/blends@latest my-app ./acme-starter-1.0.0.tgz # a packed template on disk
96
+ ```
97
+
98
+ A template is a folder (a repository, or an npm package) with an `acryl.template.json` at its top:
99
+
100
+ ```json
101
+ {
102
+ "name": "starter",
103
+ "description": "What the app is",
104
+ "plugins": ["desktop"]
105
+ }
106
+ ```
107
+
108
+ `name` and `description` are required and shown when the app is created. `plugins` is optional: library plugins the template needs, which the command lists with the `acrylblends add` line that adds them. A source without the file is refused with a message.
109
+
110
+ What the command does, in order:
111
+
112
+ 1. **Fetches without running anything.** A GitHub source is downloaded as a tarball (never cloned, so no git hook can run). An npm source is fetched with `npm pack --ignore-scripts`. The archive is unpacked into a scratch folder; one with a path that leaves its folder, a symbolic link, more than 5,000 files or more than 50 MB is refused.
113
+ 2. **Reads `acryl.template.json`** and refuses the source if it is missing or malformed.
114
+ 3. **Fills the template in.** `__APP_NAME__`, `__PACKAGE__`, `__CLASS__` and `__RANGE__` in text files are replaced as in the built-in templates, `package.json` gets the app's name, a dependency on `acrylblends` is set to the release this command carries, a `gitignore` file becomes `.gitignore` (npm does not publish a `.gitignore`), `docs/framework/` is added, and so are `AGENTS.md` and `CLAUDE.md` when the template has none of its own.
115
+ 4. **Looks for secrets.** The result is checked with the secret scan the save step of Blend apps uses; a template that holds a key or a password is refused, and the file and line are named (never the value).
116
+ 5. **Creates the folder** only if all of that passed.
117
+
118
+ Nothing of the template is installed or run. If its `package.json` defines `preinstall`, `install`, `postinstall` or `prepare`, the command says so and prints them: `npm install` would run them. Read them first. With `--install` the command prints the list of what will be installed and which scripts will run, then runs the install.
119
+
120
+ To publish your own: put `acryl.template.json` in the repository or package, name the files with the placeholders above, keep a file named `gitignore` instead of `.gitignore`, and keep secrets out.
121
+
122
+ ## Example flows
123
+
124
+ ### Interactive
125
+
126
+ ```sh
127
+ npm create @acryldev/blends@latest my-app
128
+ ```
129
+
130
+ This asks which template you want.
131
+
132
+ ### Non-interactive
133
+
134
+ ```sh
135
+ npm create @acryldev/blends@latest my-app -- --template nodejs --pm npm --install
136
+ ```
137
+
138
+ This creates `my-app` from the `nodejs` template and installs its dependencies with npm.
139
+
140
+ ## Troubleshooting
141
+
142
+ - If an argument is not recognized, make sure you forward it with `--` when you use `npm create` or `npx`.
143
+ - Run `npm create @acryldev/blends@latest -- --help` to see the arguments of the version you have.