@acryldev/create-blends 1.7.1 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/{LICENSE → docs/framework/LICENSE} +3 -1
  2. package/docs/framework/README.md +70 -0
  3. package/docs/framework/agents/index.md +59 -0
  4. package/docs/framework/api/acryl.md +247 -0
  5. package/docs/framework/api/context.md +478 -0
  6. package/docs/framework/api/exception.md +80 -0
  7. package/docs/framework/api/index.md +12 -0
  8. package/docs/framework/api/presets.md +62 -0
  9. package/docs/framework/api/request.md +396 -0
  10. package/docs/framework/api/routing.md +303 -0
  11. package/docs/framework/api/summary.md +143 -0
  12. package/docs/framework/concepts/benchmarks.md +26 -0
  13. package/docs/framework/concepts/developer-experience.md +5 -0
  14. package/docs/framework/concepts/middleware.md +21 -0
  15. package/docs/framework/concepts/motivation.md +14 -0
  16. package/docs/framework/concepts/routers.md +63 -0
  17. package/docs/framework/concepts/stacks.md +235 -0
  18. package/docs/framework/concepts/web-standard.md +27 -0
  19. package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
  20. package/docs/framework/cordis/concepts.md +105 -0
  21. package/docs/framework/cordis/middleware.md +8 -0
  22. package/docs/framework/cordis/migration-from-0-3.md +111 -0
  23. package/docs/framework/cordis/migration-from-0-4.md +14 -0
  24. package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
  25. package/docs/framework/cordis/migration-to-1-0.md +46 -0
  26. package/docs/framework/cordis/mounting.md +85 -0
  27. package/docs/framework/cordis/node-server.md +100 -0
  28. package/docs/framework/cordis/plugin-lifecycle.md +111 -0
  29. package/docs/framework/cordis/surfaces.md +71 -0
  30. package/docs/framework/cordis/transport-and-cancellation.md +57 -0
  31. package/docs/framework/cordis/validation.md +135 -0
  32. package/docs/framework/getting-started/basic.md +201 -0
  33. package/docs/framework/getting-started/bun.md +219 -0
  34. package/docs/framework/getting-started/deploy.md +133 -0
  35. package/docs/framework/getting-started/desktop.md +80 -0
  36. package/docs/framework/getting-started/nodejs.md +365 -0
  37. package/docs/framework/getting-started/other-runtimes.md +30 -0
  38. package/docs/framework/guides/best-practices.md +231 -0
  39. package/docs/framework/guides/bring-your-own-tool.md +218 -0
  40. package/docs/framework/guides/client-modules.md +210 -0
  41. package/docs/framework/guides/create-acrylblends.md +143 -0
  42. package/docs/framework/guides/data.md +314 -0
  43. package/docs/framework/guides/examples.md +3 -0
  44. package/docs/framework/guides/faq.md +19 -0
  45. package/docs/framework/guides/forms-and-sessions.md +235 -0
  46. package/docs/framework/guides/helpers.md +33 -0
  47. package/docs/framework/guides/jsx-dom.md +301 -0
  48. package/docs/framework/guides/jsx.md +487 -0
  49. package/docs/framework/guides/middleware.md +253 -0
  50. package/docs/framework/guides/production.md +80 -0
  51. package/docs/framework/guides/rpc.md +878 -0
  52. package/docs/framework/guides/testing.md +133 -0
  53. package/docs/framework/guides/validation.md +470 -0
  54. package/docs/framework/helpers/accepts.md +60 -0
  55. package/docs/framework/helpers/adapter.md +57 -0
  56. package/docs/framework/helpers/conninfo.md +77 -0
  57. package/docs/framework/helpers/cookie.md +232 -0
  58. package/docs/framework/helpers/css.md +282 -0
  59. package/docs/framework/helpers/dev.md +64 -0
  60. package/docs/framework/helpers/factory.md +180 -0
  61. package/docs/framework/helpers/html.md +123 -0
  62. package/docs/framework/helpers/jwt.md +184 -0
  63. package/docs/framework/helpers/proxy.md +115 -0
  64. package/docs/framework/helpers/route.md +143 -0
  65. package/docs/framework/helpers/ssg.md +390 -0
  66. package/docs/framework/helpers/streaming.md +224 -0
  67. package/docs/framework/helpers/testing.md +118 -0
  68. package/docs/framework/helpers/websocket.md +208 -0
  69. package/docs/framework/middleware/builtin/basic-auth.md +165 -0
  70. package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
  71. package/docs/framework/middleware/builtin/body-limit.md +71 -0
  72. package/docs/framework/middleware/builtin/cache.md +99 -0
  73. package/docs/framework/middleware/builtin/combine.md +94 -0
  74. package/docs/framework/middleware/builtin/compress.md +59 -0
  75. package/docs/framework/middleware/builtin/context-storage.md +74 -0
  76. package/docs/framework/middleware/builtin/cors.md +134 -0
  77. package/docs/framework/middleware/builtin/csrf.md +105 -0
  78. package/docs/framework/middleware/builtin/etag.md +54 -0
  79. package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
  80. package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
  81. package/docs/framework/middleware/builtin/jwk.md +192 -0
  82. package/docs/framework/middleware/builtin/jwt.md +145 -0
  83. package/docs/framework/middleware/builtin/language.md +232 -0
  84. package/docs/framework/middleware/builtin/logger.md +74 -0
  85. package/docs/framework/middleware/builtin/loopback-only.md +31 -0
  86. package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
  87. package/docs/framework/middleware/builtin/method-override.md +80 -0
  88. package/docs/framework/middleware/builtin/mount.md +103 -0
  89. package/docs/framework/middleware/builtin/pretty-json.md +53 -0
  90. package/docs/framework/middleware/builtin/request-id.md +87 -0
  91. package/docs/framework/middleware/builtin/secure-headers.md +247 -0
  92. package/docs/framework/middleware/builtin/timeout.md +98 -0
  93. package/docs/framework/middleware/builtin/timing.md +100 -0
  94. package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
  95. package/docs/framework/middleware/third-party.md +4 -0
  96. package/docs/framework/workshop/README.md +294 -0
  97. package/docs/framework/workshop/facilitator.md +101 -0
  98. package/package.json +2 -2
@@ -0,0 +1,143 @@
1
+ # Route Helper
2
+
3
+ The Route Helper provides enhanced routing information for debugging and middleware development. It allows you to access detailed information about matched routes and the current route being processed.
4
+
5
+ ## Import
6
+
7
+ ```ts
8
+ import { Acryl } from '@acryldev/blends'
9
+ import {
10
+ matchedRoutes,
11
+ routePath,
12
+ baseRoutePath,
13
+ basePath,
14
+ } from '@acryldev/blends/route'
15
+ ```
16
+
17
+ ## Usage
18
+
19
+ ### Basic route information
20
+
21
+ ```ts
22
+ const app = new Acryl()
23
+
24
+ app.get('/posts/:id', (c) => {
25
+ const currentPath = routePath(c) // '/posts/:id'
26
+ const routes = matchedRoutes(c) // Array of matched routes
27
+
28
+ return c.json({
29
+ path: currentPath,
30
+ totalRoutes: routes.length,
31
+ })
32
+ })
33
+ ```
34
+
35
+ ### Working with sub-applications
36
+
37
+ ```ts
38
+ const app = new Acryl()
39
+ const apiApp = new Acryl()
40
+
41
+ apiApp.get('/posts/:id', (c) => {
42
+ return c.json({
43
+ routePath: routePath(c), // '/posts/:id'
44
+ baseRoutePath: baseRoutePath(c), // '/api'
45
+ basePath: basePath(c), // '/api' (with actual params)
46
+ })
47
+ })
48
+
49
+ app.route('/api', apiApp)
50
+ ```
51
+
52
+ ## `matchedRoutes()`
53
+
54
+ Returns an array of all routes that matched the current request, including middleware.
55
+
56
+ ```ts
57
+ app.all('/api/*', (c, next) => {
58
+ console.log('API middleware')
59
+ return next()
60
+ })
61
+
62
+ app.get('/api/users/:id', (c) => {
63
+ const routes = matchedRoutes(c)
64
+ // Returns: [
65
+ // { method: 'ALL', path: '/api/*', handler: [Function] },
66
+ // { method: 'GET', path: '/api/users/:id', handler: [Function] }
67
+ // ]
68
+ return c.json({ routes: routes.length })
69
+ })
70
+ ```
71
+
72
+ ## `routePath()`
73
+
74
+ Returns the route path pattern registered for the current handler.
75
+
76
+ ```ts
77
+ app.get('/posts/:id', (c) => {
78
+ console.log(routePath(c)) // '/posts/:id'
79
+ return c.text('Post details')
80
+ })
81
+ ```
82
+
83
+ ### Using with index parameter
84
+
85
+ You can optionally pass an index parameter to get the route path at a specific position, similar to `Array.prototype.at()`.
86
+
87
+ ```ts
88
+ app.all('/api/*', (c, next) => {
89
+ return next()
90
+ })
91
+
92
+ app.get('/api/users/:id', (c) => {
93
+ console.log(routePath(c, 0)) // '/api/*' (first matched route)
94
+ console.log(routePath(c, -1)) // '/api/users/:id' (last matched route)
95
+ return c.text('User details')
96
+ })
97
+ ```
98
+
99
+ ## `baseRoutePath()`
100
+
101
+ Returns the base path pattern of the current route as specified in routing.
102
+
103
+ ```ts
104
+ const subApp = new Acryl()
105
+ subApp.get('/posts/:id', (c) => {
106
+ return c.text(baseRoutePath(c)) // '/:sub'
107
+ })
108
+
109
+ app.route('/:sub', subApp)
110
+ ```
111
+
112
+ ### Using with index parameter
113
+
114
+ You can optionally pass an index parameter to get the base route path at a specific
115
+ position, similar to `Array.prototype.at()`.
116
+
117
+ ```ts
118
+ app.all('/api/*', (c, next) => {
119
+ return next()
120
+ })
121
+
122
+ const subApp = new Acryl()
123
+ subApp.get('/users/:id', (c) => {
124
+ console.log(baseRoutePath(c, 0)) // '/' (first matched route)
125
+ console.log(baseRoutePath(c, -1)) // '/api' (last matched route)
126
+ return c.text('User details')
127
+ })
128
+
129
+ app.route('/api', subApp)
130
+ ```
131
+
132
+ ## `basePath()`
133
+
134
+ Returns the base path with embedded parameters from the actual request.
135
+
136
+ ```ts
137
+ const subApp = new Acryl()
138
+ subApp.get('/posts/:id', (c) => {
139
+ return c.text(basePath(c)) // '/api' (for request to '/api/posts/123')
140
+ })
141
+
142
+ app.route('/:sub', subApp)
143
+ ```
@@ -0,0 +1,390 @@
1
+ # SSG Helper
2
+
3
+ SSG Helper generates a static site from your Acryl application. It will retrieve the contents of registered routes and save them as static files.
4
+
5
+ ## Usage
6
+
7
+ ### Manual
8
+
9
+ If you have a simple Acryl application like the following:
10
+
11
+ ```tsx
12
+ // index.tsx
13
+ const app = new Acryl()
14
+
15
+ app.get('/', (c) => c.html('Hello, World!'))
16
+
17
+ app.use('/about', async (c, next) => {
18
+ c.setRenderer((content) => {
19
+ return c.html(
20
+ <html>
21
+ <head />
22
+ <body>
23
+ <p>{content}</p>
24
+ </body>
25
+ </html>
26
+ )
27
+ })
28
+ await next()
29
+ })
30
+
31
+ app.get('/about', (c) => {
32
+ return c.render(
33
+ <>
34
+ <title>Acryl SSG Page</title>Hello!
35
+ </>
36
+ )
37
+ })
38
+
39
+ export default app
40
+ ```
41
+
42
+ For Node.js, create a build script like this:
43
+
44
+ ```ts
45
+ // build.ts
46
+ import app from './index'
47
+ import { toSSG } from '@acryldev/blends/ssg'
48
+ import fs from 'fs/promises'
49
+
50
+ toSSG(app, fs)
51
+ ```
52
+
53
+ By executing the script, the files will be output as follows:
54
+
55
+ ```bash
56
+ ls ./static
57
+ about.html index.html
58
+ ```
59
+
60
+ ### Vite Plugin
61
+
62
+ Using the `@acryldev/vite-ssg` Vite Plugin, you can easily handle the process.
63
+
64
+ For more details, see here:
65
+
66
+ (not yet available)
67
+
68
+ ## toSSG
69
+
70
+ `toSSG` is the main function for generating static sites, taking an application and a filesystem module as arguments. It is based on the following:
71
+
72
+ ### Input
73
+
74
+ The arguments for toSSG are specified in ToSSGInterface.
75
+
76
+ ```ts
77
+ export interface ToSSGInterface {
78
+ (
79
+ app: Acryl,
80
+ fsModule: FileSystemModule,
81
+ options?: ToSSGOptions
82
+ ): Promise<ToSSGResult>
83
+ }
84
+ ```
85
+
86
+ - `app` specifies `new Acryl()` with registered routes.
87
+ - `fs` specifies the following object, assuming `node:fs/promise`.
88
+
89
+ ```ts
90
+ export interface FileSystemModule {
91
+ writeFile(path: string, data: string | Uint8Array): Promise<void>
92
+ mkdir(
93
+ path: string,
94
+ options: { recursive: boolean }
95
+ ): Promise<void | string>
96
+ }
97
+ ```
98
+
99
+ ### Using the adapter for Bun
100
+
101
+ On Bun, a `toSSG` function is provided by `acrylblends/bun`; it writes the files with `Bun.write`.
102
+
103
+ ### Options
104
+
105
+ Options are specified in the ToSSGOptions interface.
106
+
107
+ ```ts
108
+ export interface ToSSGOptions {
109
+ dir?: string
110
+ concurrency?: number
111
+ extensionMap?: Record<string, string>
112
+ plugins?: SSGPlugin[]
113
+ }
114
+ ```
115
+
116
+ - `dir` is the output destination for Static files. The default value is `./static`.
117
+ - `concurrency` is the concurrent number of files to be generated at the same time. The default value is `2`.
118
+ - `extensionMap` is a map containing the `Content-Type` as a key and the string of the extension as a value. This is used to determine the file extension of the output file.
119
+ - `plugins` is an array of SSG plugins that extend the functionality of the static site generation process.
120
+
121
+ ### Output
122
+
123
+ `toSSG` returns the result in the following Result type.
124
+
125
+ ```ts
126
+ export interface ToSSGResult {
127
+ success: boolean
128
+ files: string[]
129
+ error?: Error
130
+ }
131
+ ```
132
+
133
+ ## Generate File
134
+
135
+ ### Route and Filename
136
+
137
+ The following rules apply to the registered route information and the generated file name. The default `./static` behaves as follows:
138
+
139
+ - `/` -> `./static/index.html`
140
+ - `/path` -> `./static/path.html`
141
+ - `/path/` -> `./static/path/index.html`
142
+
143
+ ### File Extension
144
+
145
+ The file extension depends on the `Content-Type` returned by each route. For example, responses from `c.html` are saved as `.html`.
146
+
147
+ If you want to customize the file extensions, set the `extensionMap` option.
148
+
149
+ ```ts
150
+ import { toSSG, defaultExtensionMap } from '@acryldev/blends/ssg'
151
+
152
+ // Save `application/x-html` content with `.html`
153
+ toSSG(app, fs, {
154
+ extensionMap: {
155
+ 'application/x-html': 'html',
156
+ ...defaultExtensionMap,
157
+ },
158
+ })
159
+ ```
160
+
161
+ Note that paths ending with a slash are saved as index.ext regardless of the extension.
162
+
163
+ ```ts
164
+ // save to ./static/html/index.html
165
+ app.get('/html/', (c) => c.html('html'))
166
+
167
+ // save to ./static/text/index.txt
168
+ app.get('/text/', (c) => c.text('text'))
169
+ ```
170
+
171
+ ## Middleware
172
+
173
+ Introducing built-in middleware that supports SSG.
174
+
175
+ ### ssgParams
176
+
177
+ You can use an API like `generateStaticParams` of Next.js.
178
+
179
+ Example:
180
+
181
+ ```ts
182
+ app.get(
183
+ '/shops/:id',
184
+ ssgParams(async () => {
185
+ const shops = await getShops()
186
+ return shops.map((shop) => ({ id: shop.id }))
187
+ }),
188
+ async (c) => {
189
+ const shop = await getShop(c.req.param('id'))
190
+ if (!shop) {
191
+ return c.notFound()
192
+ }
193
+ return c.render(
194
+ <div>
195
+ <h1>{shop.name}</h1>
196
+ </div>
197
+ )
198
+ }
199
+ )
200
+ ```
201
+
202
+ ### isSSGContext
203
+
204
+ `isSSGContext` is a helper function that returns `true` if the current application is running within the SSG context triggered by `toSSG`.
205
+
206
+ ```ts
207
+ app.get('/page', (c) => {
208
+ if (isSSGContext(c)) {
209
+ return c.text('This is generated by SSG')
210
+ }
211
+ return c.text('This is served dynamically')
212
+ })
213
+ ```
214
+
215
+ ### disableSSG
216
+
217
+ Routes with the `disableSSG` middleware set are excluded from static file generation by `toSSG`.
218
+
219
+ ```ts
220
+ app.get('/api', disableSSG(), (c) => c.text('an-api'))
221
+ ```
222
+
223
+ ### onlySSG
224
+
225
+ Routes with the `onlySSG` middleware set will be overridden by `c.notFound()` after `toSSG` execution.
226
+
227
+ ```ts
228
+ app.get('/static-page', onlySSG(), (c) => c.html(<h1>Welcome to my site</h1>))
229
+ ```
230
+
231
+ ## Plugins
232
+
233
+ Plugins allow you to extend the functionality of the static site generation process. They use hooks to customize the generation process at different stages.
234
+
235
+ ### Default Plugin
236
+
237
+ By default, `toSSG` uses `defaultPlugin()`, which skips non-200 status responses (like redirects, errors, or 404s). This prevents generating files for unsuccessful responses.
238
+
239
+ ```ts
240
+ import { toSSG, defaultPlugin } from '@acryldev/blends/ssg'
241
+
242
+ // defaultPlugin is automatically applied when no plugins specified
243
+ toSSG(app, fs)
244
+
245
+ // Equivalent to:
246
+ toSSG(app, fs, { plugins: [defaultPlugin()] })
247
+ ```
248
+
249
+ If you specify custom plugins, `defaultPlugin` is **not** automatically included. To keep the default behavior while adding custom plugins, explicitly include it:
250
+
251
+ ```ts
252
+ toSSG(app, fs, {
253
+ plugins: [defaultPlugin(), myCustomPlugin],
254
+ })
255
+ ```
256
+
257
+ ### Redirect Plugin
258
+
259
+ The `redirectPlugin` generates HTML redirect pages for routes that return HTTP redirect responses (301, 302, 303, 307, 308). The generated HTML includes a `<meta http-equiv="refresh">` tag and a canonical link.
260
+
261
+ ```ts
262
+ import { toSSG, redirectPlugin, defaultPlugin } from '@acryldev/blends/ssg'
263
+
264
+ toSSG(app, fs, {
265
+ plugins: [redirectPlugin(), defaultPlugin()],
266
+ })
267
+ ```
268
+
269
+ For example, if your app has:
270
+
271
+ ```ts
272
+ app.get('/old', (c) => c.redirect('/new'))
273
+ ```
274
+
275
+ The `redirectPlugin` will generate an HTML file at `/old.html` with a meta refresh redirect to `/new`.
276
+
277
+ > [!NOTE]
278
+ > When used with `defaultPlugin`, place `redirectPlugin` **before** `defaultPlugin`. Since `defaultPlugin` skips non-200 responses, placing it first would prevent `redirectPlugin` from processing redirect responses.
279
+
280
+ ### Hook Types
281
+
282
+ Plugins can use the following hooks to customize the `toSSG` process:
283
+
284
+ ```ts
285
+ export type BeforeRequestHook = (req: Request) => Request | false
286
+ export type AfterResponseHook = (res: Response) => Response | false
287
+ export type AfterGenerateHook = (
288
+ result: ToSSGResult
289
+ ) => void | Promise<void>
290
+ ```
291
+
292
+ - **BeforeRequestHook**: Called before processing each request. Return `false` to skip the route.
293
+ - **AfterResponseHook**: Called after receiving each response. Return `false` to skip file generation.
294
+ - **AfterGenerateHook**: Called after the entire generation process completes.
295
+
296
+ ### Plugin Interface
297
+
298
+ ```ts
299
+ export interface SSGPlugin {
300
+ beforeRequestHook?: BeforeRequestHook | BeforeRequestHook[]
301
+ afterResponseHook?: AfterResponseHook | AfterResponseHook[]
302
+ afterGenerateHook?: AfterGenerateHook | AfterGenerateHook[]
303
+ }
304
+ ```
305
+
306
+ ### Basic Plugin Examples
307
+
308
+ Filter only GET requests:
309
+
310
+ ```ts
311
+ const getOnlyPlugin: SSGPlugin = {
312
+ beforeRequestHook: (req) => {
313
+ if (req.method === 'GET') {
314
+ return req
315
+ }
316
+ return false
317
+ },
318
+ }
319
+ ```
320
+
321
+ Filter by status code:
322
+
323
+ ```ts
324
+ const statusFilterPlugin: SSGPlugin = {
325
+ afterResponseHook: (res) => {
326
+ if (res.status === 200 || res.status === 500) {
327
+ return res
328
+ }
329
+ return false
330
+ },
331
+ }
332
+ ```
333
+
334
+ Log generated files:
335
+
336
+ ```ts
337
+ const logFilesPlugin: SSGPlugin = {
338
+ afterGenerateHook: (result) => {
339
+ if (result.files) {
340
+ result.files.forEach((file) => console.log(file))
341
+ }
342
+ },
343
+ }
344
+ ```
345
+
346
+ ### Advanced Plugin Example
347
+
348
+ Here's an example of creating a sitemap plugin that generates a `sitemap.xml` file:
349
+
350
+ ```ts
351
+ // plugins.ts
352
+ import fs from 'node:fs/promises'
353
+ import path from 'node:path'
354
+ import type { SSGPlugin } from '@acryldev/blends/ssg'
355
+ import { DEFAULT_OUTPUT_DIR } from '@acryldev/blends/ssg'
356
+
357
+ export const sitemapPlugin = (baseURL: string): SSGPlugin => {
358
+ return {
359
+ afterGenerateHook: (result, fsModule, options) => {
360
+ const outputDir = options?.dir ?? DEFAULT_OUTPUT_DIR
361
+ const filePath = path.join(outputDir, 'sitemap.xml')
362
+ const urls = result.files.map((file) =>
363
+ new URL(file, baseURL).toString()
364
+ )
365
+ const siteMapText = `<?xml version="1.0" encoding="UTF-8"?>
366
+ <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
367
+ ${urls.map((url) => `<url><loc>${url}</loc></url>`).join('\n')}
368
+ </urlset>`
369
+ fsModule.writeFile(filePath, siteMapText)
370
+ },
371
+ }
372
+ }
373
+ ```
374
+
375
+ Applying plugins:
376
+
377
+ ```ts
378
+ import app from './index'
379
+ import { toSSG } from '@acryldev/blends/ssg'
380
+ import { sitemapPlugin } from './plugins'
381
+
382
+ toSSG(app, fs, {
383
+ plugins: [
384
+ getOnlyPlugin,
385
+ statusFilterPlugin,
386
+ logFilesPlugin,
387
+ sitemapPlugin('https://example.com'),
388
+ ],
389
+ })
390
+ ```