@acryldev/create-blends 1.7.0 → 1.7.1
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/{docs/framework/LICENSE → LICENSE} +1 -3
- package/package.json +2 -2
- package/docs/framework/README.md +0 -70
- package/docs/framework/agents/index.md +0 -59
- package/docs/framework/api/acryl.md +0 -247
- package/docs/framework/api/context.md +0 -478
- package/docs/framework/api/exception.md +0 -80
- package/docs/framework/api/index.md +0 -12
- package/docs/framework/api/presets.md +0 -62
- package/docs/framework/api/request.md +0 -396
- package/docs/framework/api/routing.md +0 -303
- package/docs/framework/api/summary.md +0 -143
- package/docs/framework/concepts/benchmarks.md +0 -26
- package/docs/framework/concepts/developer-experience.md +0 -5
- package/docs/framework/concepts/middleware.md +0 -21
- package/docs/framework/concepts/motivation.md +0 -14
- package/docs/framework/concepts/routers.md +0 -63
- package/docs/framework/concepts/stacks.md +0 -235
- package/docs/framework/concepts/web-standard.md +0 -27
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +0 -160
- package/docs/framework/cordis/concepts.md +0 -105
- package/docs/framework/cordis/middleware.md +0 -8
- package/docs/framework/cordis/migration-from-0-3.md +0 -111
- package/docs/framework/cordis/migration-from-0-4.md +0 -14
- package/docs/framework/cordis/migration-from-dsh-webserver.md +0 -109
- package/docs/framework/cordis/migration-to-1-0.md +0 -46
- package/docs/framework/cordis/mounting.md +0 -85
- package/docs/framework/cordis/node-server.md +0 -100
- package/docs/framework/cordis/plugin-lifecycle.md +0 -111
- package/docs/framework/cordis/surfaces.md +0 -71
- package/docs/framework/cordis/transport-and-cancellation.md +0 -57
- package/docs/framework/cordis/validation.md +0 -135
- package/docs/framework/getting-started/basic.md +0 -201
- package/docs/framework/getting-started/bun.md +0 -219
- package/docs/framework/getting-started/deploy.md +0 -133
- package/docs/framework/getting-started/desktop.md +0 -80
- package/docs/framework/getting-started/nodejs.md +0 -365
- package/docs/framework/getting-started/other-runtimes.md +0 -30
- package/docs/framework/guides/best-practices.md +0 -231
- package/docs/framework/guides/bring-your-own-tool.md +0 -218
- package/docs/framework/guides/client-modules.md +0 -210
- package/docs/framework/guides/create-acrylblends.md +0 -143
- package/docs/framework/guides/data.md +0 -314
- package/docs/framework/guides/examples.md +0 -3
- package/docs/framework/guides/faq.md +0 -19
- package/docs/framework/guides/forms-and-sessions.md +0 -235
- package/docs/framework/guides/helpers.md +0 -33
- package/docs/framework/guides/jsx-dom.md +0 -301
- package/docs/framework/guides/jsx.md +0 -487
- package/docs/framework/guides/middleware.md +0 -253
- package/docs/framework/guides/production.md +0 -80
- package/docs/framework/guides/rpc.md +0 -878
- package/docs/framework/guides/testing.md +0 -133
- package/docs/framework/guides/validation.md +0 -470
- package/docs/framework/helpers/accepts.md +0 -60
- package/docs/framework/helpers/adapter.md +0 -57
- package/docs/framework/helpers/conninfo.md +0 -77
- package/docs/framework/helpers/cookie.md +0 -232
- package/docs/framework/helpers/css.md +0 -282
- package/docs/framework/helpers/dev.md +0 -64
- package/docs/framework/helpers/factory.md +0 -180
- package/docs/framework/helpers/html.md +0 -123
- package/docs/framework/helpers/jwt.md +0 -184
- package/docs/framework/helpers/proxy.md +0 -115
- package/docs/framework/helpers/route.md +0 -143
- package/docs/framework/helpers/ssg.md +0 -390
- package/docs/framework/helpers/streaming.md +0 -224
- package/docs/framework/helpers/testing.md +0 -118
- package/docs/framework/helpers/websocket.md +0 -208
- package/docs/framework/middleware/builtin/basic-auth.md +0 -165
- package/docs/framework/middleware/builtin/bearer-auth.md +0 -138
- package/docs/framework/middleware/builtin/body-limit.md +0 -71
- package/docs/framework/middleware/builtin/cache.md +0 -99
- package/docs/framework/middleware/builtin/combine.md +0 -94
- package/docs/framework/middleware/builtin/compress.md +0 -59
- package/docs/framework/middleware/builtin/context-storage.md +0 -74
- package/docs/framework/middleware/builtin/cors.md +0 -134
- package/docs/framework/middleware/builtin/csrf.md +0 -105
- package/docs/framework/middleware/builtin/etag.md +0 -54
- package/docs/framework/middleware/builtin/ip-restriction.md +0 -69
- package/docs/framework/middleware/builtin/jsx-renderer.md +0 -283
- package/docs/framework/middleware/builtin/jwk.md +0 -192
- package/docs/framework/middleware/builtin/jwt.md +0 -145
- package/docs/framework/middleware/builtin/language.md +0 -232
- package/docs/framework/middleware/builtin/logger.md +0 -74
- package/docs/framework/middleware/builtin/loopback-only.md +0 -31
- package/docs/framework/middleware/builtin/method-not-allowed.md +0 -48
- package/docs/framework/middleware/builtin/method-override.md +0 -80
- package/docs/framework/middleware/builtin/mount.md +0 -103
- package/docs/framework/middleware/builtin/pretty-json.md +0 -53
- package/docs/framework/middleware/builtin/request-id.md +0 -87
- package/docs/framework/middleware/builtin/secure-headers.md +0 -247
- package/docs/framework/middleware/builtin/timeout.md +0 -98
- package/docs/framework/middleware/builtin/timing.md +0 -100
- package/docs/framework/middleware/builtin/trailing-slash.md +0 -74
- package/docs/framework/middleware/third-party.md +0 -4
- package/docs/framework/workshop/README.md +0 -294
- package/docs/framework/workshop/facilitator.md +0 -101
|
@@ -1,365 +0,0 @@
|
|
|
1
|
-
# Node.js
|
|
2
|
-
|
|
3
|
-
[Node.js](https://nodejs.org/) is an open-source, cross-platform JavaScript runtime environment.
|
|
4
|
-
|
|
5
|
-
On Node.js, Acryl runs through the Node.js adapter, `acrylblends/node-server`.
|
|
6
|
-
|
|
7
|
-
> **Note.** Verified on Node.js 22.19 and newer, which runs TypeScript files directly.
|
|
8
|
-
|
|
9
|
-
## 1. Setup
|
|
10
|
-
|
|
11
|
-
A starter for Node.js is available.
|
|
12
|
-
Start your project with "create-acrylblends" command.
|
|
13
|
-
Select `nodejs` template for this example.
|
|
14
|
-
|
|
15
|
-
**npm**
|
|
16
|
-
|
|
17
|
-
```sh
|
|
18
|
-
npm create @acryldev/blends@latest my-app
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
**yarn**
|
|
22
|
-
|
|
23
|
-
```sh
|
|
24
|
-
yarn create acrylblends my-app
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
**pnpm**
|
|
28
|
-
|
|
29
|
-
```sh
|
|
30
|
-
pnpm create @acryldev/blends my-app
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
**bun**
|
|
34
|
-
|
|
35
|
-
```sh
|
|
36
|
-
bun create acrylblends@latest my-app
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
Move to `my-app` and install the dependencies.
|
|
40
|
-
|
|
41
|
-
**npm**
|
|
42
|
-
|
|
43
|
-
```sh
|
|
44
|
-
cd my-app
|
|
45
|
-
npm i
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
**yarn**
|
|
49
|
-
|
|
50
|
-
```sh
|
|
51
|
-
cd my-app
|
|
52
|
-
yarn
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
**pnpm**
|
|
56
|
-
|
|
57
|
-
```sh
|
|
58
|
-
cd my-app
|
|
59
|
-
pnpm i
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
**bun**
|
|
63
|
-
|
|
64
|
-
```sh
|
|
65
|
-
cd my-app
|
|
66
|
-
bun i
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
## 2. Hello World
|
|
70
|
-
|
|
71
|
-
Edit `src/index.ts`:
|
|
72
|
-
|
|
73
|
-
```ts
|
|
74
|
-
import { serve } from '@acryldev/blends/node-server'
|
|
75
|
-
import { Acryl } from '@acryldev/blends'
|
|
76
|
-
|
|
77
|
-
const app = new Acryl()
|
|
78
|
-
app.get('/', (c) => c.text('Hello Node.js!'))
|
|
79
|
-
|
|
80
|
-
serve(app)
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
`serve()` listens on `127.0.0.1` unless you pass `hostname`, so a development server is reachable from this machine only, not from the rest
|
|
84
|
-
of the network. See [Listen on another interface](#listen-on-another-interface).
|
|
85
|
-
|
|
86
|
-
To shut the server down gracefully, stop taking requests, let the ones in flight finish, and exit after a bounded time, so a connection
|
|
87
|
-
that never ends cannot keep the process alive:
|
|
88
|
-
|
|
89
|
-
```ts
|
|
90
|
-
const server = serve(app)
|
|
91
|
-
|
|
92
|
-
function shutdown(): void {
|
|
93
|
-
server.close(() => process.exit(0))
|
|
94
|
-
// Keep-alive connections with no request in flight would otherwise hold close() open until they time out.
|
|
95
|
-
server.closeIdleConnections()
|
|
96
|
-
setTimeout(() => process.exit(1), 10_000).unref()
|
|
97
|
-
}
|
|
98
|
-
process.once('SIGINT', shutdown)
|
|
99
|
-
process.once('SIGTERM', shutdown)
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
`serve(app)` and `serve({ fetch, ... })` return an `http.Server`, which has `closeIdleConnections()`. With `createServer` from
|
|
103
|
-
`node:https` the result is an `https.Server`, and with `node:http2` an `Http2Server` or `Http2SecureServer`, which has no such method;
|
|
104
|
-
there, `server.close()` waits for the open sessions.
|
|
105
|
-
|
|
106
|
-
> **Note.** On Node.js, `serve()` wraps the `node:http` module and returns the underlying server instance, so closing it is up to you. Bun serves Fetch handlers natively and manages the server itself, which is why its guide doesn't include this step.
|
|
107
|
-
|
|
108
|
-
## 3. Run
|
|
109
|
-
|
|
110
|
-
Run the development server locally. Then, access `http://localhost:3000` in your Web browser.
|
|
111
|
-
|
|
112
|
-
**npm**
|
|
113
|
-
|
|
114
|
-
```sh
|
|
115
|
-
npm run dev
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
**yarn**
|
|
119
|
-
|
|
120
|
-
```sh
|
|
121
|
-
yarn dev
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
**pnpm**
|
|
125
|
-
|
|
126
|
-
```sh
|
|
127
|
-
pnpm dev
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
## Change port number
|
|
131
|
-
|
|
132
|
-
You can specify the port number with the `port` option.
|
|
133
|
-
|
|
134
|
-
```ts
|
|
135
|
-
serve({
|
|
136
|
-
fetch: app.fetch,
|
|
137
|
-
port: 8787,
|
|
138
|
-
})
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
## Listen on another interface
|
|
142
|
-
|
|
143
|
-
`serve()` binds `127.0.0.1` when `hostname` is not given. That is right on a developer machine and behind a reverse proxy on the same
|
|
144
|
-
host. Inside a container, or when other machines should reach the app directly, bind every interface on purpose:
|
|
145
|
-
|
|
146
|
-
```ts
|
|
147
|
-
serve({
|
|
148
|
-
fetch: app.fetch,
|
|
149
|
-
port: 3000,
|
|
150
|
-
hostname: '0.0.0.0', // or '::' for IPv6 and IPv4
|
|
151
|
-
})
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
> **Note.** Many Node servers listen on every interface by default. `serve()` does not, so starting a development server never exposes
|
|
155
|
-
> the app to the local network by accident.
|
|
156
|
-
|
|
157
|
-
## WebSocket
|
|
158
|
-
|
|
159
|
-
WebSocket support is built into `acrylblends/node-server`. Install `ws` and, if you use TypeScript, `@types/ws`. Then create a `WebSocketServer` with `{ noServer: true }` and pass it to `serve()` with the `websocket` option.
|
|
160
|
-
|
|
161
|
-
```ts
|
|
162
|
-
import { serve, upgradeWebSocket } from '@acryldev/blends/node-server'
|
|
163
|
-
import { Acryl } from '@acryldev/blends'
|
|
164
|
-
import { WebSocketServer } from 'ws'
|
|
165
|
-
|
|
166
|
-
const app = new Acryl()
|
|
167
|
-
|
|
168
|
-
app.get(
|
|
169
|
-
'/ws',
|
|
170
|
-
upgradeWebSocket(() => ({
|
|
171
|
-
onMessage(event, ws) {
|
|
172
|
-
ws.send(String(event.data))
|
|
173
|
-
},
|
|
174
|
-
}))
|
|
175
|
-
)
|
|
176
|
-
|
|
177
|
-
const wss = new WebSocketServer({ noServer: true })
|
|
178
|
-
|
|
179
|
-
serve({
|
|
180
|
-
fetch: app.fetch,
|
|
181
|
-
websocket: { server: wss },
|
|
182
|
-
})
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
## Access the raw Node.js APIs
|
|
186
|
-
|
|
187
|
-
You can access the Node.js APIs from `c.env.incoming` and `c.env.outgoing`.
|
|
188
|
-
|
|
189
|
-
```ts
|
|
190
|
-
import { Acryl } from '@acryldev/blends'
|
|
191
|
-
import { serve, type HttpBindings } from '@acryldev/blends/node-server'
|
|
192
|
-
// or `Http2Bindings` if you use HTTP2
|
|
193
|
-
|
|
194
|
-
type Bindings = HttpBindings & {
|
|
195
|
-
/* ... */
|
|
196
|
-
}
|
|
197
|
-
|
|
198
|
-
const app = new Acryl<{ Bindings: Bindings }>()
|
|
199
|
-
|
|
200
|
-
app.get('/', (c) => {
|
|
201
|
-
return c.json({
|
|
202
|
-
remoteAddress: c.env.incoming.socket.remoteAddress,
|
|
203
|
-
})
|
|
204
|
-
})
|
|
205
|
-
|
|
206
|
-
serve(app)
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
## Serve static files
|
|
210
|
-
|
|
211
|
-
You can use `serveStatic` to serve static files from the local file system. For example, suppose the directory structure is as follows:
|
|
212
|
-
|
|
213
|
-
```sh
|
|
214
|
-
./
|
|
215
|
-
├── favicon.ico
|
|
216
|
-
├── index.ts
|
|
217
|
-
└── static
|
|
218
|
-
├── hello.txt
|
|
219
|
-
└── image.png
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
If a request to the path `/static/*` comes in and you want to return a file under `./static`, you can write the following:
|
|
223
|
-
|
|
224
|
-
```ts
|
|
225
|
-
import { serveStatic } from '@acryldev/blends/node-server'
|
|
226
|
-
|
|
227
|
-
app.use('/static/*', serveStatic({ root: './' }))
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
**Warning.**
|
|
231
|
-
|
|
232
|
-
The `root` option resolves paths relative to the current working directory (`process.cwd()`). This means the behavior depends on **where you run your Node.js process from**, not where your source file is located. If you start your server from a different directory, file resolution may fail.
|
|
233
|
-
|
|
234
|
-
For reliable path resolution that always points to the same directory as your source file, use `import.meta.url`:
|
|
235
|
-
|
|
236
|
-
```ts
|
|
237
|
-
import { fileURLToPath } from 'node:url'
|
|
238
|
-
import { serveStatic } from '@acryldev/blends/node-server'
|
|
239
|
-
|
|
240
|
-
app.use(
|
|
241
|
-
'/static/*',
|
|
242
|
-
serveStatic({ root: fileURLToPath(new URL('./', import.meta.url)) })
|
|
243
|
-
)
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
Use the `path` option to serve `favicon.ico` in the directory root:
|
|
247
|
-
|
|
248
|
-
```ts
|
|
249
|
-
app.use('/favicon.ico', serveStatic({ path: './favicon.ico' }))
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
If a request to the path `/hello.txt` or `/image.png` comes in and you want to return a file named `./static/hello.txt` or `./static/image.png`, you can use the following:
|
|
253
|
-
|
|
254
|
-
```ts
|
|
255
|
-
app.use('*', serveStatic({ root: './static' }))
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
### `rewriteRequestPath`
|
|
259
|
-
|
|
260
|
-
If you want to map `http://localhost:3000/static/*` to `./statics`, you can use the `rewriteRequestPath` option:
|
|
261
|
-
|
|
262
|
-
```ts
|
|
263
|
-
app.get(
|
|
264
|
-
'/static/*',
|
|
265
|
-
serveStatic({
|
|
266
|
-
root: './',
|
|
267
|
-
rewriteRequestPath: (path) =>
|
|
268
|
-
path.replace(/^\/static/, '/statics'),
|
|
269
|
-
})
|
|
270
|
-
)
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
## http2
|
|
274
|
-
|
|
275
|
-
You can run acrylblends on a [Node.js http2 Server](https://nodejs.org/api/http2.html).
|
|
276
|
-
|
|
277
|
-
### unencrypted http2
|
|
278
|
-
|
|
279
|
-
```ts
|
|
280
|
-
import { createServer } from 'node:http2'
|
|
281
|
-
|
|
282
|
-
const server = serve({
|
|
283
|
-
fetch: app.fetch,
|
|
284
|
-
createServer,
|
|
285
|
-
})
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
### encrypted http2
|
|
289
|
-
|
|
290
|
-
```ts
|
|
291
|
-
import { createSecureServer } from 'node:http2'
|
|
292
|
-
import { readFileSync } from 'node:fs'
|
|
293
|
-
|
|
294
|
-
const server = serve({
|
|
295
|
-
fetch: app.fetch,
|
|
296
|
-
createServer: createSecureServer,
|
|
297
|
-
serverOptions: {
|
|
298
|
-
key: readFileSync('localhost-privkey.pem'),
|
|
299
|
-
cert: readFileSync('localhost-cert.pem'),
|
|
300
|
-
},
|
|
301
|
-
})
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
## Building & Deployment
|
|
305
|
-
|
|
306
|
-
**npm**
|
|
307
|
-
|
|
308
|
-
```sh
|
|
309
|
-
npm run build
|
|
310
|
-
```
|
|
311
|
-
|
|
312
|
-
**yarn**
|
|
313
|
-
|
|
314
|
-
```sh
|
|
315
|
-
yarn run build
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
**pnpm**
|
|
319
|
-
|
|
320
|
-
```sh
|
|
321
|
-
pnpm run build
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
**bun**
|
|
325
|
-
|
|
326
|
-
```sh
|
|
327
|
-
bun run build
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
### Dockerfile
|
|
331
|
-
|
|
332
|
-
Here is an example of a Node.js Dockerfile. A container's published port reaches the app only when it listens on every interface, so
|
|
333
|
-
the app reads its hostname from the environment, as the templates do (`hostname: process.env.HOST || '127.0.0.1'`), and the image
|
|
334
|
-
sets `HOST=0.0.0.0`.
|
|
335
|
-
|
|
336
|
-
```Dockerfile
|
|
337
|
-
FROM node:22-alpine AS base
|
|
338
|
-
|
|
339
|
-
FROM base AS builder
|
|
340
|
-
|
|
341
|
-
RUN apk add --no-cache gcompat
|
|
342
|
-
WORKDIR /app
|
|
343
|
-
|
|
344
|
-
COPY package*json tsconfig.json src ./
|
|
345
|
-
|
|
346
|
-
RUN npm ci && \
|
|
347
|
-
npm run build && \
|
|
348
|
-
npm prune --production
|
|
349
|
-
|
|
350
|
-
FROM base AS runner
|
|
351
|
-
WORKDIR /app
|
|
352
|
-
|
|
353
|
-
RUN addgroup --system --gid 1001 nodejs
|
|
354
|
-
RUN adduser --system --uid 1001 acrylblends
|
|
355
|
-
|
|
356
|
-
COPY --from=builder --chown=acrylblends:nodejs /app/node_modules /app/node_modules
|
|
357
|
-
COPY --from=builder --chown=acrylblends:nodejs /app/dist /app/dist
|
|
358
|
-
COPY --from=builder --chown=acrylblends:nodejs /app/package.json /app/package.json
|
|
359
|
-
|
|
360
|
-
USER acrylblends
|
|
361
|
-
ENV HOST=0.0.0.0
|
|
362
|
-
EXPOSE 3000
|
|
363
|
-
|
|
364
|
-
CMD ["node", "/app/dist/index.js"]
|
|
365
|
-
```
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
# Other runtimes
|
|
2
|
-
|
|
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
|
-
|
|
5
|
-
## Runtimes with an adapter
|
|
6
|
-
|
|
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). |
|
|
11
|
-
|
|
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/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.
|
|
15
|
-
|
|
16
|
-
## Not yet verified
|
|
17
|
-
|
|
18
|
-
The following runtimes and platforms have no adapter and no getting-started page:
|
|
19
|
-
|
|
20
|
-
- Deno, and Deno Deploy
|
|
21
|
-
- Fastly Compute
|
|
22
|
-
- Next.js
|
|
23
|
-
- Supabase Functions
|
|
24
|
-
- Google Cloud Run
|
|
25
|
-
- Azure Functions
|
|
26
|
-
- Alibaba Cloud Function Compute
|
|
27
|
-
- CloudBase
|
|
28
|
-
- WebAssembly (WASI)
|
|
29
|
-
|
|
30
|
-
A page is added here, with a getting-started guide, when a runtime has an adapter and a gate that runs it.
|
|
@@ -1,231 +0,0 @@
|
|
|
1
|
-
# Best Practices
|
|
2
|
-
|
|
3
|
-
Acryl is very flexible. You can write your app as you like.
|
|
4
|
-
However, there are best practices that are better to follow.
|
|
5
|
-
|
|
6
|
-
## Don't make "Controllers" when possible
|
|
7
|
-
|
|
8
|
-
When possible, you should not create "Ruby on Rails-like Controllers".
|
|
9
|
-
|
|
10
|
-
```ts
|
|
11
|
-
// 🙁
|
|
12
|
-
// A RoR-like Controller
|
|
13
|
-
const booksList = (c: Context) => {
|
|
14
|
-
return c.json('list books')
|
|
15
|
-
}
|
|
16
|
-
|
|
17
|
-
app.get('/books', booksList)
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
The issue is related to types. For example, the path parameter cannot be inferred in the Controller without writing complex generics.
|
|
21
|
-
|
|
22
|
-
```ts
|
|
23
|
-
// 🙁
|
|
24
|
-
// A RoR-like Controller
|
|
25
|
-
const bookPermalink = (c: Context) => {
|
|
26
|
-
const id = c.req.param('id') // Can't infer the path param
|
|
27
|
-
return c.json(`get ${id}`)
|
|
28
|
-
}
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
Therefore, you don't need to create RoR-like controllers and should write handlers directly after path definitions.
|
|
32
|
-
|
|
33
|
-
```ts
|
|
34
|
-
// 😃
|
|
35
|
-
app.get('/books/:id', (c) => {
|
|
36
|
-
const id = c.req.param('id') // Can infer the path param
|
|
37
|
-
return c.json(`get ${id}`)
|
|
38
|
-
})
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## `factory.createHandlers()` in `acrylblends/factory`
|
|
42
|
-
|
|
43
|
-
If you still want to create a RoR-like Controller, use `factory.createHandlers()` in [`acrylblends/factory`](../helpers/factory.md). If you use this, type inference will work correctly.
|
|
44
|
-
|
|
45
|
-
```ts
|
|
46
|
-
import { createFactory } from '@acryldev/blends/factory'
|
|
47
|
-
import { logger } from '@acryldev/blends/logger'
|
|
48
|
-
|
|
49
|
-
declare module '@acryldev/blends' {
|
|
50
|
-
interface ContextVariableMap {
|
|
51
|
-
foo: string
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
// ...
|
|
56
|
-
|
|
57
|
-
// 😃
|
|
58
|
-
const factory = createFactory()
|
|
59
|
-
|
|
60
|
-
const middleware = factory.createMiddleware(async (c, next) => {
|
|
61
|
-
c.set('foo', 'bar')
|
|
62
|
-
await next()
|
|
63
|
-
})
|
|
64
|
-
|
|
65
|
-
const handlers = factory.createHandlers(logger(), middleware, (c) => {
|
|
66
|
-
return c.json(c.var.foo)
|
|
67
|
-
})
|
|
68
|
-
|
|
69
|
-
app.get('/api', ...handlers)
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
## Building a larger application
|
|
73
|
-
|
|
74
|
-
Use `app.route()` to build a larger application without creating "Ruby on Rails-like Controllers".
|
|
75
|
-
|
|
76
|
-
If your application has `/authors` and `/books` endpoints and you wish to separate files from `index.ts`, create `authors.ts` and `books.ts`.
|
|
77
|
-
|
|
78
|
-
```ts
|
|
79
|
-
// authors.ts
|
|
80
|
-
import { Acryl } from '@acryldev/blends'
|
|
81
|
-
|
|
82
|
-
const app = new Acryl()
|
|
83
|
-
|
|
84
|
-
app.get('/', (c) => c.json('list authors'))
|
|
85
|
-
app.post('/', (c) => c.json('create an author', 201))
|
|
86
|
-
app.get('/:id', (c) => c.json(`get ${c.req.param('id')}`))
|
|
87
|
-
|
|
88
|
-
export default app
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
```ts
|
|
92
|
-
// books.ts
|
|
93
|
-
import { Acryl } from '@acryldev/blends'
|
|
94
|
-
|
|
95
|
-
const app = new Acryl()
|
|
96
|
-
|
|
97
|
-
app.get('/', (c) => c.json('list books'))
|
|
98
|
-
app.post('/', (c) => c.json('create a book', 201))
|
|
99
|
-
app.get('/:id', (c) => c.json(`get ${c.req.param('id')}`))
|
|
100
|
-
|
|
101
|
-
export default app
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
Then, import them and mount on the paths `/authors` and `/books` with `app.route()`.
|
|
105
|
-
|
|
106
|
-
```ts
|
|
107
|
-
// index.ts
|
|
108
|
-
import { Acryl } from '@acryldev/blends'
|
|
109
|
-
import authors from './authors'
|
|
110
|
-
import books from './books'
|
|
111
|
-
|
|
112
|
-
const app = new Acryl()
|
|
113
|
-
|
|
114
|
-
// 😃
|
|
115
|
-
app.route('/authors', authors)
|
|
116
|
-
app.route('/books', books)
|
|
117
|
-
|
|
118
|
-
export default app
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
### If you want to use RPC features
|
|
122
|
-
|
|
123
|
-
The code above works well for normal use cases.
|
|
124
|
-
However, if you want to use the `RPC` feature, you can get the correct type by chaining as follows.
|
|
125
|
-
|
|
126
|
-
```ts
|
|
127
|
-
// authors.ts
|
|
128
|
-
import { Acryl } from '@acryldev/blends'
|
|
129
|
-
|
|
130
|
-
const app = new Acryl()
|
|
131
|
-
.get('/', (c) => c.json('list authors'))
|
|
132
|
-
.post('/', (c) => c.json('create an author', 201))
|
|
133
|
-
.get('/:id', (c) => c.json(`get ${c.req.param('id')}`))
|
|
134
|
-
|
|
135
|
-
export default app
|
|
136
|
-
export type AppType = typeof app
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
If you pass the type of the `app` to `hc`, it will get the correct type.
|
|
140
|
-
|
|
141
|
-
```ts
|
|
142
|
-
import type { AppType } from './authors'
|
|
143
|
-
import { hc } from '@acryldev/blends/client'
|
|
144
|
-
|
|
145
|
-
// 😃
|
|
146
|
-
const client = hc<AppType>('http://localhost') // Typed correctly
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
For more detailed information, please see [the RPC page](rpc.md#using-rpc-with-larger-applications).
|
|
150
|
-
|
|
151
|
-
## HEAD Request Best Practices
|
|
152
|
-
|
|
153
|
-
### Understanding Acryl's HEAD Handling
|
|
154
|
-
|
|
155
|
-
Acryl automatically handles HEAD requests by converting them to GET requests and stripping the response body. This behavior is built into the framework's dispatch layer and happens before route matching occurs.
|
|
156
|
-
|
|
157
|
-
### ✅ Do: Use GET Routes for HEAD Requests
|
|
158
|
-
|
|
159
|
-
```ts
|
|
160
|
-
// GOOD: This GET route automatically handles HEAD requests
|
|
161
|
-
app.get('/api/users', async (c) => {
|
|
162
|
-
const users = await getUsers()
|
|
163
|
-
c.header('X-Total-Count', users.length.toString())
|
|
164
|
-
return c.json(users)
|
|
165
|
-
})
|
|
166
|
-
|
|
167
|
-
// HEAD /api/users will return:
|
|
168
|
-
// - Same headers as GET (including X-Total-Count)
|
|
169
|
-
// - Status 200
|
|
170
|
-
// - No body (null)
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
### ✅ Do: Use Middleware for HEAD-Specific Logic
|
|
174
|
-
|
|
175
|
-
```ts
|
|
176
|
-
// GOOD: Use middleware when HEAD needs different behavior
|
|
177
|
-
app.use('/api/resource', async (c, next) => {
|
|
178
|
-
await next()
|
|
179
|
-
|
|
180
|
-
// Add HEAD-specific headers after the handler
|
|
181
|
-
if (c.req.method === 'HEAD') {
|
|
182
|
-
c.header('X-HEAD-Processed', 'true')
|
|
183
|
-
// Don't compute expensive body content for HEAD
|
|
184
|
-
c.res = new Response(null, c.res)
|
|
185
|
-
}
|
|
186
|
-
})
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
### ❌ Don't: Try to Create Dedicated HEAD Handlers
|
|
190
|
-
|
|
191
|
-
```ts
|
|
192
|
-
// BAD: This won't work as expected
|
|
193
|
-
app.head('/api/users', (c) => {
|
|
194
|
-
// This handler will NEVER be called
|
|
195
|
-
c.header('X-Custom', 'value')
|
|
196
|
-
return c.text('ignored')
|
|
197
|
-
})
|
|
198
|
-
|
|
199
|
-
// BAD: Using on() also won't work
|
|
200
|
-
app.on('HEAD', '/api/users', (c) => {
|
|
201
|
-
// Still converted to GET before route matching
|
|
202
|
-
})
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
### Performance Considerations
|
|
206
|
-
|
|
207
|
-
- **Avoid expensive operations in GET handlers if you expect many HEAD requests**: Use middleware to detect HEAD and skip body generation
|
|
208
|
-
- **Cache headers work identically**: HEAD responses respect the same caching rules as GET
|
|
209
|
-
- **Middleware compatibility**: Most middleware works with HEAD, but body-processing middleware (like compression) automatically skips HEAD requests
|
|
210
|
-
|
|
211
|
-
### Testing HEAD Requests
|
|
212
|
-
|
|
213
|
-
```ts
|
|
214
|
-
// Always test both GET and HEAD responses
|
|
215
|
-
it('handles HEAD requests correctly', async () => {
|
|
216
|
-
const getRes = await app.request('/api/users')
|
|
217
|
-
const headRes = await app.request('/api/users', { method: 'HEAD' })
|
|
218
|
-
|
|
219
|
-
expect(headRes.status).toBe(getRes.status)
|
|
220
|
-
expect(headRes.headers.get('X-Total-Count')).toBe(
|
|
221
|
-
getRes.headers.get('X-Total-Count')
|
|
222
|
-
)
|
|
223
|
-
expect(headRes.body).toBe(null)
|
|
224
|
-
})
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
### Notes
|
|
228
|
-
|
|
229
|
-
- The automatic HEAD conversion ensures consistent headers between GET and HEAD responses
|
|
230
|
-
- This behavior is consistent across all Acryl runtimes (Node.js, Bun)
|
|
231
|
-
- If you need completely different logic for HEAD vs GET, consider using different endpoints rather than trying to override the framework's HEAD handling
|