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
|
@@ -2,11 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
The Cache middleware uses the Web Standards' [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
Cloudflare Workers respects the `Cache-Control` header and return cached responses. For details, refer to [Cache on Cloudflare Docs](https://developers.cloudflare.com/workers/runtime-apis/cache/). Deno does not respect headers, so if you need to update the cache, you will need to implement your own mechanism.
|
|
8
|
-
|
|
9
|
-
See [Usage](#usage) below for instructions on each platform.
|
|
5
|
+
It needs a Cache API on the host: the middleware reads `globalThis.caches`. Node.js, the verified runtime, does not provide one, so on Node the middleware is not enabled and says so in one line; a host that embeds an app in a runtime with a Cache API (or provides `globalThis.caches` itself) gets it. `Cache-Control` handling and the QUERY-request cache below are implemented by the middleware, not by the platform.
|
|
10
6
|
|
|
11
7
|
## Import
|
|
12
8
|
|
|
@@ -17,28 +13,12 @@ import { cache } from 'acrylblends/cache'
|
|
|
17
13
|
|
|
18
14
|
## Usage
|
|
19
15
|
|
|
20
|
-
**Cloudflare Workers**
|
|
21
|
-
|
|
22
|
-
```ts
|
|
23
|
-
app.get(
|
|
24
|
-
'*',
|
|
25
|
-
cache({
|
|
26
|
-
cacheName: 'my-app',
|
|
27
|
-
cacheControl: 'max-age=3600',
|
|
28
|
-
})
|
|
29
|
-
)
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
**Deno**
|
|
33
|
-
|
|
34
16
|
```ts
|
|
35
|
-
// Must use `wait: true` for the Deno runtime
|
|
36
17
|
app.get(
|
|
37
18
|
'*',
|
|
38
19
|
cache({
|
|
39
20
|
cacheName: 'my-app',
|
|
40
21
|
cacheControl: 'max-age=3600',
|
|
41
|
-
wait: true,
|
|
42
22
|
})
|
|
43
23
|
)
|
|
44
24
|
```
|
|
@@ -59,7 +39,7 @@ The name of the cache. Can be used to store multiple caches with different ident
|
|
|
59
39
|
|
|
60
40
|
### *(optional)* wait: `boolean`
|
|
61
41
|
|
|
62
|
-
A boolean indicating if Acryl should wait for the Promise of the `cache.put` function to resolve before continuing with the request.
|
|
42
|
+
A boolean indicating if Acryl should wait for the Promise of the `cache.put` function to resolve before continuing with the request. The default is `false`. A runtime whose Cache API only completes a write after the response has finished needs `true`, or the write is dropped.
|
|
63
43
|
|
|
64
44
|
### *(optional)* cacheControl: `string`
|
|
65
45
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
This middleware compresses the response body, according to `Accept-Encoding` request header.
|
|
4
4
|
|
|
5
|
-
> **Note.**
|
|
5
|
+
> **Note.** Node.js and Bun do not compress a response on their own, so this middleware is what compresses it. A host that already compresses at its edge does not need it.
|
|
6
6
|
|
|
7
7
|
## Import
|
|
8
8
|
|
|
@@ -2,9 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
The Context Storage Middleware stores the Acryl `Context` in the `AsyncLocalStorage`, to make it globally accessible.
|
|
4
4
|
|
|
5
|
-
> **Note.** This middleware uses `AsyncLocalStorage`.
|
|
6
|
-
>
|
|
7
|
-
> **Cloudflare Workers**: To enable `AsyncLocalStorage`, add the [`nodejs_compat` or `nodejs_als` flag](https://developers.cloudflare.com/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) to your `wrangler.toml` file.
|
|
5
|
+
> **Note.** This middleware uses `AsyncLocalStorage`. Node.js, the verified runtime, provides it; a host that embeds an app in a runtime without it cannot use this middleware.
|
|
8
6
|
|
|
9
7
|
## Import
|
|
10
8
|
|
|
@@ -47,22 +45,20 @@ app.get('/', (c) => {
|
|
|
47
45
|
})
|
|
48
46
|
```
|
|
49
47
|
|
|
50
|
-
|
|
48
|
+
Anything a handler puts on the context can be read further down the call stack, without passing `c` through every function:
|
|
51
49
|
|
|
52
50
|
```ts
|
|
53
|
-
|
|
54
|
-
Bindings: {
|
|
55
|
-
KV: KVNamespace
|
|
56
|
-
}
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
const app = new Acryl<Env>()
|
|
51
|
+
const app = new Acryl()
|
|
60
52
|
|
|
61
53
|
app.use(contextStorage())
|
|
54
|
+
app.use(async (c, next) => {
|
|
55
|
+
c.set('user', 'ada')
|
|
56
|
+
await next()
|
|
57
|
+
})
|
|
62
58
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
59
|
+
app.get('/', (c) => c.text(`Hello ${getUser()}`))
|
|
60
|
+
|
|
61
|
+
const getUser = () => getContext().get('user')
|
|
66
62
|
```
|
|
67
63
|
|
|
68
64
|
## tryGetContext
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
# CORS Middleware
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
For them we have to implement CORS, let's do this with middleware as well.
|
|
3
|
+
A web API is often called from a page served by another origin. For that we have to implement CORS, and this middleware does it.
|
|
5
4
|
|
|
6
5
|
## Import
|
|
7
6
|
|
|
@@ -31,7 +31,7 @@ app.use(
|
|
|
31
31
|
app.get('/', (c) => c.text('Acryl!'))
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. Every adapter has one (`acrylblends/
|
|
34
|
+
Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. Every adapter has one (`acrylblends/node-server` and `acrylblends/bun`).
|
|
35
35
|
|
|
36
36
|
## Rules
|
|
37
37
|
|
|
@@ -224,7 +224,7 @@ app.get('/page/info', (c) => {
|
|
|
224
224
|
|
|
225
225
|
**Warning.**
|
|
226
226
|
|
|
227
|
-
You can't use `useRequestContext()` with the
|
|
227
|
+
You can't use `useRequestContext()` with a JSX option that precompiles the templates ahead of the build. Use `react-jsx`:
|
|
228
228
|
|
|
229
229
|
```json
|
|
230
230
|
"compilerOptions": {
|
|
@@ -32,7 +32,7 @@ By using the Logger Middleware, you can easily monitor the flow of requests and
|
|
|
32
32
|
You can also extend the middleware further by providing your own `PrintFunc` function for tailored logging behavior.
|
|
33
33
|
|
|
34
34
|
> **Tip.**
|
|
35
|
-
> To disable _status code coloring_, you can set a `NO_COLOR` environment variable. This is a common way to disable ANSI color escape codes in logging libraries, and is described at <https://no-color.org/>.
|
|
35
|
+
> To disable _status code coloring_, you can set a `NO_COLOR` environment variable. This is a common way to disable ANSI color escape codes in logging libraries, and is described at <https://no-color.org/>.
|
|
36
36
|
|
|
37
37
|
## PrintFunc
|
|
38
38
|
|
|
@@ -29,7 +29,7 @@ app.all('/itty-router/*', mount(ittyRouter.handle))
|
|
|
29
29
|
|
|
30
30
|
By default, the mounted application receives a new `Request` with the matched path prefix removed from its URL. A request to `/itty-router/hello` reaches itty-router as `/hello`.
|
|
31
31
|
|
|
32
|
-
The mounted application is called as `handler(request, c.env, c.executionCtx)`, the
|
|
32
|
+
The mounted application is called as `handler(request, c.env, c.executionCtx)`, the three arguments a `fetch`-style handler takes. Use `optionHandler` to pass different arguments.
|
|
33
33
|
|
|
34
34
|
## Options
|
|
35
35
|
|
|
@@ -72,23 +72,16 @@ The header name used for the request ID. The default is `X-Request-Id`.
|
|
|
72
72
|
|
|
73
73
|
The request ID generation function. By default, it uses `crypto.randomUUID()`.
|
|
74
74
|
|
|
75
|
-
##
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
Without
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
- Cloudflare
|
|
89
|
-
- [Cloudflare Ray ID
|
|
90
|
-
](https://developers.cloudflare.com/fundamentals/reference/cloudflare-ray-id/)
|
|
91
|
-
- Deno
|
|
92
|
-
- [Request ID on the Deno Blog](https://deno.com/blog/zero-config-debugging-deno-opentelemetry#:~:text=s%20automatically%20have-,unique%20request%20IDs,-associated%20with%20them)
|
|
93
|
-
- Fastly
|
|
94
|
-
- [Fastly documentation: req.xid](https://www.fastly.com/documentation/reference/vcl/variables/client-request/req-xid/)
|
|
75
|
+
## An ID that came from earlier in the chain
|
|
76
|
+
|
|
77
|
+
A proxy, a load balancer or the host that starts the app may already put a request id on the request.
|
|
78
|
+
Without configuration this middleware is unaware of it and generates a new one, which makes the two logs hard to line up.
|
|
79
|
+
Use the `generator` function to read the incoming one and fall back to a fresh id:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
app.use(
|
|
83
|
+
requestId({
|
|
84
|
+
generator: (c) => c.req.header('X-Request-Id') ?? crypto.randomUUID(),
|
|
85
|
+
})
|
|
86
|
+
)
|
|
87
|
+
```
|
|
@@ -3,8 +3,7 @@
|
|
|
3
3
|
The [Server-Timing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing) Middleware provides
|
|
4
4
|
performance metrics in the response headers.
|
|
5
5
|
|
|
6
|
-
> **Note.**
|
|
7
|
-
> since [timers only show the time of last I/O](https://developers.cloudflare.com/workers/learning/security-model/#step-1-disallow-timers-and-multi-threading).
|
|
6
|
+
> **Note.** The metrics come from timers around the handler, so they measure wall-clock time on the host the app runs on.
|
|
8
7
|
|
|
9
8
|
## Import
|
|
10
9
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-acrylblends",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"description": "Create an Acryl app: npm create acrylblends@latest",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"scaffold"
|
|
37
37
|
],
|
|
38
38
|
"dependencies": {
|
|
39
|
-
"acrylblends": "^0.
|
|
39
|
+
"acrylblends": "^1.0.0",
|
|
40
40
|
"@webboxes/app-persistence": "0.1.1"
|
|
41
41
|
},
|
|
42
42
|
"publishConfig": {
|
|
@@ -1,115 +0,0 @@
|
|
|
1
|
-
# AWS Lambda
|
|
2
|
-
|
|
3
|
-
An Acryl app runs on AWS Lambda behind API Gateway (REST API and HTTP API), an Application Load Balancer, a Lambda Function URL or VPC Lattice. `handle(app)` from `acrylblends/aws-lambda` turns the app into the Lambda handler: it builds a `Request` from the event, calls `app.fetch`, and returns the result in the shape the event source expects.
|
|
4
|
-
|
|
5
|
-
> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with API Gateway v1 and v2 and ALB events. It has not been deployed to an AWS account by the ACRYL team: try your first deploy with a test stage.
|
|
6
|
-
|
|
7
|
-
## Install and write the handler
|
|
8
|
-
|
|
9
|
-
```sh
|
|
10
|
-
npm install acrylblends
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
```ts
|
|
14
|
-
import { Acryl } from 'acrylblends'
|
|
15
|
-
import { handle } from 'acrylblends/aws-lambda'
|
|
16
|
-
|
|
17
|
-
const app = new Acryl()
|
|
18
|
-
|
|
19
|
-
app.get('/', (c) => c.text('Hello from Lambda'))
|
|
20
|
-
app.get('/json', (c) => c.json({ message: 'Hello JSON' }))
|
|
21
|
-
|
|
22
|
-
export const handler = handle(app)
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
Bundle the file to one JavaScript file for the `nodejs22.x` (or newer) runtime with your tool of choice (esbuild is common), upload it, and set the handler to `index.handler` (the file name, a dot, the export).
|
|
26
|
-
|
|
27
|
-
## The event and the Lambda context
|
|
28
|
-
|
|
29
|
-
Both are in the bindings of the request:
|
|
30
|
-
|
|
31
|
-
```ts
|
|
32
|
-
import { Acryl } from 'acrylblends'
|
|
33
|
-
import type { LambdaContext, LambdaEvent } from 'acrylblends/aws-lambda'
|
|
34
|
-
|
|
35
|
-
type Bindings = {
|
|
36
|
-
event: LambdaEvent
|
|
37
|
-
lambdaContext: LambdaContext
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
const app = new Acryl<{ Bindings: Bindings }>()
|
|
41
|
-
|
|
42
|
-
app.get('/info', (c) => {
|
|
43
|
-
return c.json({
|
|
44
|
-
isBase64Encoded: c.env.event.isBase64Encoded,
|
|
45
|
-
awsRequestId: c.env.lambdaContext.awsRequestId,
|
|
46
|
-
})
|
|
47
|
-
})
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
`c.env.requestContext` holds the request context of the event (API Gateway, ALB or Lattice). The client's address is available through the [ConnInfo helper](../helpers/conninfo.md): `getConnInfo(c).remote.address`.
|
|
51
|
-
|
|
52
|
-
## Binary responses
|
|
53
|
-
|
|
54
|
-
A response is returned base64 encoded when its content type is binary (images, audio, video, PDF, archives and other non-text types) or it has a content encoding such as `gzip`. To decide differently, pass `isContentTypeBinary`:
|
|
55
|
-
|
|
56
|
-
```ts
|
|
57
|
-
import { Acryl } from 'acrylblends'
|
|
58
|
-
import { defaultIsContentTypeBinary, handle } from 'acrylblends/aws-lambda'
|
|
59
|
-
|
|
60
|
-
const app = new Acryl()
|
|
61
|
-
|
|
62
|
-
export const handler = handle(app, {
|
|
63
|
-
isContentTypeBinary: (contentType) =>
|
|
64
|
-
defaultIsContentTypeBinary(contentType) || contentType.startsWith('application/vnd.api+octet'),
|
|
65
|
-
})
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
## Response streaming
|
|
69
|
-
|
|
70
|
-
On a Function URL with `RESPONSE_STREAM` invoke mode, use `streamHandle` instead of `handle`: the body is written to the response stream as the app produces it, so [streaming helpers](../helpers/streaming.md) (SSE, `stream`, `streamText`) reach the client as they are written. It needs the `awslambda` global, which only the Lambda runtime provides.
|
|
71
|
-
|
|
72
|
-
```ts
|
|
73
|
-
import { Acryl } from 'acrylblends'
|
|
74
|
-
import { streamHandle } from 'acrylblends/aws-lambda'
|
|
75
|
-
|
|
76
|
-
const app = new Acryl()
|
|
77
|
-
|
|
78
|
-
export const handler = streamHandle(app)
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
## Try it without AWS
|
|
82
|
-
|
|
83
|
-
A handler is a function from an event to a result, so it can be called locally with a sample event:
|
|
84
|
-
|
|
85
|
-
```ts
|
|
86
|
-
import { Acryl } from 'acrylblends'
|
|
87
|
-
import { handle } from 'acrylblends/aws-lambda'
|
|
88
|
-
|
|
89
|
-
const app = new Acryl().get('/', (c) => c.text('Hello from Lambda'))
|
|
90
|
-
|
|
91
|
-
const result = await handle(app)({
|
|
92
|
-
version: '2.0',
|
|
93
|
-
routeKey: '$default',
|
|
94
|
-
rawPath: '/',
|
|
95
|
-
rawQueryString: '',
|
|
96
|
-
headers: { host: 'example.execute-api.eu-west-1.amazonaws.com' },
|
|
97
|
-
requestContext: {
|
|
98
|
-
accountId: '1',
|
|
99
|
-
apiId: 'example',
|
|
100
|
-
authentication: null,
|
|
101
|
-
authorizer: {},
|
|
102
|
-
domainName: 'example.execute-api.eu-west-1.amazonaws.com',
|
|
103
|
-
domainPrefix: 'example',
|
|
104
|
-
http: { method: 'GET', path: '/', protocol: 'HTTP/1.1', sourceIp: '203.0.113.9', userAgent: 'test' },
|
|
105
|
-
requestId: 'r',
|
|
106
|
-
routeKey: '$default',
|
|
107
|
-
stage: '$default',
|
|
108
|
-
time: '25/Oct/2026:12:00:00 +0000',
|
|
109
|
-
timeEpoch: 0,
|
|
110
|
-
},
|
|
111
|
-
body: null,
|
|
112
|
-
isBase64Encoded: false,
|
|
113
|
-
})
|
|
114
|
-
console.log(result.statusCode, result.body) // 200 Hello from Lambda
|
|
115
|
-
```
|
|
@@ -1,53 +0,0 @@
|
|
|
1
|
-
# Cloudflare Pages
|
|
2
|
-
|
|
3
|
-
Cloudflare Pages Functions run code next to a static site. `handle(app)` from `acrylblends/cloudflare-pages` turns an Acryl app into a Pages Function, and `handleMiddleware` turns a middleware into a Pages middleware.
|
|
4
|
-
|
|
5
|
-
> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a Pages event context. It has not been deployed to Cloudflare by the ACRYL team. Cloudflare recommends Workers with static assets for new projects (see [Cloudflare Workers](cloudflare-workers.md)).
|
|
6
|
-
|
|
7
|
-
## A catch-all function
|
|
8
|
-
|
|
9
|
-
Put the file in `functions/[[route]].ts` so it answers every path that is not a static file:
|
|
10
|
-
|
|
11
|
-
```ts
|
|
12
|
-
import { Acryl } from 'acrylblends'
|
|
13
|
-
import { handle } from 'acrylblends/cloudflare-pages'
|
|
14
|
-
|
|
15
|
-
const app = new Acryl().basePath('/api')
|
|
16
|
-
|
|
17
|
-
app.get('/hello', (c) => c.json({ message: 'Hello from Pages Functions' }))
|
|
18
|
-
|
|
19
|
-
export const onRequest = handle(app)
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
`basePath('/api')` is for a function at `functions/api/[[route]].ts`.
|
|
23
|
-
|
|
24
|
-
## The event context and the bindings
|
|
25
|
-
|
|
26
|
-
The Pages event context (`env`, `params`, `data`, `waitUntil`, `next`) is `c.env.eventContext`; the environment bindings are `c.env` as in Workers:
|
|
27
|
-
|
|
28
|
-
```ts
|
|
29
|
-
import { Acryl } from 'acrylblends'
|
|
30
|
-
import type { EventContext } from 'acrylblends/cloudflare-pages'
|
|
31
|
-
|
|
32
|
-
type Bindings = { MY_KV: unknown; eventContext: EventContext }
|
|
33
|
-
|
|
34
|
-
const app = new Acryl<{ Bindings: Bindings }>()
|
|
35
|
-
|
|
36
|
-
app.get('/params', (c) => c.json(c.env.eventContext.params))
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Middleware
|
|
40
|
-
|
|
41
|
-
```ts
|
|
42
|
-
import { handleMiddleware } from 'acrylblends/cloudflare-pages'
|
|
43
|
-
|
|
44
|
-
// functions/_middleware.ts
|
|
45
|
-
export const onRequest = handleMiddleware(async (c, next) => {
|
|
46
|
-
await next()
|
|
47
|
-
c.res.headers.set('x-checked', 'yes')
|
|
48
|
-
})
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
## Static files
|
|
52
|
-
|
|
53
|
-
In [advanced mode](https://developers.cloudflare.com/pages/platform/functions/advanced-mode/) (a `_worker.js` that answers every request), `serveStatic()` from `acrylblends/cloudflare-pages` answers a request from the Pages `ASSETS` binding and falls through to the app's not-found handler when there is no such file. The client's address is available through the [ConnInfo helper](../helpers/conninfo.md).
|
|
@@ -1,67 +0,0 @@
|
|
|
1
|
-
# Cloudflare Workers
|
|
2
|
-
|
|
3
|
-
A Cloudflare Worker is a module that exports a `fetch` handler, which is what an Acryl app has: `export default app` is a Worker. The adapter `acrylblends/cloudflare-workers` adds the pieces that need Cloudflare: the client's address, WebSockets, and (deprecated) serving static files from Workers KV.
|
|
4
|
-
|
|
5
|
-
> **Status.** The adapter is the upstream adapter ported with its test suite, and a Worker with these routes (`export default app`, bindings from `vars`, `getConnInfo`, `waitUntil`) has been run in `workerd` with `wrangler dev --local`, which needs no Cloudflare account. The ACRYL team has not deployed to Cloudflare itself: run `wrangler dev` first.
|
|
6
|
-
|
|
7
|
-
## A Worker
|
|
8
|
-
|
|
9
|
-
```ts
|
|
10
|
-
import { Acryl } from 'acrylblends'
|
|
11
|
-
|
|
12
|
-
const app = new Acryl()
|
|
13
|
-
|
|
14
|
-
app.get('/', (c) => c.text('Hello Cloudflare Workers!'))
|
|
15
|
-
|
|
16
|
-
export default app
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
With Wrangler: a `wrangler.jsonc` naming the entry file and a compatibility date (`"main": "src/index.ts"`, `"compatibility_date": "2026-01-01"`), then `npx wrangler dev` to run it locally and `npx wrangler deploy` to publish it.
|
|
20
|
-
|
|
21
|
-
## Bindings and the execution context
|
|
22
|
-
|
|
23
|
-
Environment variables, secrets, KV namespaces, D1 databases and R2 buckets arrive as `c.env`; the `ExecutionContext` is `c.executionCtx`:
|
|
24
|
-
|
|
25
|
-
```ts
|
|
26
|
-
import { Acryl } from 'acrylblends'
|
|
27
|
-
|
|
28
|
-
type Bindings = {
|
|
29
|
-
MY_SECRET: string
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
const app = new Acryl<{ Bindings: Bindings }>()
|
|
33
|
-
|
|
34
|
-
app.get('/', (c) => {
|
|
35
|
-
c.executionCtx.waitUntil(Promise.resolve()) // work that may finish after the response
|
|
36
|
-
return c.text(c.env.MY_SECRET ? 'configured' : 'missing')
|
|
37
|
-
})
|
|
38
|
-
|
|
39
|
-
export default app
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
## The client's address
|
|
43
|
-
|
|
44
|
-
```ts
|
|
45
|
-
import { Acryl } from 'acrylblends'
|
|
46
|
-
import { getConnInfo } from 'acrylblends/cloudflare-workers'
|
|
47
|
-
|
|
48
|
-
const app = new Acryl()
|
|
49
|
-
|
|
50
|
-
app.get('/ip', (c) => c.text(getConnInfo(c).remote.address ?? 'unknown'))
|
|
51
|
-
|
|
52
|
-
export default app
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
It reads the `cf-connecting-ip` header that Cloudflare sets. See the [ConnInfo helper](../helpers/conninfo.md).
|
|
56
|
-
|
|
57
|
-
## WebSockets
|
|
58
|
-
|
|
59
|
-
`upgradeWebSocket` from `acrylblends/cloudflare-workers` accepts the upgrade with Cloudflare's `WebSocketPair`. Cloudflare does not give an `onOpen` event. See the [WebSocket helper](../helpers/websocket.md).
|
|
60
|
-
|
|
61
|
-
## Static files
|
|
62
|
-
|
|
63
|
-
Prefer Cloudflare's static assets (the `assets` setting of Wrangler), which serve files before your code runs. `serveStatic` from `acrylblends/cloudflare-workers`, which reads files from Workers KV (`__STATIC_CONTENT`), is deprecated by Cloudflare's move to static assets and is kept for existing Workers Sites projects. Cloudflare Pages is the other option: see [Cloudflare Pages](cloudflare-pages.md).
|
|
64
|
-
|
|
65
|
-
## Service Worker syntax
|
|
66
|
-
|
|
67
|
-
A Worker written in the old non-module syntax (`addEventListener('fetch', ...)`) uses `fire` from `acrylblends/service-worker`: see [Service Worker](service-worker.md).
|
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
# Lambda@Edge
|
|
2
|
-
|
|
3
|
-
An Acryl app can answer CloudFront requests from Lambda@Edge. `handle(app)` from `acrylblends/lambda-edge` turns the app into the edge function: it builds a `Request` from the CloudFront event, calls `app.fetch`, and returns a CloudFront response. A viewer-request or origin-request function that answers by itself (a redirect, an HTML page, a JSON answer) is the typical use.
|
|
4
|
-
|
|
5
|
-
> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a CloudFront viewer-request event. It has not been deployed to AWS by the ACRYL team.
|
|
6
|
-
|
|
7
|
-
```ts
|
|
8
|
-
import { Acryl } from 'acrylblends'
|
|
9
|
-
import { handle } from 'acrylblends/lambda-edge'
|
|
10
|
-
|
|
11
|
-
const app = new Acryl()
|
|
12
|
-
|
|
13
|
-
app.get('/', (c) => c.text('Hello from the edge'))
|
|
14
|
-
|
|
15
|
-
export const handler = handle(app)
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
Lambda@Edge has its own limits: the function must be created in `us-east-1`, has no environment variables, and its size and time limits are lower than Lambda's; check them in the AWS documentation when you choose between this adapter and [AWS Lambda](aws-lambda.md).
|
|
19
|
-
|
|
20
|
-
## The CloudFront event
|
|
21
|
-
|
|
22
|
-
The CloudFront request, response and config are in the bindings:
|
|
23
|
-
|
|
24
|
-
```ts
|
|
25
|
-
import { Acryl } from 'acrylblends'
|
|
26
|
-
import type { Callback, CloudFrontEdgeEvent } from 'acrylblends/lambda-edge'
|
|
27
|
-
|
|
28
|
-
type Bindings = {
|
|
29
|
-
callback: Callback
|
|
30
|
-
event: CloudFrontEdgeEvent
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
const app = new Acryl<{ Bindings: Bindings }>()
|
|
34
|
-
|
|
35
|
-
app.get('/country', (c) => {
|
|
36
|
-
const request = c.env.event.Records[0].cf.request
|
|
37
|
-
return c.json({ uri: request.uri, clientIp: request.clientIp })
|
|
38
|
-
})
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
The client's address is available through the [ConnInfo helper](../helpers/conninfo.md).
|
|
@@ -1,25 +0,0 @@
|
|
|
1
|
-
# Netlify
|
|
2
|
-
|
|
3
|
-
Netlify Functions (version 2) and Edge Functions take a `Request` and a context and return a `Response`. `handle(app)` from `acrylblends/netlify` is that function; the Netlify context is available to the app as `c.env.context`.
|
|
4
|
-
|
|
5
|
-
> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a `Request`. It has not been deployed to Netlify by the ACRYL team.
|
|
6
|
-
|
|
7
|
-
## A function
|
|
8
|
-
|
|
9
|
-
`netlify/functions/api.ts`:
|
|
10
|
-
|
|
11
|
-
```ts
|
|
12
|
-
import { Acryl } from 'acrylblends'
|
|
13
|
-
import { handle } from 'acrylblends/netlify'
|
|
14
|
-
import type { Context } from '@netlify/functions'
|
|
15
|
-
|
|
16
|
-
type Bindings = { context: Context }
|
|
17
|
-
|
|
18
|
-
const app = new Acryl<{ Bindings: Bindings }>().basePath('/.netlify/functions/api')
|
|
19
|
-
|
|
20
|
-
app.get('/hello', (c) => c.json({ hello: 'world', site: c.env.context.site.id }))
|
|
21
|
-
|
|
22
|
-
export default handle(app)
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
Run it locally with `netlify dev` and publish with `netlify deploy`. The client's address comes from `getConnInfo` of `acrylblends/netlify` (the Netlify context's `ip`); see the [ConnInfo helper](../helpers/conninfo.md).
|
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
# Service Worker
|
|
2
|
-
|
|
3
|
-
An Acryl app can answer `fetch` events in a Service Worker, and in any environment that uses the Service Worker syntax, such as a Cloudflare Worker written without ES modules. `fire(app)` from `acrylblends/service-worker` registers the app on the `fetch` event, and `handle(app)` returns the listener, if you want to register it yourself.
|
|
4
|
-
|
|
5
|
-
> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a fetch event. It has not been run inside a browser's Service Worker by the ACRYL team.
|
|
6
|
-
|
|
7
|
-
```ts
|
|
8
|
-
import { Acryl } from 'acrylblends'
|
|
9
|
-
import { fire } from 'acrylblends/service-worker'
|
|
10
|
-
|
|
11
|
-
const app = new Acryl()
|
|
12
|
-
|
|
13
|
-
app.get('/', (c) => c.text('Hello from a Service Worker'))
|
|
14
|
-
|
|
15
|
-
fire(app)
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
A request the app does not answer (`404`) can be passed on to the network by giving `fetch` as an option, so a Service Worker can serve some routes and leave the others to the origin:
|
|
19
|
-
|
|
20
|
-
```ts lib=webworker
|
|
21
|
-
import { Acryl } from 'acrylblends'
|
|
22
|
-
import { handle } from 'acrylblends/service-worker'
|
|
23
|
-
|
|
24
|
-
declare const self: ServiceWorkerGlobalScope
|
|
25
|
-
|
|
26
|
-
const app = new Acryl()
|
|
27
|
-
|
|
28
|
-
app.get('/offline', (c) => c.text('Served by the Service Worker'))
|
|
29
|
-
|
|
30
|
-
self.addEventListener('fetch', handle(app, { fetch: globalThis.fetch }))
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
The example is type-checked with the TypeScript `WebWorker` library: declare `self` as a `ServiceWorkerGlobalScope` as above. `app.fire()` (a method of the app) is deprecated in favour of `fire()` from this module.
|
|
@@ -1,28 +0,0 @@
|
|
|
1
|
-
# Vercel
|
|
2
|
-
|
|
3
|
-
Vercel runs a function that takes a `Request` and returns a `Response`, which is what `app.fetch` is. `handle(app)` from `acrylblends/vercel` is that function.
|
|
4
|
-
|
|
5
|
-
> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a `Request`. It has not been deployed to Vercel by the ACRYL team.
|
|
6
|
-
|
|
7
|
-
## A function
|
|
8
|
-
|
|
9
|
-
Create `api/index.ts`:
|
|
10
|
-
|
|
11
|
-
```ts
|
|
12
|
-
import { Acryl } from 'acrylblends'
|
|
13
|
-
import { handle } from 'acrylblends/vercel'
|
|
14
|
-
|
|
15
|
-
const app = new Acryl().basePath('/api')
|
|
16
|
-
|
|
17
|
-
app.get('/', (c) => c.text('Hello from Vercel'))
|
|
18
|
-
app.get('/hello', (c) => c.json({ hello: 'world' }))
|
|
19
|
-
|
|
20
|
-
export const GET = handle(app)
|
|
21
|
-
export const POST = handle(app)
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
Export one handler per HTTP method the app answers. Run it locally with `vercel dev`, and publish with `vercel deploy`.
|
|
25
|
-
|
|
26
|
-
## The client's address
|
|
27
|
-
|
|
28
|
-
The client's address comes from `getConnInfo` of `acrylblends/vercel`, which reads the `x-real-ip` header Vercel sets; see the [ConnInfo helper](../helpers/conninfo.md).
|