@acryldev/create-blends 1.7.1 → 1.7.2
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/{LICENSE → docs/framework/LICENSE} +3 -1
- package/docs/framework/README.md +70 -0
- package/docs/framework/agents/index.md +59 -0
- package/docs/framework/api/acryl.md +247 -0
- package/docs/framework/api/context.md +478 -0
- package/docs/framework/api/exception.md +80 -0
- package/docs/framework/api/index.md +12 -0
- package/docs/framework/api/presets.md +62 -0
- package/docs/framework/api/request.md +396 -0
- package/docs/framework/api/routing.md +303 -0
- package/docs/framework/api/summary.md +143 -0
- package/docs/framework/concepts/benchmarks.md +26 -0
- package/docs/framework/concepts/developer-experience.md +5 -0
- package/docs/framework/concepts/middleware.md +21 -0
- package/docs/framework/concepts/motivation.md +14 -0
- package/docs/framework/concepts/routers.md +63 -0
- package/docs/framework/concepts/stacks.md +235 -0
- package/docs/framework/concepts/web-standard.md +27 -0
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
- package/docs/framework/cordis/concepts.md +105 -0
- package/docs/framework/cordis/middleware.md +8 -0
- package/docs/framework/cordis/migration-from-0-3.md +111 -0
- package/docs/framework/cordis/migration-from-0-4.md +14 -0
- package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
- package/docs/framework/cordis/migration-to-1-0.md +46 -0
- package/docs/framework/cordis/mounting.md +85 -0
- package/docs/framework/cordis/node-server.md +100 -0
- package/docs/framework/cordis/plugin-lifecycle.md +111 -0
- package/docs/framework/cordis/surfaces.md +71 -0
- package/docs/framework/cordis/transport-and-cancellation.md +57 -0
- package/docs/framework/cordis/validation.md +135 -0
- package/docs/framework/getting-started/basic.md +201 -0
- package/docs/framework/getting-started/bun.md +219 -0
- package/docs/framework/getting-started/deploy.md +133 -0
- package/docs/framework/getting-started/desktop.md +80 -0
- package/docs/framework/getting-started/nodejs.md +365 -0
- package/docs/framework/getting-started/other-runtimes.md +30 -0
- package/docs/framework/guides/best-practices.md +231 -0
- package/docs/framework/guides/bring-your-own-tool.md +218 -0
- package/docs/framework/guides/client-modules.md +210 -0
- package/docs/framework/guides/create-acrylblends.md +143 -0
- package/docs/framework/guides/data.md +314 -0
- package/docs/framework/guides/examples.md +3 -0
- package/docs/framework/guides/faq.md +19 -0
- package/docs/framework/guides/forms-and-sessions.md +235 -0
- package/docs/framework/guides/helpers.md +33 -0
- package/docs/framework/guides/jsx-dom.md +301 -0
- package/docs/framework/guides/jsx.md +487 -0
- package/docs/framework/guides/middleware.md +253 -0
- package/docs/framework/guides/production.md +80 -0
- package/docs/framework/guides/rpc.md +878 -0
- package/docs/framework/guides/testing.md +133 -0
- package/docs/framework/guides/validation.md +470 -0
- package/docs/framework/helpers/accepts.md +60 -0
- package/docs/framework/helpers/adapter.md +57 -0
- package/docs/framework/helpers/conninfo.md +77 -0
- package/docs/framework/helpers/cookie.md +232 -0
- package/docs/framework/helpers/css.md +282 -0
- package/docs/framework/helpers/dev.md +64 -0
- package/docs/framework/helpers/factory.md +180 -0
- package/docs/framework/helpers/html.md +123 -0
- package/docs/framework/helpers/jwt.md +184 -0
- package/docs/framework/helpers/proxy.md +115 -0
- package/docs/framework/helpers/route.md +143 -0
- package/docs/framework/helpers/ssg.md +390 -0
- package/docs/framework/helpers/streaming.md +224 -0
- package/docs/framework/helpers/testing.md +118 -0
- package/docs/framework/helpers/websocket.md +208 -0
- package/docs/framework/middleware/builtin/basic-auth.md +165 -0
- package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
- package/docs/framework/middleware/builtin/body-limit.md +71 -0
- package/docs/framework/middleware/builtin/cache.md +99 -0
- package/docs/framework/middleware/builtin/combine.md +94 -0
- package/docs/framework/middleware/builtin/compress.md +59 -0
- package/docs/framework/middleware/builtin/context-storage.md +74 -0
- package/docs/framework/middleware/builtin/cors.md +134 -0
- package/docs/framework/middleware/builtin/csrf.md +105 -0
- package/docs/framework/middleware/builtin/etag.md +54 -0
- package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
- package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
- package/docs/framework/middleware/builtin/jwk.md +192 -0
- package/docs/framework/middleware/builtin/jwt.md +145 -0
- package/docs/framework/middleware/builtin/language.md +232 -0
- package/docs/framework/middleware/builtin/logger.md +74 -0
- package/docs/framework/middleware/builtin/loopback-only.md +31 -0
- package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
- package/docs/framework/middleware/builtin/method-override.md +80 -0
- package/docs/framework/middleware/builtin/mount.md +103 -0
- package/docs/framework/middleware/builtin/pretty-json.md +53 -0
- package/docs/framework/middleware/builtin/request-id.md +87 -0
- package/docs/framework/middleware/builtin/secure-headers.md +247 -0
- package/docs/framework/middleware/builtin/timeout.md +98 -0
- package/docs/framework/middleware/builtin/timing.md +100 -0
- package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
- package/docs/framework/middleware/third-party.md +4 -0
- package/docs/framework/workshop/README.md +294 -0
- package/docs/framework/workshop/facilitator.md +101 -0
- package/package.json +2 -2
|
@@ -1,6 +1,8 @@
|
|
|
1
|
+
The pages in this folder are adapted in part from the Hono documentation (https://github.com/honojs/website), used under this license:
|
|
2
|
+
|
|
1
3
|
MIT License
|
|
2
4
|
|
|
3
|
-
Copyright (c)
|
|
5
|
+
Copyright (c) 2021 - present, Yusuke Wada and Hono contributors
|
|
4
6
|
|
|
5
7
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
8
|
of this software and associated documentation files (the "Software"), to deal
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Acryl
|
|
2
|
+
|
|
3
|
+
Acryl is a small web framework built on Web Standards. You write handlers over the standard `Request` and `Response`, and the same application runs on Node.js (and, experimentally, Bun), and inside a Cordis app as a plugin that an agent can extend while it runs.
|
|
4
|
+
|
|
5
|
+
```ts twoslash
|
|
6
|
+
import { Acryl } from '@acryldev/blends'
|
|
7
|
+
const app = new Acryl()
|
|
8
|
+
|
|
9
|
+
app.get('/', (c) => c.text('Acryl!'))
|
|
10
|
+
|
|
11
|
+
export default app
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Quick Start
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
npm create @acryldev/blends@latest my-app
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Other package managers work the same way: `pnpm create @acryldev/blends@latest`, `yarn create acrylblends`, `bun create acrylblends@latest`.
|
|
21
|
+
Every template is a Cordis app (`blend.yaml`, plugins in `plugins/`). The starter asks which one you want, from the same list `acrylblends init --template` takes: `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (`acryl-app` is the old name for `agent`), and `npm create @acryldev/blends@latest my-app notes` names it directly. See [Getting started](getting-started/basic.md).
|
|
22
|
+
|
|
23
|
+
## What is in the box
|
|
24
|
+
|
|
25
|
+
- **Routing** with several routers behind one API: `RegExpRouter`, `TrieRouter`, `SmartRouter` (the default, which chooses between them), `LinearRouter` and `PatternRouter`.
|
|
26
|
+
See [Routers](concepts/routers.md) and [Routing](api/routing.md).
|
|
27
|
+
- **Web Standards only.** Handlers receive a `Context` over `Request` and return `Response`, with no runtime-specific objects. See [Web Standards](concepts/web-standard.md).
|
|
28
|
+
- **Built-in middleware** for authentication, CORS, CSRF, compression, ETag, logging, request ids, secure headers, timeouts and more.
|
|
29
|
+
See [Built-in middleware](middleware/builtin/basic-auth.md) and [Middleware](concepts/middleware.md).
|
|
30
|
+
- **Helpers** for cookies, streaming and server-sent events, content negotiation, HTML templates, WebSockets and testing. See [Helpers](guides/helpers.md).
|
|
31
|
+
- **Typed routes and a typed client.** Route types flow from the server to `acrylblends/client`. See [RPC](guides/rpc.md).
|
|
32
|
+
- **Data** through one small `db` interface: SQL with numbered migrations on SQLite; the same code runs on Postgres through an optional plugin. See [Data](guides/data.md).
|
|
33
|
+
- **Validation** with a validator function or any Standard Schema library. See [Validation](guides/validation.md).
|
|
34
|
+
- **A Cordis plugin around it.** A plugin mounts an app with `ctx.router.route`, the mount goes away when the plugin unloads, and a coding agent can write such plugins
|
|
35
|
+
into a running app. See [Acryl in a Cordis app](cordis/acryl-in-a-cordis-app.md) and [Agents](agents/index.md).
|
|
36
|
+
|
|
37
|
+
## Runtimes
|
|
38
|
+
|
|
39
|
+
Verified: Node.js. Bun is experimental (its adapter, `acrylblends/bun`, has one smoke gate). The other hosting adapters of the upstream (AWS Lambda, Lambda@Edge, Cloudflare, Vercel, Netlify, Service Workers) are not part of the package: no gate of ours deploys to them. See [Other runtimes](getting-started/other-runtimes.md).
|
|
40
|
+
|
|
41
|
+
## Not yet available
|
|
42
|
+
|
|
43
|
+
Some parts of the documented API surface are not part of the package yet, and their pages say so: the Vite plugin for static site generation, a registry of third-party middleware, and benchmark results.
|
|
44
|
+
They are enabled as they are built.
|
|
45
|
+
|
|
46
|
+
## Where to read next
|
|
47
|
+
|
|
48
|
+
| I want to | Read |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| Run something in five minutes | [Getting started](getting-started/basic.md) |
|
|
51
|
+
| Run the app as a desktop app | [Desktop](getting-started/desktop.md) |
|
|
52
|
+
| Run it on a server | [Deploy](getting-started/deploy.md) |
|
|
53
|
+
| Run it on another runtime | [Other runtimes](getting-started/other-runtimes.md): Node.js is the verified one, [Bun](getting-started/bun.md) is experimental |
|
|
54
|
+
| Look up a call | [API](api/index.md), [Routing](api/routing.md), [Context](api/context.md), [Request](api/request.md), [API summary](api/summary.md) |
|
|
55
|
+
| Understand the design | [Concepts](concepts/motivation.md) |
|
|
56
|
+
| Copy a pattern | [Guides](guides/best-practices.md), [Validation](guides/validation.md), [Testing](guides/testing.md), [Data, migrations and choosing a store](guides/data.md), [Forms, sessions and a database](guides/forms-and-sessions.md), [Client components without a bundler](guides/client-modules.md), [Bring your own tool](guides/bring-your-own-tool.md) |
|
|
57
|
+
| Run the 90-minute workshop | [Workshop](workshop/README.md), and the room around it in [Facilitator notes](workshop/facilitator.md) |
|
|
58
|
+
| Use Acryl inside a Cordis app | [Acryl in a Cordis app](cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](cordis/plugin-lifecycle.md), [Mounting](cordis/mounting.md) |
|
|
59
|
+
| Move from the 0.3 router calls | [Migration from 0.3](cordis/migration-from-0-3.md) |
|
|
60
|
+
| Know what runs in production, and what the sandbox stops | [What runs in production](guides/production.md) |
|
|
61
|
+
| Move to 1.0 (`acrylblends upgrade`) | [Migration to 1.0](cordis/migration-to-1-0.md) |
|
|
62
|
+
| Move from the 0.4 names (`App`) | [Migration from 0.4](cordis/migration-from-0-4.md) |
|
|
63
|
+
|
|
64
|
+
The license of these pages and of the framework source they describe is in [LICENSE](LICENSE).
|
|
65
|
+
|
|
66
|
+
## TypeScript in a Cordis app
|
|
67
|
+
|
|
68
|
+
An app's `tsconfig.json` can extend `@acryldev/router/tsconfig.app.json` (ES2024 with the DOM types, strict). The DOM types are optional: every
|
|
69
|
+
entry point's types also stand with only `"lib": ["ES2024"]` and `"types": ["node"]`, the setting a Host-only plugin uses so browser globals
|
|
70
|
+
do not typecheck in server code (the router's `tests/no-dom` fixture checks this on every typecheck).
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Agents
|
|
2
|
+
|
|
3
|
+
A coding agent (Claude Code, Codex, OpenCode, Copilot and others) builds on Acryl best when the documentation is in the folder it works in. A project created with
|
|
4
|
+
`npm create @acryldev/blends@latest` (and one made with `npx acrylblends init`) therefore contains:
|
|
5
|
+
|
|
6
|
+
- `docs/framework/`: these pages. Start at `README.md`; `api/summary.md` is the one-page summary of the API.
|
|
7
|
+
- `AGENTS.md`: where the API is, how a feature is built (an `Acryl` app mounted with `ctx.router.route`, a plugin registered in `src/app.ts` and `blend.yaml`, a state cell),
|
|
8
|
+
the defaults and how each is swapped, the things that surprise people, and what must pass before a task is done (`npm test` and `npm run check`).
|
|
9
|
+
- `CLAUDE.md`: the same text as `AGENTS.md`, so tools that read either file read the same guide.
|
|
10
|
+
- Two skills, `acryl-app` and `cordis-plugin`, in `.claude/skills/<name>/SKILL.md` and `.agents/skills/<name>/SKILL.md` (the same text in both places): how the app is put together and how to change and check it through the door, and how to add a feature as a Cordis plugin.
|
|
11
|
+
- `.gitignore` lists `.acryl/`, the folder the door keeps its secret and state in, so `git add -A` stages none of it.
|
|
12
|
+
|
|
13
|
+
## One plugin folder
|
|
14
|
+
|
|
15
|
+
Every plugin of an app is a folder in `plugins/<name>/`, at the root of the app: the library plugins `acrylblends add <name>` copies (listed in `plugins/library.json`), and the
|
|
16
|
+
plugins you or an agent write. There is no `src/plugins/` and no `extensions/`. An app made before this layout keeps working for one release: the CLI reads its `src/plugins/` and
|
|
17
|
+
`extensions/` and warns; move them with `git mv src/plugins plugins`, fix the paths in `tsconfig.json`, `package.json` and `src/`, and `git mv extensions/<name> plugins/<name>`.
|
|
18
|
+
|
|
19
|
+
## Defaults, and how to swap each
|
|
20
|
+
|
|
21
|
+
The framework is not rigid: every choice is a plugin behind a port, and the default is only a fallback. A new app names each default in `AGENTS.md`: records on the `db` port
|
|
22
|
+
with SQLite, small state on the `kv` port with one JSON file, the Node server, the browser as the window (`acrylblends add desktop-shell` adds Electron), browser code through
|
|
23
|
+
`clientModules`. A swap changes the one file that opens or mounts the choice (the opener, `src/db.ts`; or `src/app.ts` in a Blend app), because nothing else imports a provider
|
|
24
|
+
(`acrylblends check-deps` checks it). An outside tool, such as a database server or a bundler, joins the app as a provider in `plugins/<name>/` that implements the port.
|
|
25
|
+
|
|
26
|
+
## What an agent can do inside a running app
|
|
27
|
+
|
|
28
|
+
The `agent` template (a Cordis app; `acryl-app` is its old name and still works) also lets an agent change the app while it runs:
|
|
29
|
+
|
|
30
|
+
1. The agent writes a plugin into `plugins/<name>/index.ts`. The plugin may import `acrylblends` and the other subpaths by name.
|
|
31
|
+
2. The app installs it as a child plugin, runs its `check(ctx)` with the plugin's own context, and keeps the previous version if the new one fails to start or to pass its check.
|
|
32
|
+
3. A plugin's routes are an `Acryl` app mounted with `ctx.router.route`, so removing the plugin removes its routes.
|
|
33
|
+
|
|
34
|
+
See [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](../cordis/plugin-lifecycle.md) and [Mounting](../cordis/mounting.md).
|
|
35
|
+
|
|
36
|
+
## The agent panel and the terminals
|
|
37
|
+
|
|
38
|
+
The panel is a chat button on every page of the running app. **A new app from the `agent` template has it** (`npm create @acryldev/blends@latest my-app agent`), and `driver-pty` adds real terminals to it. Both are **development only** (see [what runs in production](../guides/production.md)).
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
npm create @acryldev/blends@latest my-app agent
|
|
42
|
+
cd my-app
|
|
43
|
+
npm install
|
|
44
|
+
npm run dev # the panel is the button at the corner of the page
|
|
45
|
+
npx acrylblends add driver-pty # optional: real terminals (pty:claude, pty:codex, pty:pi) in the panel
|
|
46
|
+
npm install
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
- The panel needs the `agent` and `extensions` rows, which only the `agent` template has: `add agent-panel` on an app without them (a `blank` app) refuses before it copies anything and says which rows are missing, and on an `agent` app it says the panel is already there. An agent-template app made before 1.0.5 gets it with `npx acrylblends add agent-panel`.
|
|
50
|
+
- `add driver-pty` puts the driver's row after the panel's in `blend.yaml` and registers it in `src/app.ts`.
|
|
51
|
+
- A **run belongs to the app, not to the page**: when the page reloads (the door reloads it after a plugin change) the panel shows the question and the events so far and follows the run to its end; **Stop** is the only thing that cancels it.
|
|
52
|
+
- **The panel's coding agents are yours.** `claude`, `codex` and `pi` run on the machine that runs the app, in the app folder, with the login of the person who started it: `claude` and `codex` use their own signed-in sessions, and `pi` is offered when `DEEPSEEK_API_KEY` is set or `pi` has stored a DeepSeek login (`~/.pi/agent/auth.json`, read from the `HOME` of the process that runs the app: an app started under another `HOME` does not see the login, and the panel then lists `pty:pi` but no chat `pi`). A program that is not installed, or is not logged in, is not offered; nothing is shared between machines, and a workshop laptop needs its own login. The panel's own `agent` (the offline scripted one) needs none.
|
|
53
|
+
- `pi` has to be an executable on the `PATH`; a shell function that wraps the binary is fine as long as the binary itself is found by `which pi`. Install it with `npm i -g @earendil-works/pi-coding-agent` (the older `@mariozechner/pi-coding-agent` is deprecated). It reaches DeepSeek with `DEEPSEEK_API_KEY` in the environment of the app, or with the key it stored when its owner logged in (`~/.pi/agent/auth.json`, a `deepseek` entry); without one the panel does not offer it. On Windows an npm-installed `claude`, `codex` or `pi` is a `.cmd` shim: the panel reads the script the shim runs and starts it with Node (no shell, so the message is not passed through cmd.exe quoting), and Stop ends the whole process tree.
|
|
54
|
+
- `driver-pty` brings `node-pty`, which ships prebuilt binaries for macOS, Windows and Linux. npm 11 and pnpm warn that its install script was not run (they ask you to approve dependency install scripts); you can ignore the warning. If no `pty:` terminal is offered and the app prints why at start, approve and rebuild: `npm approve-scripts node-pty`, then `npm rebuild node-pty` (pnpm: `pnpm approve-builds`).
|
|
55
|
+
|
|
56
|
+
## Checking that an agent can use the docs
|
|
57
|
+
|
|
58
|
+
The repository has a manual gate: it creates a fresh app, starts a headless coding agent inside it with a one-line task (for example "add a /customers/count route with a test"),
|
|
59
|
+
and checks that the app's tests and type-check pass afterwards and that the route answers.
|
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# Acryl
|
|
2
|
+
|
|
3
|
+
`Acryl` is the primary object.
|
|
4
|
+
It will be imported first and used until the end.
|
|
5
|
+
|
|
6
|
+
```ts twoslash
|
|
7
|
+
import { Acryl } from '@acryldev/blends'
|
|
8
|
+
|
|
9
|
+
const app = new Acryl()
|
|
10
|
+
//...
|
|
11
|
+
|
|
12
|
+
export default app // a Bun server, or a value a Cordis plugin mounts; see Node.js for the Node entry
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Methods
|
|
16
|
+
|
|
17
|
+
An instance of `Acryl` has the following methods.
|
|
18
|
+
|
|
19
|
+
- app.**HTTP_METHOD**(\[path,\]handler|middleware...)
|
|
20
|
+
- app.**all**(\[path,\]handler|middleware...)
|
|
21
|
+
- app.**on**(method|method[], path|path[], handler|middleware...)
|
|
22
|
+
- app.**use**(\[path,\]middleware)
|
|
23
|
+
- app.**route**(path, \[app\])
|
|
24
|
+
- app.**basePath**(path)
|
|
25
|
+
- app.**notFound**(handler)
|
|
26
|
+
- app.**onError**(err, handler)
|
|
27
|
+
- app.**mount**(path, anotherApp, \[options\])
|
|
28
|
+
- app.**fire**()
|
|
29
|
+
- app.**fetch**(request, env, event)
|
|
30
|
+
- app.**request**(path, options)
|
|
31
|
+
|
|
32
|
+
The first part of them is used for routing, please refer to the [routing section](routing.md).
|
|
33
|
+
|
|
34
|
+
## Not Found
|
|
35
|
+
|
|
36
|
+
`app.notFound` allows you to customize a Not Found Response.
|
|
37
|
+
|
|
38
|
+
```ts twoslash
|
|
39
|
+
import { Acryl } from '@acryldev/blends'
|
|
40
|
+
const app = new Acryl()
|
|
41
|
+
// ---cut---
|
|
42
|
+
app.notFound((c) => {
|
|
43
|
+
return c.text('Custom 404 Message', 404)
|
|
44
|
+
})
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
> **Warning.** The `notFound` method is only called from the top-level app. For more information, see this issue.
|
|
48
|
+
|
|
49
|
+
## Error Handling
|
|
50
|
+
|
|
51
|
+
`app.onError` allows you to handle uncaught errors and return a custom Response.
|
|
52
|
+
|
|
53
|
+
```ts twoslash
|
|
54
|
+
import { Acryl } from '@acryldev/blends'
|
|
55
|
+
const app = new Acryl()
|
|
56
|
+
// ---cut---
|
|
57
|
+
app.onError((err, c) => {
|
|
58
|
+
console.error(`${err}`)
|
|
59
|
+
return c.text('Custom Error Message', 500)
|
|
60
|
+
})
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
> **Note.** If both a parent app and its routes have `onError` handlers, the route-level handlers get priority.
|
|
64
|
+
|
|
65
|
+
## fire()
|
|
66
|
+
|
|
67
|
+
> **Warning.** **`app.fire()` is deprecated**, and the Service Worker adapter is not part of the package in 1.0. It adds a global `fetch` event listener, which only a Service Worker-style host reads; use `app.fetch` in an entry point of your own instead.
|
|
68
|
+
|
|
69
|
+
## fetch()
|
|
70
|
+
|
|
71
|
+
`app.fetch` will be the entry point of your application.
|
|
72
|
+
|
|
73
|
+
As the `fetch` method of an object a host calls:
|
|
74
|
+
|
|
75
|
+
```ts twoslash
|
|
76
|
+
import { Acryl } from '@acryldev/blends'
|
|
77
|
+
const app = new Acryl()
|
|
78
|
+
type Env = any
|
|
79
|
+
type ExecutionContext = any
|
|
80
|
+
// ---cut---
|
|
81
|
+
export default {
|
|
82
|
+
fetch(request: Request, env: Env, ctx: ExecutionContext) {
|
|
83
|
+
return app.fetch(request, env, ctx)
|
|
84
|
+
},
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
or just do:
|
|
89
|
+
|
|
90
|
+
```ts twoslash
|
|
91
|
+
import { Acryl } from '@acryldev/blends'
|
|
92
|
+
const app = new Acryl()
|
|
93
|
+
// ---cut---
|
|
94
|
+
export default app
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Bun:
|
|
98
|
+
|
|
99
|
+
<!-- prettier-ignore -->
|
|
100
|
+
```ts
|
|
101
|
+
export default {
|
|
102
|
+
port: 3000,
|
|
103
|
+
fetch: app.fetch,
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## request()
|
|
108
|
+
|
|
109
|
+
`request` is a useful method for testing.
|
|
110
|
+
|
|
111
|
+
You can pass a URL or pathname to send a GET request.
|
|
112
|
+
`app` will return a `Response` object.
|
|
113
|
+
|
|
114
|
+
```ts twoslash
|
|
115
|
+
import { Acryl } from '@acryldev/blends'
|
|
116
|
+
const app = new Acryl()
|
|
117
|
+
declare const test: (name: string, fn: () => void) => void
|
|
118
|
+
declare const expect: (value: any) => any
|
|
119
|
+
// ---cut---
|
|
120
|
+
test('GET /hello is ok', async () => {
|
|
121
|
+
const res = await app.request('/hello')
|
|
122
|
+
expect(res.status).toBe(200)
|
|
123
|
+
})
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
You can also pass a `Request` object:
|
|
127
|
+
|
|
128
|
+
```ts twoslash
|
|
129
|
+
import { Acryl } from '@acryldev/blends'
|
|
130
|
+
const app = new Acryl()
|
|
131
|
+
declare const test: (name: string, fn: () => void) => void
|
|
132
|
+
declare const expect: (value: any) => any
|
|
133
|
+
// ---cut---
|
|
134
|
+
test('POST /message is ok', async () => {
|
|
135
|
+
const req = new Request('Hello!', {
|
|
136
|
+
method: 'POST',
|
|
137
|
+
})
|
|
138
|
+
const res = await app.request(req)
|
|
139
|
+
expect(res.status).toBe(201)
|
|
140
|
+
})
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## mount()
|
|
144
|
+
|
|
145
|
+
> **Warning.** **`app.mount()` is deprecated**. Use the [Mount Middleware](../middleware/builtin/mount.md) instead.
|
|
146
|
+
|
|
147
|
+
The `mount()` allows you to mount applications built with other frameworks into your Acryl application.
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
import { Router as IttyRouter } from 'itty-router'
|
|
151
|
+
import { Acryl } from '@acryldev/blends'
|
|
152
|
+
|
|
153
|
+
// Create itty-router application
|
|
154
|
+
const ittyRouter = IttyRouter()
|
|
155
|
+
|
|
156
|
+
// Handle `GET /itty-router/hello`
|
|
157
|
+
ittyRouter.get('/hello', () => new Response('Hello from itty-router'))
|
|
158
|
+
|
|
159
|
+
// Acryl application
|
|
160
|
+
const app = new Acryl()
|
|
161
|
+
|
|
162
|
+
// Mount!
|
|
163
|
+
app.mount('/itty-router', ittyRouter.handle)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
By default, `mount()` passes a new `Request` with the mount path removed from its URL. Provide a `replaceRequest` function to control which `Request` is passed to the mounted application:
|
|
167
|
+
|
|
168
|
+
```ts twoslash
|
|
169
|
+
import { Acryl } from '@acryldev/blends'
|
|
170
|
+
const app = new Acryl()
|
|
171
|
+
const handler = (request: Request) => new Response(request.url)
|
|
172
|
+
// ---cut---
|
|
173
|
+
app.mount('/app', handler, {
|
|
174
|
+
replaceRequest: (originalRequest) => originalRequest,
|
|
175
|
+
})
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
To pass the original `Request` unchanged, set `replaceRequest` to `false` as a shorthand for the function above:
|
|
179
|
+
|
|
180
|
+
```ts twoslash
|
|
181
|
+
import { Acryl } from '@acryldev/blends'
|
|
182
|
+
const app = new Acryl()
|
|
183
|
+
const handler = (request: Request) => new Response(request.url)
|
|
184
|
+
// ---cut---
|
|
185
|
+
app.mount('/app', handler, {
|
|
186
|
+
replaceRequest: false,
|
|
187
|
+
})
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
## strict mode
|
|
191
|
+
|
|
192
|
+
Strict mode defaults to `true` and distinguishes the following routes.
|
|
193
|
+
|
|
194
|
+
- `/hello`
|
|
195
|
+
- `/hello/`
|
|
196
|
+
|
|
197
|
+
`app.get('/hello')` will not match `GET /hello/`.
|
|
198
|
+
|
|
199
|
+
By setting strict mode to `false`, both paths will be treated equally.
|
|
200
|
+
|
|
201
|
+
```ts twoslash
|
|
202
|
+
import { Acryl } from '@acryldev/blends'
|
|
203
|
+
// ---cut---
|
|
204
|
+
const app = new Acryl({ strict: false })
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## router option
|
|
208
|
+
|
|
209
|
+
The `router` option specifies which router to use. The default router is `SmartRouter`. If you want to use `RegExpRouter`, pass it to a new `Acryl` instance:
|
|
210
|
+
|
|
211
|
+
```ts twoslash
|
|
212
|
+
import { Acryl } from '@acryldev/blends'
|
|
213
|
+
// ---cut---
|
|
214
|
+
import { RegExpRouter } from '@acryldev/blends/router/reg-exp-router'
|
|
215
|
+
|
|
216
|
+
const app = new Acryl({ router: new RegExpRouter() })
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
## Generics
|
|
220
|
+
|
|
221
|
+
You can pass Generics to specify the type of the environment the host passes and the variables used in `c.set`/`c.get`.
|
|
222
|
+
|
|
223
|
+
```ts twoslash
|
|
224
|
+
import { Acryl } from '@acryldev/blends'
|
|
225
|
+
type User = any
|
|
226
|
+
declare const user: User
|
|
227
|
+
// ---cut---
|
|
228
|
+
type Bindings = {
|
|
229
|
+
TOKEN: string
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
type Variables = {
|
|
233
|
+
user: User
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
const app = new Acryl<{
|
|
237
|
+
Bindings: Bindings
|
|
238
|
+
Variables: Variables
|
|
239
|
+
}>()
|
|
240
|
+
|
|
241
|
+
app.use('/auth/*', async (c, next) => {
|
|
242
|
+
const token = c.env.TOKEN // token is `string`
|
|
243
|
+
// ...
|
|
244
|
+
c.set('user', user) // user should be `User`
|
|
245
|
+
await next()
|
|
246
|
+
})
|
|
247
|
+
```
|