@acryldev/create-blends 0.0.0-stage → 1.7.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 (103) hide show
  1. package/README.md +104 -2
  2. package/bin/create-acrylblends.js +12 -0
  3. package/dist/index.d.ts +94 -0
  4. package/dist/index.js +1069 -0
  5. package/dist/index.js.map +1 -0
  6. package/docs/framework/LICENSE +23 -0
  7. package/docs/framework/README.md +70 -0
  8. package/docs/framework/agents/index.md +59 -0
  9. package/docs/framework/api/acryl.md +247 -0
  10. package/docs/framework/api/context.md +478 -0
  11. package/docs/framework/api/exception.md +80 -0
  12. package/docs/framework/api/index.md +12 -0
  13. package/docs/framework/api/presets.md +62 -0
  14. package/docs/framework/api/request.md +396 -0
  15. package/docs/framework/api/routing.md +303 -0
  16. package/docs/framework/api/summary.md +143 -0
  17. package/docs/framework/concepts/benchmarks.md +26 -0
  18. package/docs/framework/concepts/developer-experience.md +5 -0
  19. package/docs/framework/concepts/middleware.md +21 -0
  20. package/docs/framework/concepts/motivation.md +14 -0
  21. package/docs/framework/concepts/routers.md +63 -0
  22. package/docs/framework/concepts/stacks.md +235 -0
  23. package/docs/framework/concepts/web-standard.md +27 -0
  24. package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
  25. package/docs/framework/cordis/concepts.md +105 -0
  26. package/docs/framework/cordis/middleware.md +8 -0
  27. package/docs/framework/cordis/migration-from-0-3.md +111 -0
  28. package/docs/framework/cordis/migration-from-0-4.md +14 -0
  29. package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
  30. package/docs/framework/cordis/migration-to-1-0.md +46 -0
  31. package/docs/framework/cordis/mounting.md +85 -0
  32. package/docs/framework/cordis/node-server.md +100 -0
  33. package/docs/framework/cordis/plugin-lifecycle.md +111 -0
  34. package/docs/framework/cordis/surfaces.md +71 -0
  35. package/docs/framework/cordis/transport-and-cancellation.md +57 -0
  36. package/docs/framework/cordis/validation.md +135 -0
  37. package/docs/framework/getting-started/basic.md +201 -0
  38. package/docs/framework/getting-started/bun.md +219 -0
  39. package/docs/framework/getting-started/deploy.md +133 -0
  40. package/docs/framework/getting-started/desktop.md +80 -0
  41. package/docs/framework/getting-started/nodejs.md +365 -0
  42. package/docs/framework/getting-started/other-runtimes.md +30 -0
  43. package/docs/framework/guides/best-practices.md +231 -0
  44. package/docs/framework/guides/bring-your-own-tool.md +218 -0
  45. package/docs/framework/guides/client-modules.md +210 -0
  46. package/docs/framework/guides/create-acrylblends.md +143 -0
  47. package/docs/framework/guides/data.md +314 -0
  48. package/docs/framework/guides/examples.md +3 -0
  49. package/docs/framework/guides/faq.md +19 -0
  50. package/docs/framework/guides/forms-and-sessions.md +235 -0
  51. package/docs/framework/guides/helpers.md +33 -0
  52. package/docs/framework/guides/jsx-dom.md +301 -0
  53. package/docs/framework/guides/jsx.md +487 -0
  54. package/docs/framework/guides/middleware.md +253 -0
  55. package/docs/framework/guides/production.md +80 -0
  56. package/docs/framework/guides/rpc.md +878 -0
  57. package/docs/framework/guides/testing.md +133 -0
  58. package/docs/framework/guides/validation.md +470 -0
  59. package/docs/framework/helpers/accepts.md +60 -0
  60. package/docs/framework/helpers/adapter.md +57 -0
  61. package/docs/framework/helpers/conninfo.md +77 -0
  62. package/docs/framework/helpers/cookie.md +232 -0
  63. package/docs/framework/helpers/css.md +282 -0
  64. package/docs/framework/helpers/dev.md +64 -0
  65. package/docs/framework/helpers/factory.md +180 -0
  66. package/docs/framework/helpers/html.md +123 -0
  67. package/docs/framework/helpers/jwt.md +184 -0
  68. package/docs/framework/helpers/proxy.md +115 -0
  69. package/docs/framework/helpers/route.md +143 -0
  70. package/docs/framework/helpers/ssg.md +390 -0
  71. package/docs/framework/helpers/streaming.md +224 -0
  72. package/docs/framework/helpers/testing.md +118 -0
  73. package/docs/framework/helpers/websocket.md +208 -0
  74. package/docs/framework/middleware/builtin/basic-auth.md +165 -0
  75. package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
  76. package/docs/framework/middleware/builtin/body-limit.md +71 -0
  77. package/docs/framework/middleware/builtin/cache.md +99 -0
  78. package/docs/framework/middleware/builtin/combine.md +94 -0
  79. package/docs/framework/middleware/builtin/compress.md +59 -0
  80. package/docs/framework/middleware/builtin/context-storage.md +74 -0
  81. package/docs/framework/middleware/builtin/cors.md +134 -0
  82. package/docs/framework/middleware/builtin/csrf.md +105 -0
  83. package/docs/framework/middleware/builtin/etag.md +54 -0
  84. package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
  85. package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
  86. package/docs/framework/middleware/builtin/jwk.md +192 -0
  87. package/docs/framework/middleware/builtin/jwt.md +145 -0
  88. package/docs/framework/middleware/builtin/language.md +232 -0
  89. package/docs/framework/middleware/builtin/logger.md +74 -0
  90. package/docs/framework/middleware/builtin/loopback-only.md +31 -0
  91. package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
  92. package/docs/framework/middleware/builtin/method-override.md +80 -0
  93. package/docs/framework/middleware/builtin/mount.md +103 -0
  94. package/docs/framework/middleware/builtin/pretty-json.md +53 -0
  95. package/docs/framework/middleware/builtin/request-id.md +87 -0
  96. package/docs/framework/middleware/builtin/secure-headers.md +247 -0
  97. package/docs/framework/middleware/builtin/timeout.md +98 -0
  98. package/docs/framework/middleware/builtin/timing.md +100 -0
  99. package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
  100. package/docs/framework/middleware/third-party.md +4 -0
  101. package/docs/framework/workshop/README.md +294 -0
  102. package/docs/framework/workshop/facilitator.md +101 -0
  103. package/package.json +54 -3
@@ -0,0 +1,365 @@
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
+ ```
@@ -0,0 +1,30 @@
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.
@@ -0,0 +1,231 @@
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