create-acrylblends 0.4.1 → 1.0.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.
- package/README.md +4 -2
- package/dist/index.d.ts +10 -1
- package/dist/index.js +37 -16
- package/dist/index.js.map +1 -1
- package/docs/framework/README.md +5 -3
- package/docs/framework/agents/index.md +1 -1
- package/docs/framework/api/acryl.md +5 -17
- package/docs/framework/api/context.md +12 -61
- package/docs/framework/api/presets.md +1 -1
- package/docs/framework/api/request.md +3 -3
- package/docs/framework/api/summary.md +1 -1
- package/docs/framework/concepts/web-standard.md +6 -16
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +13 -8
- package/docs/framework/cordis/migration-from-0-4.md +1 -1
- package/docs/framework/cordis/migration-to-1-0.md +45 -0
- package/docs/framework/cordis/node-server.md +2 -2
- package/docs/framework/getting-started/basic.md +15 -10
- package/docs/framework/getting-started/desktop.md +1 -1
- package/docs/framework/getting-started/other-runtimes.md +10 -14
- package/docs/framework/guides/create-acrylblends.md +4 -2
- package/docs/framework/guides/data.md +1 -1
- package/docs/framework/guides/faq.md +1 -1
- package/docs/framework/guides/jsx-dom.md +1 -1
- package/docs/framework/guides/production.md +43 -0
- package/docs/framework/guides/rpc.md +3 -11
- package/docs/framework/helpers/adapter.md +13 -43
- package/docs/framework/helpers/conninfo.md +1 -36
- package/docs/framework/helpers/streaming.md +1 -1
- package/docs/framework/helpers/websocket.md +4 -11
- package/docs/framework/middleware/builtin/basic-auth.md +1 -1
- package/docs/framework/middleware/builtin/cache.md +2 -22
- package/docs/framework/middleware/builtin/compress.md +1 -1
- package/docs/framework/middleware/builtin/context-storage.md +10 -14
- package/docs/framework/middleware/builtin/cors.md +1 -2
- package/docs/framework/middleware/builtin/ip-restriction.md +1 -1
- package/docs/framework/middleware/builtin/jsx-renderer.md +1 -1
- package/docs/framework/middleware/builtin/logger.md +1 -1
- package/docs/framework/middleware/builtin/loopback-only.md +1 -1
- package/docs/framework/middleware/builtin/mount.md +1 -1
- package/docs/framework/middleware/builtin/request-id.md +13 -20
- package/docs/framework/middleware/builtin/timing.md +1 -2
- package/package.json +2 -2
- package/docs/framework/getting-started/aws-lambda.md +0 -115
- package/docs/framework/getting-started/cloudflare-pages.md +0 -53
- package/docs/framework/getting-started/cloudflare-workers.md +0 -67
- package/docs/framework/getting-started/lambda-edge.md +0 -41
- package/docs/framework/getting-started/netlify.md +0 -25
- package/docs/framework/getting-started/service-worker.md +0 -33
- package/docs/framework/getting-started/vercel.md +0 -28
|
@@ -4,8 +4,8 @@ Acryl uses only **Web Standards** like Fetch.
|
|
|
4
4
|
They were originally used in the `fetch` function and consist of basic objects that handle HTTP requests and responses.
|
|
5
5
|
In addition to `Requests` and `Responses`, there are `URL`, `URLSearchParam`, `Headers` and others.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
For example, a server that returns "Hello World"
|
|
7
|
+
Bun is built on Web Standards the same way.
|
|
8
|
+
For example, a server that returns "Hello World" can be written as below, and it runs on Node.js and Bun.
|
|
9
9
|
|
|
10
10
|
```ts twoslash
|
|
11
11
|
export default {
|
|
@@ -15,23 +15,13 @@ export default {
|
|
|
15
15
|
}
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
Acryl uses only Web Standards,
|
|
19
|
-
In addition, we have a Node.js adapter. Acryl runs on these runtimes:
|
|
18
|
+
Acryl uses only Web Standards, so the same application code is expected to run wherever a `fetch`-style handler can run: a platform that can call `app.fetch(request)` can serve an Acryl app. In 1.0 the framework builds, exports and gates two runtimes:
|
|
20
19
|
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
- Bun
|
|
24
|
-
- Fastly Compute
|
|
25
|
-
- AWS Lambda
|
|
26
|
-
- Node.js
|
|
27
|
-
- Vercel (edge-light)
|
|
28
|
-
- WebAssembly (w/ [WebAssembly System Interface (WASI)][wasi] via [`wasi:http`][wasi-http])
|
|
20
|
+
- **Node.js** (`acrylblends/node-server`): the verified runtime, on Node 22 and 24, on Linux, macOS and Windows.
|
|
21
|
+
- **Bun** (`acrylblends/bun`): experimental, with one smoke gate.
|
|
29
22
|
|
|
30
|
-
|
|
23
|
+
The adapters the upstream project had for Cloudflare Workers and Pages, Deno, Fastly Compute, AWS Lambda, Lambda@Edge, Vercel, Netlify and service workers are not part of the 1.0 package: no gate of ours deploys to them. Their ported sources stay in the repository and may return as separate plugins, each with its own gate. See [Other runtimes](../getting-started/other-runtimes.md).
|
|
31
24
|
The same code runs on all platforms.
|
|
32
25
|
|
|
33
26
|
Cloudflare Workers, Deno, Shopify, and others launched [WinterCG](https://wintercg.org) to discuss the possibility of using the Web Standards to enable "web-interoperability".
|
|
34
27
|
Acryl will follow their steps and go for **the Standard of the Web Standards**.
|
|
35
|
-
|
|
36
|
-
[wasi]: https://github.com/WebAssembly/wasi
|
|
37
|
-
[wasi-http]: https://github.com/WebAssembly/wasi-http
|
|
@@ -126,7 +126,7 @@ smallest one to copy is `examples/acryl-framework-starter`.
|
|
|
126
126
|
|
|
127
127
|
```ts
|
|
128
128
|
import { Context } from '@deepseek-ai/cordis'
|
|
129
|
-
import * as router from '
|
|
129
|
+
import * as router from 'acrylblends/cordis/router'
|
|
130
130
|
import * as todo from '../src/index.ts'
|
|
131
131
|
|
|
132
132
|
const ctx = new Context()
|
|
@@ -139,13 +139,18 @@ expect(await response.json()).toEqual({ id: '42' })
|
|
|
139
139
|
|
|
140
140
|
## Package map
|
|
141
141
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
|
145
|
-
|
|
|
146
|
-
| `acryl-
|
|
147
|
-
| `acryl-
|
|
148
|
-
| `acryl-
|
|
142
|
+
The framework plugins are published as subpaths of the `acrylblends` package (the Cordis forms); an app made by `acrylblends init` carries their source under `plugins/` instead, with the same names.
|
|
143
|
+
|
|
144
|
+
| Plugin | Published as | Responsibility |
|
|
145
|
+
| --- | --- | --- |
|
|
146
|
+
| `acryl-router` | `acrylblends/cordis/router` | the application API and the Cordis `router` service |
|
|
147
|
+
| `acryl-router-http` | `acrylblends/cordis/router-http` | serving router prefixes on the ACRYL Host's web server, with WebSocket upgrades owned by the mounting plugin |
|
|
148
|
+
| `acryl-node-server` | `acrylblends/cordis/node-server` | serving the whole router from a standalone Node.js process |
|
|
149
|
+
| `acryl-state` | `acrylblends/cordis/state` | shared application state across surfaces |
|
|
150
|
+
| `acryl-inspect` | `acrylblends/cordis/inspect` | runtime inspection of mounts, routes and plugins |
|
|
151
|
+
| `acryl-db`, `acryl-db-sqlite` | `acrylblends/cordis/db`, `acrylblends/cordis/db-sqlite` | the `db` port and its SQLite provider |
|
|
152
|
+
| `acryl-kv`, `acryl-kv-json`, `acryl-kv-db` | `acrylblends/cordis/kv`, `.../kv-json`, `.../kv-db` | the `kv` port and its providers |
|
|
153
|
+
| `acryl-door` | `acrylblends/cordis/door` (experimental) | the door: an agent looks at the running app and acts on it, in development only |
|
|
149
154
|
|
|
150
155
|
## Next
|
|
151
156
|
|
|
@@ -6,7 +6,7 @@ unchanged.
|
|
|
6
6
|
|
|
7
7
|
| 0.4 | 0.5 |
|
|
8
8
|
| --- | --- |
|
|
9
|
-
| `import { App } from 'acryl-router'`, `new App()` | `import { Acryl } from '
|
|
9
|
+
| `import { App } from 'acryl-router'`, `new App()` | `import { Acryl } from 'acrylblends/cordis/router'`, `new Acryl()` (`App` and `AppRequest` are removed in 1.0) |
|
|
10
10
|
| `AppRequest` | `AcrylRequest` |
|
|
11
11
|
|
|
12
12
|
`App` and `AppRequest` still work in 0.5, marked deprecated, and are removed in the next release. Code outside Cordis imports the same
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Migration to 1.0
|
|
2
|
+
|
|
3
|
+
1.0 fixes the public surface of `acrylblends` and gives an app a way to move its copies of the framework plugins forward. This page is the one path from any 0.x app that was made by 0.9.1 or later; an older app is best made again with `npm create acrylblends@latest` and its own code moved over (its routes and plugins are plain `Acryl` code and Cordis plugins).
|
|
4
|
+
|
|
5
|
+
## 1. Upgrade the app's copies of the framework plugins
|
|
6
|
+
|
|
7
|
+
An app made by `acrylblends init` carries copies of the framework plugins (`acryl-router`, `acryl-node-server`, `acryl-door`, `extensions`, ...) in `plugins/`. `acrylblends upgrade` brings them to the version of the installed package:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install acrylblends@latest # in an app that depends on the package; the agent template does not
|
|
11
|
+
npx acrylblends upgrade --dry-run # what would change, and the diff of every file you edited
|
|
12
|
+
npx acrylblends upgrade # do it
|
|
13
|
+
npm install && npm run check && npm test
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- A file nobody edited is replaced. A file the app edited stops the upgrade: nothing is changed, the diff of what would be lost is shown, and the command exits 1. Move your change out of the plugin (a plugin of your own in `plugins/<name>/` is never touched), or run `npx acrylblends upgrade --force`, which saves the edited versions in `.acrylblends/upgrade-backup/<time>/` before replacing them.
|
|
17
|
+
- `--diff` prints the diff of every changed file, not only the edited ones. `acrylblends upgrade acryl-router extensions` upgrades only those plugins.
|
|
18
|
+
- A file of your own inside a library plugin folder (a note, a test) is kept and reported. A plugin that a newer version needs and the app lacks is added.
|
|
19
|
+
- How it tells an edit from an untouched file: since 1.0 `acrylblends init` and `add` record the hash of every copied file in `plugins/library.lock.json`; for an app made earlier, the package knows the hashes of the released versions (0.9.1, 0.9.2, 0.10.0, 0.11.0). A file that matches neither counts as edited, so a doubt always stops the upgrade instead of overwriting.
|
|
20
|
+
- `package.json` gets the new `acrylblends` range when it has one, and the dependencies the new plugin versions need (existing ones are kept; run `npm install`).
|
|
21
|
+
|
|
22
|
+
## 2. What changed in the public surface
|
|
23
|
+
|
|
24
|
+
| Removed or changed | Do this |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `App` and `AppRequest` (the 0.4 names, deprecated since 0.5) are removed | `Acryl` and `AcrylRequest`: `import { Acryl } from 'acrylblends'` |
|
|
27
|
+
| `acrylblends/utils/*` and `acrylblends/acryl-base` are internal, not exported | Use the public helpers (`acrylblends/cookie`, `acrylblends/http-exception`, ...); the utilities are not promised |
|
|
28
|
+
| The adapters for AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify and Service Workers are not exported | An app is plain `fetch` code (`app.fetch(request)`), so a platform that calls a `fetch` handler can call it. Their ported sources stay in the repository; they may return as separate plugins, each with a gate. See [Other runtimes](../getting-started/other-runtimes.md) |
|
|
29
|
+
| `acrylblends/bun` is experimental | The one Bun gate runs it on Bun; no promise beyond that |
|
|
30
|
+
| The door (`door/*`, `cordis/door`), the agent panel and the PTY driver are experimental and development-only | They start nothing with `NODE_ENV=production` (the door plugin now checks it itself; `allowInProduction: true` for a host that means it); see [what runs in production](../guides/production.md) |
|
|
31
|
+
| `HTTPException` is `acrylblends/http-exception`, not the root | `import { HTTPException } from 'acrylblends/http-exception'` |
|
|
32
|
+
| `acrylblends/cordis/*` are the published forms of the framework plugins | In code that uses the package (not an app's own copies), import `acrylblends/cordis/router` where an old guide wrote `acryl-router` |
|
|
33
|
+
| One template list: `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` in both `create-acrylblends` and `acrylblends init` | `acryl-app` still means `agent` |
|
|
34
|
+
|
|
35
|
+
Node.js 22.19 or newer. Bun is optional and experimental; Deno is not supported.
|
|
36
|
+
|
|
37
|
+
## 3. Check
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npx acrylblends check-deps
|
|
41
|
+
npm run check
|
|
42
|
+
npm test
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
An app on the vendored plugins keeps working without the package's own newer subpaths; moving to the package's `acrylblends/cordis/*` forms in place of the copies is a separate, optional step.
|
|
@@ -9,8 +9,8 @@ The server is a Cordis plugin that provides the `nodeServer` service:
|
|
|
9
9
|
|
|
10
10
|
```ts
|
|
11
11
|
import { Context } from '@deepseek-ai/cordis'
|
|
12
|
-
import * as router from '
|
|
13
|
-
import * as nodeServer from 'acrylblends/node-server'
|
|
12
|
+
import * as router from 'acrylblends/cordis/router'
|
|
13
|
+
import * as nodeServer from 'acrylblends/cordis/node-server'
|
|
14
14
|
import * as todo from './todo.ts'
|
|
15
15
|
|
|
16
16
|
const root = new Context()
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Getting Started
|
|
2
2
|
|
|
3
|
-
Using Acryl is easy. You set up the project, write code, develop with a local server, and run it. The same application code
|
|
4
|
-
entry point
|
|
3
|
+
Using Acryl is easy. You set up the project, write code, develop with a local server, and run it. The same application code runs on Node.js, the verified runtime, and on Bun,
|
|
4
|
+
which is experimental; only the entry point differs. This page shows the basic usage.
|
|
5
5
|
|
|
6
6
|
## Starter
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
A starter is a Cordis app that arrives already wired: `blend.yaml`, its plugins in `plugins/`, and a test. Use the "create-acrylblends" command.
|
|
9
9
|
|
|
10
10
|
**npm**
|
|
11
11
|
|
|
@@ -34,12 +34,17 @@ bun create acrylblends@latest my-app
|
|
|
34
34
|
You are asked which template you want:
|
|
35
35
|
|
|
36
36
|
```
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
37
|
+
Templates:
|
|
38
|
+
blank the router, a server and one route: the smallest app
|
|
39
|
+
nodejs a web app with a page and a client component
|
|
40
|
+
notes a multi-user notes app on the db port (sign-up, log-in, sessions)
|
|
41
|
+
chat a chat app that streams an answer over server-sent events
|
|
42
|
+
todo a to-do list on the router and state
|
|
43
|
+
agent the blank app with an offline agent that builds plugins into the running app
|
|
44
|
+
Which template do you want to use? [nodejs]:
|
|
40
45
|
```
|
|
41
46
|
|
|
42
|
-
Every template is a Cordis app: `blend.yaml` lists its plugins and every plugin is a folder in `plugins/`. `nodejs` is a web app with a page and a client component, `notes` and `chat` add a database, and `
|
|
47
|
+
Every template is a Cordis app: `blend.yaml` lists its plugins and every plugin is a folder in `plugins/`. `blank` is the smallest app, `nodejs` is a web app with a page and a client component, `notes` and `chat` add a database, `todo` is a to-do list, and `agent` adds an agent that can extend the app while it
|
|
43
48
|
runs (see [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md)). Pass `--template` to skip the question, see [create-acrylblends](../guides/create-acrylblends.md).
|
|
44
49
|
|
|
45
50
|
The template is created in `my-app`: go to it, install the dependencies and start the local server.
|
|
@@ -52,9 +57,9 @@ npm run dev
|
|
|
52
57
|
|
|
53
58
|
## Hello World
|
|
54
59
|
|
|
55
|
-
|
|
60
|
+
In a generated app the routes live in `src/routes.ts`, which builds an `Acryl` app and mounts it with `ctx.router.route`; `src/main.ts` picks where the app lives and starts it. The app on its own is plain:
|
|
56
61
|
|
|
57
|
-
The `import` and the final `export default` are the same on
|
|
62
|
+
The `import` and the final `export default` are the same on Node.js and on Bun; what differs is how the runtime starts the app (see [Node.js](nodejs.md) and [Bun](bun.md)).
|
|
58
63
|
|
|
59
64
|
```ts twoslash
|
|
60
65
|
import { Acryl } from 'acrylblends'
|
|
@@ -131,7 +136,7 @@ app.get('/', (c) => {
|
|
|
131
136
|
})
|
|
132
137
|
```
|
|
133
138
|
|
|
134
|
-
[JSX](../guides/jsx.md)
|
|
139
|
+
JSX works too: `acrylblends/jsx` renders on the server and in the browser, and the `nodejs` template ships a `.tsx` page. See [JSX](../guides/jsx.md).
|
|
135
140
|
|
|
136
141
|
## Return raw Response
|
|
137
142
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Desktop
|
|
2
2
|
|
|
3
3
|
An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. This page covers a plain Acryl app (the `nodejs`
|
|
4
|
-
template) and a Blend app (the `
|
|
4
|
+
template) and a Blend app (the `agent` template or any other `acrylblends init` template). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
|
|
5
5
|
|
|
6
6
|
## Add it
|
|
7
7
|
|
|
@@ -2,24 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
Acryl is built on Web Standards, so the same application code is expected to run wherever a `fetch`-style handler can run. Node.js ([guide](nodejs.md)) is the runtime the framework is verified on. Bun is experimental ([guide](bun.md)).
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Runtimes with an adapter
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
| Runtime | Guide | Import | Status |
|
|
8
|
+
| --- | --- | --- | --- |
|
|
9
|
+
| Node.js | [Node.js](nodejs.md) | `acrylblends/node-server` | Primary. Verified on Node 22 and 24, on Linux, macOS and Windows. |
|
|
10
|
+
| Bun | [Bun](bun.md) | `acrylblends/bun` | Experimental. One smoke gate: the Bun adapter is run on Bun (a static file, the client address, a WebSocket echo). |
|
|
8
11
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
| Lambda@Edge (CloudFront) | [Lambda@Edge](lambda-edge.md) | `acrylblends/lambda-edge` |
|
|
13
|
-
| Cloudflare Workers | [Cloudflare Workers](cloudflare-workers.md) | `acrylblends/cloudflare-workers` |
|
|
14
|
-
| Cloudflare Pages | [Cloudflare Pages](cloudflare-pages.md) | `acrylblends/cloudflare-pages` |
|
|
15
|
-
| Vercel | [Vercel](vercel.md) | `acrylblends/vercel` |
|
|
16
|
-
| Netlify | [Netlify](netlify.md) | `acrylblends/netlify` |
|
|
17
|
-
| Service Worker | [Service Worker](service-worker.md) | `acrylblends/service-worker` |
|
|
18
|
-
| Bun | [Bun](bun.md) | `acrylblends/bun` |
|
|
12
|
+
## Removed in 1.0
|
|
13
|
+
|
|
14
|
+
The upstream also ships adapters for AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify and Service Workers. They were part of 0.x, ported with their tests, but no gate of ours deploys to any of them, so a 1.0 package does not promise them: they are not built or exported. Their ported sources stay in `plugins/acryl-router/src/core/adapter/` in the repository and may come back as separate plugins, each with its own gate. An app written with `acrylblends` is still plain `fetch` code (`app.fetch(request)`), so a platform that calls a `fetch` handler can call it directly.
|
|
19
15
|
|
|
20
16
|
## Not yet verified
|
|
21
17
|
|
|
22
|
-
The following runtimes and platforms have no adapter and no getting-started page
|
|
18
|
+
The following runtimes and platforms have no adapter and no getting-started page:
|
|
23
19
|
|
|
24
20
|
- Deno, and Deno Deploy
|
|
25
21
|
- Fastly Compute
|
|
@@ -31,4 +27,4 @@ The following runtimes and platforms have no adapter and no getting-started page
|
|
|
31
27
|
- CloudBase
|
|
32
28
|
- WebAssembly (WASI)
|
|
33
29
|
|
|
34
|
-
A page is added here, with a getting-started guide, when a
|
|
30
|
+
A page is added here, with a getting-started guide, when a runtime has an adapter and a gate that runs it.
|
|
@@ -7,10 +7,12 @@
|
|
|
7
7
|
|
|
8
8
|
| Template | What you get |
|
|
9
9
|
| --- | --- |
|
|
10
|
+
| `blank` | the smallest app: the router, a server and one route, with a test |
|
|
10
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 |
|
|
11
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 |
|
|
12
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 |
|
|
13
|
-
| `
|
|
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) |
|
|
14
16
|
|
|
15
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 acrylblends@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.
|
|
16
18
|
|
|
@@ -51,7 +53,7 @@ bun create acrylblends@latest my-app --template nodejs
|
|
|
51
53
|
| :-- | :-- | :-- |
|
|
52
54
|
| `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
|
|
53
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` |
|
|
54
|
-
| `--template <template>` | One of `nodejs`, `notes`, `chat`, `acryl-app
|
|
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` |
|
|
55
57
|
| `--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` |
|
|
56
58
|
| `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
|
|
57
59
|
| `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
|
|
@@ -289,7 +289,7 @@ applies the `migrations` folder, and provides `db`; a plugin declares `inject: [
|
|
|
289
289
|
|
|
290
290
|
```ts
|
|
291
291
|
import type { Context } from '@deepseek-ai/cordis'
|
|
292
|
-
import type {} from '
|
|
292
|
+
import type {} from 'acrylblends/cordis/db'
|
|
293
293
|
|
|
294
294
|
export const name = 'notes'
|
|
295
295
|
export const inject = ['db']
|
|
@@ -12,7 +12,7 @@ A `json` validation target reads the body only when the request has a JSON `Cont
|
|
|
12
12
|
|
|
13
13
|
## Which runtimes are verified?
|
|
14
14
|
|
|
15
|
-
Node.js. Bun is experimental. The hosting platforms
|
|
15
|
+
Node.js. Bun is experimental. The other hosting platforms have no adapter in 1.0; they are listed on [Other runtimes](../getting-started/other-runtimes.md).
|
|
16
16
|
|
|
17
17
|
## Where are the parts marked "not yet available"?
|
|
18
18
|
|
|
@@ -277,7 +277,7 @@ export default function App() {
|
|
|
277
277
|
On Node you can skip the bundler: [Client components without a bundler](client-modules.md) serves `.tsx` client modules to the browser with
|
|
278
278
|
this runtime and one script tag, in development and in production.
|
|
279
279
|
|
|
280
|
-
There is a small JSX Runtime for Client Components. Using this will result in smaller bundled results than using `acrylblends/jsx`. Specify `acrylblends/jsx/dom` in `tsconfig.json`.
|
|
280
|
+
There is a small JSX Runtime for Client Components. Using this will result in smaller bundled results than using `acrylblends/jsx`. Specify `acrylblends/jsx/dom` in `tsconfig.json`.
|
|
281
281
|
|
|
282
282
|
```json
|
|
283
283
|
{
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# What runs in production
|
|
2
|
+
|
|
3
|
+
`acrylblends` has two kinds of parts: the ones an app is built from, which run in production, and the development tools that let an agent (or you) work on the running app, which do not. This page says which is which, and exactly what the safety checks around live plugin install do and do not promise. A test (`plugins/driver-pty/test/production.test.ts`) mounts every development tool in one app and checks the table below.
|
|
4
|
+
|
|
5
|
+
## The table
|
|
6
|
+
|
|
7
|
+
| Part | In development | With `NODE_ENV=production` |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| Your routes and plugins, the router, the server, state, the `db` and `kv` ports and their providers | run | run |
|
|
10
|
+
| **The door** (`acryl-door`: `.acryl/bin/acryl`, the page script, the operator routes) | **experimental**: starts when the server is up | starts nothing: no service, no route, no `.acryl/` folder, no script in the page. `ACRYL_DOOR=off` also turns it off. A host that means to run it in production sets `allowInProduction: true` in the plugin's config |
|
|
11
|
+
| **The agent panel** (`agent-panel`) | **experimental**: a script tag on every HTML page and `/api/agent-panel/*` | does nothing (no tag, no routes). `ACRYL_DOOR=off` too |
|
|
12
|
+
| **The PTY driver** (`driver-pty`) | **experimental**: terminal drivers in the panel, `/api/driver-pty/*` | does nothing. `ACRYL_DOOR=off` too |
|
|
13
|
+
| **Live plugin install** (`extensions`, `builder`) | **experimental**: install, update, remove and reload plugins while the app runs | the `nodejs`, `notes` and `chat` templates leave the `extensions` row out; the `agent` template does not (see below) |
|
|
14
|
+
| `acrylblends/bun` | **experimental**: one smoke gate runs it on Bun | the same |
|
|
15
|
+
|
|
16
|
+
Experimental means: it works and is gated, its interface may still change in a minor version, and it is not for the public internet. The door and the panel are loopback and own-page only, with a per-run secret and an audit log; that is a convenience fence for a developer's machine, not an authentication system.
|
|
17
|
+
|
|
18
|
+
## The `agent` template is a development app
|
|
19
|
+
|
|
20
|
+
The `agent` template mounts an agent behind `POST /ask` that can write plugins into the running app (`builder`) and install them (`extensions`). Only its door is left out in production. Do not deploy it as it is: remove the `agent`, `builder` and `extensions` rows from `blend.yaml` (or start from `blank`, `nodejs`, `notes`, `chat` or `todo`), and if live install is wanted anywhere shared, set `approval: true` so an install waits for `POST /extensions/approve`.
|
|
21
|
+
|
|
22
|
+
## What live plugin install does and does not promise
|
|
23
|
+
|
|
24
|
+
Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the builder's `install_plugin`) is a **correctness check, not a security boundary**:
|
|
25
|
+
|
|
26
|
+
- It stages a content-hashed copy, imports it, mounts it, and reports the real state (`active`, `pending` with what it waits for, or `failed` with the error). If an update fails to start, the previous version is mounted again. A ledger line records every change.
|
|
27
|
+
- **The plugin's code runs inside the app's own process with the app's permissions**: it can read the app's files and environment, open sockets and start processes. Nothing in the install check stops that.
|
|
28
|
+
- At start-up the app reinstalls what was installed, and installs a new folder only from a source trusted to `install` (the app's own `plugins/` is). Code that arrived through a `git pull` into an untrusted source is listed, not run.
|
|
29
|
+
- `approval: true` holds an install until someone posts to `/extensions/approve`: it decides *whether* a plugin installs, not what an installed plugin can do.
|
|
30
|
+
|
|
31
|
+
## What the sandbox does and does not stop
|
|
32
|
+
|
|
33
|
+
`ctx.sandbox` runs code you do not trust, such as a **tool** an agent just wrote, in a separate Node process with the permission model on (`node --permission`):
|
|
34
|
+
|
|
35
|
+
- It **stops**: reading any file outside the tool's own folder; writing files; starting child processes or workers; loading native addons; using the inspector. It gets an empty environment (no keys, no paths). It is killed after a time limit and capped in memory and output size. Calls are independent: nothing survives into the next one.
|
|
36
|
+
- It **does not stop**: network access (Node 24 has no network permission: restrict egress outside the process where that matters), and it does not apply to plugins installed live (those are not run in the sandbox).
|
|
37
|
+
|
|
38
|
+
## Checklist for a deployment
|
|
39
|
+
|
|
40
|
+
1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).
|
|
41
|
+
2. Start from a template that is not `agent`, or remove the agent rows.
|
|
42
|
+
3. Do not set `allowInProduction` on the door unless the host is a single-user desktop app.
|
|
43
|
+
4. Keep `ACRYL_DOOR=off` in any environment where an agent should not be able to see the page.
|
|
@@ -584,21 +584,13 @@ const route = app.put(
|
|
|
584
584
|
|
|
585
585
|
## Custom `fetch` method
|
|
586
586
|
|
|
587
|
-
You can set the custom `fetch` method.
|
|
588
|
-
|
|
589
|
-
In the following example script for Cloudflare Worker, the Service Bindings' `fetch` method is used instead of the default `fetch`.
|
|
590
|
-
|
|
591
|
-
```toml
|
|
592
|
-
# wrangler.toml
|
|
593
|
-
services = [
|
|
594
|
-
{ binding = "AUTH", service = "auth-service" },
|
|
595
|
-
]
|
|
596
|
-
```
|
|
587
|
+
You can set the custom `fetch` method: anything with the `fetch` signature works in place of the global one, such as a client that adds a header or a test double.
|
|
597
588
|
|
|
598
589
|
```ts
|
|
599
590
|
// src/client.ts
|
|
600
591
|
const client = hc<CreateProfileType>('http://localhost', {
|
|
601
|
-
fetch:
|
|
592
|
+
fetch: (input, init) =>
|
|
593
|
+
fetch(input, { ...init, headers: { ...init?.headers, authorization: `Bearer ${token}` } }),
|
|
602
594
|
})
|
|
603
595
|
```
|
|
604
596
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Adapter Helper
|
|
2
2
|
|
|
3
|
-
The Adapter Helper
|
|
3
|
+
The Adapter Helper reads an app's environment the same way on every runtime it runs on.
|
|
4
4
|
|
|
5
5
|
## Import
|
|
6
6
|
|
|
@@ -11,50 +11,25 @@ import { env, getRuntimeKey } from 'acrylblends/adapter'
|
|
|
11
11
|
|
|
12
12
|
## `env()`
|
|
13
13
|
|
|
14
|
-
The `env()` function
|
|
14
|
+
The `env()` function returns the environment the host gives the app. On Node.js, the verified runtime, that is `process.env`; on Bun it is `Bun.env` (and `process.env`), and the two entries a `.env` file adds are there as well. A host that passes its own environment to `app.fetch(request, env)` gets that instead.
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
17
|
import { env } from 'acrylblends/adapter'
|
|
18
18
|
|
|
19
19
|
app.get('/env', (c) => {
|
|
20
|
-
// NAME is process.env.NAME on Node.js
|
|
21
|
-
// NAME is the value written in `wrangler.toml` on Cloudflare
|
|
20
|
+
// NAME is process.env.NAME on Node.js and Bun
|
|
22
21
|
const { NAME } = env<{ NAME: string }>(c)
|
|
23
22
|
return c.text(NAME)
|
|
24
23
|
})
|
|
25
24
|
```
|
|
26
25
|
|
|
27
|
-
Supported Runtimes, Serverless Platforms and Cloud Services:
|
|
28
|
-
|
|
29
|
-
- Cloudflare Workers
|
|
30
|
-
- `wrangler.toml`
|
|
31
|
-
- `wrangler.jsonc`
|
|
32
|
-
- Deno
|
|
33
|
-
- [`Deno.env`](https://docs.deno.com/runtime/manual/basics/env_variables)
|
|
34
|
-
- `.env` file
|
|
35
|
-
- Bun
|
|
36
|
-
- [`Bun.env`](https://bun.com/guides/runtime/set-env)
|
|
37
|
-
- `process.env`
|
|
38
|
-
- Node.js
|
|
39
|
-
- `process.env`
|
|
40
|
-
- Vercel
|
|
41
|
-
- [Environment Variables on Vercel](https://vercel.com/docs/projects/environment-variables)
|
|
42
|
-
- AWS Lambda
|
|
43
|
-
- [Environment Variables on AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/samples-blank.html#samples-blank-architecture)
|
|
44
|
-
- Lambda@Edge\
|
|
45
|
-
Environment Variables on Lambda are [not supported](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html) by Lambda@Edge, you need to use [Lambda@Edge event](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-event-structure.html) as an alternative.
|
|
46
|
-
- Fastly Compute\
|
|
47
|
-
On Fastly Compute, you can use the ConfigStore to manage user-defined data.
|
|
48
|
-
- Netlify\
|
|
49
|
-
On Netlify, you can use the [Netlify Contexts](https://docs.netlify.com/site-deploys/overview/#deploy-contexts) to manage user-defined data.
|
|
50
|
-
|
|
51
26
|
### Specify the runtime
|
|
52
27
|
|
|
53
|
-
|
|
28
|
+
`env()` reads the runtime itself. Pass the runtime key as the second argument when a host embeds the app and detects it differently, or in a test that fixes the key:
|
|
54
29
|
|
|
55
30
|
```ts
|
|
56
31
|
app.get('/env', (c) => {
|
|
57
|
-
const { NAME } = env<{ NAME: string }>(c, '
|
|
32
|
+
const { NAME } = env<{ NAME: string }>(c, 'node')
|
|
58
33
|
return c.text(NAME)
|
|
59
34
|
})
|
|
60
35
|
```
|
|
@@ -65,23 +40,18 @@ The `getRuntimeKey()` function returns the identifier of the current runtime.
|
|
|
65
40
|
|
|
66
41
|
```ts
|
|
67
42
|
app.get('/', (c) => {
|
|
68
|
-
if (getRuntimeKey() === '
|
|
69
|
-
return c.text('You are on Cloudflare')
|
|
70
|
-
} else if (getRuntimeKey() === 'bun') {
|
|
43
|
+
if (getRuntimeKey() === 'bun') {
|
|
71
44
|
return c.text('You are on Bun')
|
|
72
45
|
}
|
|
73
|
-
|
|
46
|
+
return c.text(`You are on ${getRuntimeKey()}`)
|
|
74
47
|
})
|
|
75
48
|
```
|
|
76
49
|
|
|
77
|
-
### Available
|
|
50
|
+
### Available runtime keys
|
|
78
51
|
|
|
79
|
-
|
|
52
|
+
The keys follow [WinterCG's Runtime Keys proposal](https://runtime-keys.proposal.wintercg.org/):
|
|
80
53
|
|
|
81
|
-
- `
|
|
82
|
-
- `
|
|
83
|
-
- `
|
|
84
|
-
- `
|
|
85
|
-
- `edge-light` - Vercel Edge Functions
|
|
86
|
-
- `fastly` - Fastly Compute
|
|
87
|
-
- `other` - Other unknown runtimes keys
|
|
54
|
+
- `node` - Node.js, the verified runtime
|
|
55
|
+
- `bun` - Bun, experimental
|
|
56
|
+
- `deno`, `workerd`, `edge-light`, `fastly` - keys the helper still recognizes for a host that embeds an app in that runtime; 1.0 ships no adapter for them (see [Other runtimes](../getting-started/other-runtimes.md))
|
|
57
|
+
- `other` - a runtime the helper does not recognize
|
|
@@ -4,14 +4,7 @@ The ConnInfo Helper helps you to get the connection information. For example, yo
|
|
|
4
4
|
|
|
5
5
|
## Import
|
|
6
6
|
|
|
7
|
-
Each adapter has its own `getConnInfo`: `acrylblends/node-server
|
|
8
|
-
|
|
9
|
-
**Cloudflare Workers**
|
|
10
|
-
|
|
11
|
-
```ts
|
|
12
|
-
import { Acryl } from 'acrylblends'
|
|
13
|
-
import { getConnInfo } from 'acrylblends/cloudflare-workers'
|
|
14
|
-
```
|
|
7
|
+
Each adapter has its own `getConnInfo`: `acrylblends/node-server` and `acrylblends/bun` (experimental).
|
|
15
8
|
|
|
16
9
|
**Bun**
|
|
17
10
|
|
|
@@ -20,34 +13,6 @@ import { Acryl } from 'acrylblends'
|
|
|
20
13
|
import { getConnInfo } from 'acrylblends/bun'
|
|
21
14
|
```
|
|
22
15
|
|
|
23
|
-
**Vercel**
|
|
24
|
-
|
|
25
|
-
```ts
|
|
26
|
-
import { Acryl } from 'acrylblends'
|
|
27
|
-
import { getConnInfo } from 'acrylblends/vercel'
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
**AWS Lambda**
|
|
31
|
-
|
|
32
|
-
```ts
|
|
33
|
-
import { Acryl } from 'acrylblends'
|
|
34
|
-
import { getConnInfo } from 'acrylblends/aws-lambda'
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
**Netlify**
|
|
38
|
-
|
|
39
|
-
```ts
|
|
40
|
-
import { Acryl } from 'acrylblends'
|
|
41
|
-
import { getConnInfo } from 'acrylblends/netlify'
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
**Lambda@Edge**
|
|
45
|
-
|
|
46
|
-
```ts
|
|
47
|
-
import { Acryl } from 'acrylblends'
|
|
48
|
-
import { getConnInfo } from 'acrylblends/lambda-edge'
|
|
49
|
-
```
|
|
50
|
-
|
|
51
16
|
**Node.js**
|
|
52
17
|
|
|
53
18
|
```ts
|
|
@@ -47,7 +47,7 @@ app.get('/streamText', (c) => {
|
|
|
47
47
|
|
|
48
48
|
**Warning.**
|
|
49
49
|
|
|
50
|
-
|
|
50
|
+
A proxy or a host that compresses the response body can hold a stream back until it ends. If a stream arrives only when it is complete, send `Content-Encoding: Identity` for that route.
|
|
51
51
|
|
|
52
52
|
```ts
|
|
53
53
|
app.get('/streamText', (c) => {
|
|
@@ -1,18 +1,11 @@
|
|
|
1
1
|
# WebSocket Helper
|
|
2
2
|
|
|
3
3
|
WebSocket Helper is a helper for server-side WebSockets in Acryl applications.
|
|
4
|
-
The Node.js
|
|
4
|
+
The Node.js and Bun adapters are available.
|
|
5
5
|
|
|
6
6
|
## Import
|
|
7
7
|
|
|
8
|
-
The Node.js adapter (`acrylblends/node-server`)
|
|
9
|
-
|
|
10
|
-
**Cloudflare Workers**
|
|
11
|
-
|
|
12
|
-
```ts
|
|
13
|
-
import { Acryl } from 'acrylblends'
|
|
14
|
-
import { upgradeWebSocket } from 'acrylblends/cloudflare-workers'
|
|
15
|
-
```
|
|
8
|
+
The Node.js adapter (`acrylblends/node-server`) and the Bun adapter (`acrylblends/bun`, experimental) provide `upgradeWebSocket`. The other platforms have no adapter in 1.0.
|
|
16
9
|
|
|
17
10
|
**Bun**
|
|
18
11
|
|
|
@@ -63,7 +56,7 @@ app.get(
|
|
|
63
56
|
|
|
64
57
|
Available events:
|
|
65
58
|
|
|
66
|
-
- `onOpen`
|
|
59
|
+
- `onOpen`
|
|
67
60
|
- `onMessage`
|
|
68
61
|
- `onClose`
|
|
69
62
|
- `onError`
|
|
@@ -103,7 +96,7 @@ See the examples using WebSocket Helper.
|
|
|
103
96
|
```ts
|
|
104
97
|
// server.ts
|
|
105
98
|
import { Acryl } from 'acrylblends'
|
|
106
|
-
import { upgradeWebSocket } from 'acrylblends/
|
|
99
|
+
import { upgradeWebSocket } from 'acrylblends/node-server'
|
|
107
100
|
|
|
108
101
|
const app = new Acryl().get(
|
|
109
102
|
'/ws',
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Basic Auth Middleware
|
|
2
2
|
|
|
3
3
|
This middleware can apply Basic authentication to a specified path.
|
|
4
|
-
Implementing Basic authentication
|
|
4
|
+
Implementing Basic authentication by hand is more complicated than it seems, but with this middleware, it's a breeze.
|
|
5
5
|
|
|
6
6
|
For more information about how the Basic auth scheme works under the hood, see the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme).
|
|
7
7
|
|