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.
Files changed (49) hide show
  1. package/README.md +4 -2
  2. package/dist/index.d.ts +10 -1
  3. package/dist/index.js +37 -16
  4. package/dist/index.js.map +1 -1
  5. package/docs/framework/README.md +5 -3
  6. package/docs/framework/agents/index.md +1 -1
  7. package/docs/framework/api/acryl.md +5 -17
  8. package/docs/framework/api/context.md +12 -61
  9. package/docs/framework/api/presets.md +1 -1
  10. package/docs/framework/api/request.md +3 -3
  11. package/docs/framework/api/summary.md +1 -1
  12. package/docs/framework/concepts/web-standard.md +6 -16
  13. package/docs/framework/cordis/acryl-in-a-cordis-app.md +13 -8
  14. package/docs/framework/cordis/migration-from-0-4.md +1 -1
  15. package/docs/framework/cordis/migration-to-1-0.md +45 -0
  16. package/docs/framework/cordis/node-server.md +2 -2
  17. package/docs/framework/getting-started/basic.md +15 -10
  18. package/docs/framework/getting-started/desktop.md +1 -1
  19. package/docs/framework/getting-started/other-runtimes.md +10 -14
  20. package/docs/framework/guides/create-acrylblends.md +4 -2
  21. package/docs/framework/guides/data.md +1 -1
  22. package/docs/framework/guides/faq.md +1 -1
  23. package/docs/framework/guides/jsx-dom.md +1 -1
  24. package/docs/framework/guides/production.md +43 -0
  25. package/docs/framework/guides/rpc.md +3 -11
  26. package/docs/framework/helpers/adapter.md +13 -43
  27. package/docs/framework/helpers/conninfo.md +1 -36
  28. package/docs/framework/helpers/streaming.md +1 -1
  29. package/docs/framework/helpers/websocket.md +4 -11
  30. package/docs/framework/middleware/builtin/basic-auth.md +1 -1
  31. package/docs/framework/middleware/builtin/cache.md +2 -22
  32. package/docs/framework/middleware/builtin/compress.md +1 -1
  33. package/docs/framework/middleware/builtin/context-storage.md +10 -14
  34. package/docs/framework/middleware/builtin/cors.md +1 -2
  35. package/docs/framework/middleware/builtin/ip-restriction.md +1 -1
  36. package/docs/framework/middleware/builtin/jsx-renderer.md +1 -1
  37. package/docs/framework/middleware/builtin/logger.md +1 -1
  38. package/docs/framework/middleware/builtin/loopback-only.md +1 -1
  39. package/docs/framework/middleware/builtin/mount.md +1 -1
  40. package/docs/framework/middleware/builtin/request-id.md +13 -20
  41. package/docs/framework/middleware/builtin/timing.md +1 -2
  42. package/package.json +2 -2
  43. package/docs/framework/getting-started/aws-lambda.md +0 -115
  44. package/docs/framework/getting-started/cloudflare-pages.md +0 -53
  45. package/docs/framework/getting-started/cloudflare-workers.md +0 -67
  46. package/docs/framework/getting-started/lambda-edge.md +0 -41
  47. package/docs/framework/getting-started/netlify.md +0 -25
  48. package/docs/framework/getting-started/service-worker.md +0 -33
  49. 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
- Cloudflare Workers, Deno, and Bun also are built upon Web Standards.
8
- For example, a server that returns "Hello World" could be written as below. This could run on Cloudflare Workers and Bun.
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, which means that Acryl can run on any runtime that supports them.
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
- - Cloudflare Workers (`workerd`)
22
- - Deno
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
- It also works on Netlify and other platforms.
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 'acryl-router'
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
- | Package | Responsibility |
143
- | --- | --- |
144
- | `acryl-router` | the application API and the Cordis `router` service |
145
- | `acryl-router-http` | serving router prefixes on the ACRYL Host's web server |
146
- | `acryl-node-server` | serving the whole router from a standalone Node.js process |
147
- | `acryl-state` | shared application state across surfaces |
148
- | `acryl-inspect` | runtime inspection of mounts, routes and plugins |
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 'acryl-router'`, `new Acryl()` |
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 'acryl-router'
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 works on every verified runtime, with a different
4
- entry point for each. This page shows the basic usage.
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
- Starter templates are available for each runtime. Use the "create-acrylblends" command.
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
- ? Which template do you want to use?
38
- ❯ nodejs
39
- acryl-app
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 `acryl-app` adds an agent that can extend it while it
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
- Write your first application in `src/index.ts`. The example below is a starter Acryl application.
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 every runtime; what differs is how the runtime starts the app (see [Node.js](nodejs.md) and [Bun](bun.md)).
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) is not yet available.
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 `acryl-app` template or `acrylblends init`). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
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
- ## Hosting platforms with an adapter
5
+ ## Runtimes with an adapter
6
6
 
7
- These platforms have an adapter in acrylblends, ported from the upstream adapters with their tests. Each is called with the platform's own events in the framework's release check; the ACRYL team has not deployed to these platforms, so try a first deploy on a test project.
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
- | Platform | Guide | Import |
10
- | --- | --- | --- |
11
- | AWS Lambda (API Gateway, ALB, Function URLs, VPC Lattice) | [AWS Lambda](aws-lambda.md) | `acrylblends/aws-lambda` |
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 yet:
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 platform has an adapter and a test that calls it.
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
- | `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
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`. Skips the template question; a bare name after the directory means the same. | `--template notes` |
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 'acryl-db'
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 with an adapter (AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify, Service Worker) and the ones without are listed on [Other runtimes](../getting-started/other-runtimes.md).
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`. For Deno, modify the deno.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: c.env.AUTH.fetch.bind(c.env.AUTH),
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 provides a seamless way to interact with various platforms through a unified interface.
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 facilitates retrieving environment variables across different runtimes, extending beyond just Cloudflare Workers' Bindings. The value that can be retrieved with `env(c)` may be different for each runtime.
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 or Bun
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
- You can specify the runtime to get environment variables by passing the runtime key as the second argument.
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, 'workerd')
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() === 'workerd') {
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 Runtimes Keys
50
+ ### Available runtime keys
78
51
 
79
- Here are the available runtimes keys, unavailable runtime key runtimes may be supported and labeled as `other`, with some being inspired by [WinterCG's Runtime Keys](https://runtime-keys.proposal.wintercg.org/):
52
+ The keys follow [WinterCG's Runtime Keys proposal](https://runtime-keys.proposal.wintercg.org/):
80
53
 
81
- - `workerd` - Cloudflare Workers
82
- - `deno`
83
- - `bun`
84
- - `node`
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`, `acrylblends/cloudflare-workers`, `acrylblends/vercel`, `acrylblends/aws-lambda`, `acrylblends/netlify`, `acrylblends/lambda-edge` and `acrylblends/bun`. The Bun example is not type-checked by the docs tests, which run without Bun's types.
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
- If you are developing an application for Cloudflare Workers, streaming may not work well on Wrangler. If so, add `Identity` for `Content-Encoding` header.
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, Cloudflare Workers and Bun adapters are available.
4
+ The Node.js and Bun adapters are available.
5
5
 
6
6
  ## Import
7
7
 
8
- The Node.js adapter (`acrylblends/node-server`), the Cloudflare Workers adapter (`acrylblends/cloudflare-workers`) and the Bun adapter (`acrylblends/bun`) provide `upgradeWebSocket`. The other platforms have no WebSocket support in their adapters. The Bun adapter is checked on Bun in the framework's release check; its examples below are not type-checked by the docs tests, which run without Bun's types.
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` - Currently, Cloudflare Workers does not support it.
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/cloudflare-workers'
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 with Cloudflare Workers or other platforms is more complicated than it seems, but with this middleware, it's a breeze.
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