@acryldev/create-blends 1.7.0 → 1.7.1
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.
- package/{docs/framework/LICENSE → LICENSE} +1 -3
- package/package.json +2 -2
- package/docs/framework/README.md +0 -70
- package/docs/framework/agents/index.md +0 -59
- package/docs/framework/api/acryl.md +0 -247
- package/docs/framework/api/context.md +0 -478
- package/docs/framework/api/exception.md +0 -80
- package/docs/framework/api/index.md +0 -12
- package/docs/framework/api/presets.md +0 -62
- package/docs/framework/api/request.md +0 -396
- package/docs/framework/api/routing.md +0 -303
- package/docs/framework/api/summary.md +0 -143
- package/docs/framework/concepts/benchmarks.md +0 -26
- package/docs/framework/concepts/developer-experience.md +0 -5
- package/docs/framework/concepts/middleware.md +0 -21
- package/docs/framework/concepts/motivation.md +0 -14
- package/docs/framework/concepts/routers.md +0 -63
- package/docs/framework/concepts/stacks.md +0 -235
- package/docs/framework/concepts/web-standard.md +0 -27
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +0 -160
- package/docs/framework/cordis/concepts.md +0 -105
- package/docs/framework/cordis/middleware.md +0 -8
- package/docs/framework/cordis/migration-from-0-3.md +0 -111
- package/docs/framework/cordis/migration-from-0-4.md +0 -14
- package/docs/framework/cordis/migration-from-dsh-webserver.md +0 -109
- package/docs/framework/cordis/migration-to-1-0.md +0 -46
- package/docs/framework/cordis/mounting.md +0 -85
- package/docs/framework/cordis/node-server.md +0 -100
- package/docs/framework/cordis/plugin-lifecycle.md +0 -111
- package/docs/framework/cordis/surfaces.md +0 -71
- package/docs/framework/cordis/transport-and-cancellation.md +0 -57
- package/docs/framework/cordis/validation.md +0 -135
- package/docs/framework/getting-started/basic.md +0 -201
- package/docs/framework/getting-started/bun.md +0 -219
- package/docs/framework/getting-started/deploy.md +0 -133
- package/docs/framework/getting-started/desktop.md +0 -80
- package/docs/framework/getting-started/nodejs.md +0 -365
- package/docs/framework/getting-started/other-runtimes.md +0 -30
- package/docs/framework/guides/best-practices.md +0 -231
- package/docs/framework/guides/bring-your-own-tool.md +0 -218
- package/docs/framework/guides/client-modules.md +0 -210
- package/docs/framework/guides/create-acrylblends.md +0 -143
- package/docs/framework/guides/data.md +0 -314
- package/docs/framework/guides/examples.md +0 -3
- package/docs/framework/guides/faq.md +0 -19
- package/docs/framework/guides/forms-and-sessions.md +0 -235
- package/docs/framework/guides/helpers.md +0 -33
- package/docs/framework/guides/jsx-dom.md +0 -301
- package/docs/framework/guides/jsx.md +0 -487
- package/docs/framework/guides/middleware.md +0 -253
- package/docs/framework/guides/production.md +0 -80
- package/docs/framework/guides/rpc.md +0 -878
- package/docs/framework/guides/testing.md +0 -133
- package/docs/framework/guides/validation.md +0 -470
- package/docs/framework/helpers/accepts.md +0 -60
- package/docs/framework/helpers/adapter.md +0 -57
- package/docs/framework/helpers/conninfo.md +0 -77
- package/docs/framework/helpers/cookie.md +0 -232
- package/docs/framework/helpers/css.md +0 -282
- package/docs/framework/helpers/dev.md +0 -64
- package/docs/framework/helpers/factory.md +0 -180
- package/docs/framework/helpers/html.md +0 -123
- package/docs/framework/helpers/jwt.md +0 -184
- package/docs/framework/helpers/proxy.md +0 -115
- package/docs/framework/helpers/route.md +0 -143
- package/docs/framework/helpers/ssg.md +0 -390
- package/docs/framework/helpers/streaming.md +0 -224
- package/docs/framework/helpers/testing.md +0 -118
- package/docs/framework/helpers/websocket.md +0 -208
- package/docs/framework/middleware/builtin/basic-auth.md +0 -165
- package/docs/framework/middleware/builtin/bearer-auth.md +0 -138
- package/docs/framework/middleware/builtin/body-limit.md +0 -71
- package/docs/framework/middleware/builtin/cache.md +0 -99
- package/docs/framework/middleware/builtin/combine.md +0 -94
- package/docs/framework/middleware/builtin/compress.md +0 -59
- package/docs/framework/middleware/builtin/context-storage.md +0 -74
- package/docs/framework/middleware/builtin/cors.md +0 -134
- package/docs/framework/middleware/builtin/csrf.md +0 -105
- package/docs/framework/middleware/builtin/etag.md +0 -54
- package/docs/framework/middleware/builtin/ip-restriction.md +0 -69
- package/docs/framework/middleware/builtin/jsx-renderer.md +0 -283
- package/docs/framework/middleware/builtin/jwk.md +0 -192
- package/docs/framework/middleware/builtin/jwt.md +0 -145
- package/docs/framework/middleware/builtin/language.md +0 -232
- package/docs/framework/middleware/builtin/logger.md +0 -74
- package/docs/framework/middleware/builtin/loopback-only.md +0 -31
- package/docs/framework/middleware/builtin/method-not-allowed.md +0 -48
- package/docs/framework/middleware/builtin/method-override.md +0 -80
- package/docs/framework/middleware/builtin/mount.md +0 -103
- package/docs/framework/middleware/builtin/pretty-json.md +0 -53
- package/docs/framework/middleware/builtin/request-id.md +0 -87
- package/docs/framework/middleware/builtin/secure-headers.md +0 -247
- package/docs/framework/middleware/builtin/timeout.md +0 -98
- package/docs/framework/middleware/builtin/timing.md +0 -100
- package/docs/framework/middleware/builtin/trailing-slash.md +0 -74
- package/docs/framework/middleware/third-party.md +0 -4
- package/docs/framework/workshop/README.md +0 -294
- package/docs/framework/workshop/facilitator.md +0 -101
|
@@ -1,218 +0,0 @@
|
|
|
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.
|
|
@@ -1,210 +0,0 @@
|
|
|
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.
|
|
@@ -1,143 +0,0 @@
|
|
|
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.
|