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
@@ -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
- The Cache middleware currently supports Cloudflare Workers projects using custom domains and Deno projects using [Deno 1.26+](https://github.com/denoland/deno/releases/tag/v1.26.0). Also available with Deno Deploy.
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. _Required to be true for the Deno environment_. The default is `false`.
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.** On Cloudflare Workers and Deno Deploy, the response body will be compressed automatically, so there is no need to use this middleware.
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`. The runtime should support it.
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
- On Cloudflare Workers, you can access the bindings outside the handler.
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
- type Env = {
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
- const setKV = (value: string) => {
64
- return getContext<Env>().env.KV.put('key', value)
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
- There are many use cases of Cloudflare Workers as Web APIs and calling them from external front-end application.
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/bun`, `acrylblends/aws-lambda`, `acrylblends/node-server` and the others).
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 Deno's `precompile` JSX option. Use the `react-jsx`:
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/>. Note that Cloudflare Workers do not have a `process.env` object, so will default to plaintext log output.
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
 
@@ -3,7 +3,7 @@
3
3
  The guard for a local app's own routes, such as a control API a desktop window calls:
4
4
 
5
5
  ```ts
6
- import { loopbackOnly } from 'acryl-router/middleware'
6
+ import { loopbackOnly } from 'acrylblends/loopback-only'
7
7
 
8
8
  app.use('/control/*', loopbackOnly())
9
9
  ```
@@ -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 same arguments as a Cloudflare Workers `fetch` handler. Use `optionHandler` to pass different arguments.
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
- ## Platform specific Request IDs
76
-
77
- Some platform (such as AWS Lambda) already generate their own Request IDs per request.
78
- Without any additional configuration, this middleware is unaware of these specific Request IDs
79
- and generates a new Request ID. This can lead to confusion when looking at your application logs.
80
-
81
- To unify these IDs, use the `generator` function to capture the platform specific Request ID and to use it in this middleware.
82
-
83
- ### Platform specific links
84
-
85
- - AWS Lambda
86
- - [AWS documentation: Context object](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-context.html)
87
- - Acryl: Access AWS Lambda Object
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.** On Cloudflare Workers, the timer metrics may not be accurate,
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.4.1",
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.11.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).