@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.
Files changed (98) hide show
  1. package/{docs/framework/LICENSE → LICENSE} +1 -3
  2. package/package.json +2 -2
  3. package/docs/framework/README.md +0 -70
  4. package/docs/framework/agents/index.md +0 -59
  5. package/docs/framework/api/acryl.md +0 -247
  6. package/docs/framework/api/context.md +0 -478
  7. package/docs/framework/api/exception.md +0 -80
  8. package/docs/framework/api/index.md +0 -12
  9. package/docs/framework/api/presets.md +0 -62
  10. package/docs/framework/api/request.md +0 -396
  11. package/docs/framework/api/routing.md +0 -303
  12. package/docs/framework/api/summary.md +0 -143
  13. package/docs/framework/concepts/benchmarks.md +0 -26
  14. package/docs/framework/concepts/developer-experience.md +0 -5
  15. package/docs/framework/concepts/middleware.md +0 -21
  16. package/docs/framework/concepts/motivation.md +0 -14
  17. package/docs/framework/concepts/routers.md +0 -63
  18. package/docs/framework/concepts/stacks.md +0 -235
  19. package/docs/framework/concepts/web-standard.md +0 -27
  20. package/docs/framework/cordis/acryl-in-a-cordis-app.md +0 -160
  21. package/docs/framework/cordis/concepts.md +0 -105
  22. package/docs/framework/cordis/middleware.md +0 -8
  23. package/docs/framework/cordis/migration-from-0-3.md +0 -111
  24. package/docs/framework/cordis/migration-from-0-4.md +0 -14
  25. package/docs/framework/cordis/migration-from-dsh-webserver.md +0 -109
  26. package/docs/framework/cordis/migration-to-1-0.md +0 -46
  27. package/docs/framework/cordis/mounting.md +0 -85
  28. package/docs/framework/cordis/node-server.md +0 -100
  29. package/docs/framework/cordis/plugin-lifecycle.md +0 -111
  30. package/docs/framework/cordis/surfaces.md +0 -71
  31. package/docs/framework/cordis/transport-and-cancellation.md +0 -57
  32. package/docs/framework/cordis/validation.md +0 -135
  33. package/docs/framework/getting-started/basic.md +0 -201
  34. package/docs/framework/getting-started/bun.md +0 -219
  35. package/docs/framework/getting-started/deploy.md +0 -133
  36. package/docs/framework/getting-started/desktop.md +0 -80
  37. package/docs/framework/getting-started/nodejs.md +0 -365
  38. package/docs/framework/getting-started/other-runtimes.md +0 -30
  39. package/docs/framework/guides/best-practices.md +0 -231
  40. package/docs/framework/guides/bring-your-own-tool.md +0 -218
  41. package/docs/framework/guides/client-modules.md +0 -210
  42. package/docs/framework/guides/create-acrylblends.md +0 -143
  43. package/docs/framework/guides/data.md +0 -314
  44. package/docs/framework/guides/examples.md +0 -3
  45. package/docs/framework/guides/faq.md +0 -19
  46. package/docs/framework/guides/forms-and-sessions.md +0 -235
  47. package/docs/framework/guides/helpers.md +0 -33
  48. package/docs/framework/guides/jsx-dom.md +0 -301
  49. package/docs/framework/guides/jsx.md +0 -487
  50. package/docs/framework/guides/middleware.md +0 -253
  51. package/docs/framework/guides/production.md +0 -80
  52. package/docs/framework/guides/rpc.md +0 -878
  53. package/docs/framework/guides/testing.md +0 -133
  54. package/docs/framework/guides/validation.md +0 -470
  55. package/docs/framework/helpers/accepts.md +0 -60
  56. package/docs/framework/helpers/adapter.md +0 -57
  57. package/docs/framework/helpers/conninfo.md +0 -77
  58. package/docs/framework/helpers/cookie.md +0 -232
  59. package/docs/framework/helpers/css.md +0 -282
  60. package/docs/framework/helpers/dev.md +0 -64
  61. package/docs/framework/helpers/factory.md +0 -180
  62. package/docs/framework/helpers/html.md +0 -123
  63. package/docs/framework/helpers/jwt.md +0 -184
  64. package/docs/framework/helpers/proxy.md +0 -115
  65. package/docs/framework/helpers/route.md +0 -143
  66. package/docs/framework/helpers/ssg.md +0 -390
  67. package/docs/framework/helpers/streaming.md +0 -224
  68. package/docs/framework/helpers/testing.md +0 -118
  69. package/docs/framework/helpers/websocket.md +0 -208
  70. package/docs/framework/middleware/builtin/basic-auth.md +0 -165
  71. package/docs/framework/middleware/builtin/bearer-auth.md +0 -138
  72. package/docs/framework/middleware/builtin/body-limit.md +0 -71
  73. package/docs/framework/middleware/builtin/cache.md +0 -99
  74. package/docs/framework/middleware/builtin/combine.md +0 -94
  75. package/docs/framework/middleware/builtin/compress.md +0 -59
  76. package/docs/framework/middleware/builtin/context-storage.md +0 -74
  77. package/docs/framework/middleware/builtin/cors.md +0 -134
  78. package/docs/framework/middleware/builtin/csrf.md +0 -105
  79. package/docs/framework/middleware/builtin/etag.md +0 -54
  80. package/docs/framework/middleware/builtin/ip-restriction.md +0 -69
  81. package/docs/framework/middleware/builtin/jsx-renderer.md +0 -283
  82. package/docs/framework/middleware/builtin/jwk.md +0 -192
  83. package/docs/framework/middleware/builtin/jwt.md +0 -145
  84. package/docs/framework/middleware/builtin/language.md +0 -232
  85. package/docs/framework/middleware/builtin/logger.md +0 -74
  86. package/docs/framework/middleware/builtin/loopback-only.md +0 -31
  87. package/docs/framework/middleware/builtin/method-not-allowed.md +0 -48
  88. package/docs/framework/middleware/builtin/method-override.md +0 -80
  89. package/docs/framework/middleware/builtin/mount.md +0 -103
  90. package/docs/framework/middleware/builtin/pretty-json.md +0 -53
  91. package/docs/framework/middleware/builtin/request-id.md +0 -87
  92. package/docs/framework/middleware/builtin/secure-headers.md +0 -247
  93. package/docs/framework/middleware/builtin/timeout.md +0 -98
  94. package/docs/framework/middleware/builtin/timing.md +0 -100
  95. package/docs/framework/middleware/builtin/trailing-slash.md +0 -74
  96. package/docs/framework/middleware/third-party.md +0 -4
  97. package/docs/framework/workshop/README.md +0 -294
  98. package/docs/framework/workshop/facilitator.md +0 -101
@@ -1,487 +0,0 @@
1
- # JSX
2
-
3
- You can write HTML with JSX syntax with `acrylblends/jsx`.
4
-
5
- Although `acrylblends/jsx` works on the client, you will probably use it most often when rendering content on the server side. Here are some things related to JSX that are common to both server and client.
6
-
7
- ## Settings
8
-
9
- To use JSX, modify the `tsconfig.json`:
10
-
11
- `tsconfig.json`:
12
-
13
- ```json
14
- {
15
- "compilerOptions": {
16
- "jsx": "react-jsx",
17
- "jsxImportSource": "@acryldev/blends/jsx"
18
- }
19
- }
20
- ```
21
-
22
- Alternatively, use the pragma directives:
23
-
24
- ```ts
25
- /** @jsx jsx */
26
- /** @jsxImportSource acrylblends/jsx */
27
- ```
28
-
29
- ## Run `.tsx` on Node.js
30
-
31
- Node.js strips TypeScript's types but does not compile JSX, so a `.tsx` file needs one flag: `--import acrylblends/node-server/register`.
32
- It compiles each `.tsx` (and `.jsx`) module as Node.js loads it, with your app's own `typescript` (a development dependency) and the
33
- `jsxImportSource` of your `tsconfig.json` (`acrylblends/jsx` without one); every other module runs exactly as before. Stack traces point at
34
- the `.tsx` lines.
35
-
36
- `package.json`:
37
-
38
- ```json
39
- {
40
- "scripts": {
41
- "dev": "node --watch --import acrylblends/node-server/register src/index.tsx",
42
- "start": "node --import acrylblends/node-server/register src/index.tsx",
43
- "test": "node --import acrylblends/node-server/register --test \"src/**/*.test.{ts,tsx}\""
44
- },
45
- "devDependencies": {
46
- "typescript": "^6.0.3"
47
- }
48
- }
49
- ```
50
-
51
- `node --test` looks only for `.js` and `.ts` test files on its own, so the `test` script names the `.tsx` ones with a pattern. Without `typescript` in the app, the first `.tsx` module stops with a message that says to install it. Bun compiles JSX itself and needs
52
- no flag.
53
-
54
- ## Usage
55
-
56
- > **Note.** If you are coming straight from the [Quick Start](../README.md#quick-start), the main file has a `.ts` extension - you need to change it to `.tsx` - otherwise you will not be able to run the application at all. Change the scripts in `package.json` to match: on Node.js, as [above](#run-tsx-on-nodejs); on Bun, `bun run --hot src/index.tsx` instead of `bun run --hot src/index.ts`.
57
-
58
- `index.tsx`:
59
-
60
- ```tsx
61
- import { Acryl } from '@acryldev/blends'
62
- import type { FC } from '@acryldev/blends/jsx'
63
-
64
- const app = new Acryl()
65
-
66
- const Layout: FC = (props) => {
67
- return (
68
- <html>
69
- <body>{props.children}</body>
70
- </html>
71
- )
72
- }
73
-
74
- const Top: FC<{ messages: string[] }> = (props: {
75
- messages: string[]
76
- }) => {
77
- return (
78
- <Layout>
79
- <h1>Acryl!</h1>
80
- <ul>
81
- {props.messages.map((message) => {
82
- return <li>{message}!!</li>
83
- })}
84
- </ul>
85
- </Layout>
86
- )
87
- }
88
-
89
- app.get('/', (c) => {
90
- const messages = ['Good Morning', 'Good Evening', 'Good Night']
91
- return c.html(<Top messages={messages} />)
92
- })
93
-
94
- export default app
95
- ```
96
-
97
- ## Without compiling: `jsx()`
98
-
99
- A `.ts` file can build the same nodes without JSX syntax and without the register flag: write the call that JSX compiles to.
100
- `jsx(tag, props, ...children)` takes the children after the props, and a node renders with `toString()`. The `` html`...` `` template
101
- from `acrylblends/html` is the other build-free choice.
102
-
103
- ```ts
104
- import { Acryl } from '@acryldev/blends'
105
- import { jsx } from '@acryldev/blends/jsx'
106
- import type { PropsWithChildren } from '@acryldev/blends/jsx'
107
-
108
- const Layout = (props: PropsWithChildren<{ title: string }>) =>
109
- jsx('html', { lang: 'en' }, jsx('head', null, jsx('title', null, props.title)), jsx('body', null, props.children))
110
-
111
- const About = () =>
112
- jsx(Layout, { title: 'About' }, jsx('h1', null, 'About'), jsx('p', { class: 'lead' }, 'Rendered on the server.'))
113
-
114
- const app = new Acryl()
115
- app.get('/about', (c) => c.html(jsx(About, null).toString()))
116
-
117
- export default app
118
- ```
119
-
120
- Pass the children as arguments after the props. A `children` entry inside the props object is not rendered by this form.
121
-
122
- ## Metadata hoisting
123
-
124
- You can write document metadata tags such as `<title>`, `<link>`, and `<meta>` directly inside your components. These tags will be automatically hoisted to the `<head>` section of the document. This is especially useful when the `<head>` element is rendered far from the component that determines the appropriate metadata.
125
-
126
- ```tsx
127
- import { Acryl } from '@acryldev/blends'
128
-
129
- const app = new Acryl()
130
-
131
- app.use('*', async (c, next) => {
132
- c.setRenderer((content) => {
133
- return c.html(
134
- <html>
135
- <head></head>
136
- <body>{content}</body>
137
- </html>
138
- )
139
- })
140
- await next()
141
- })
142
-
143
- app.get('/about', (c) => {
144
- return c.render(
145
- <>
146
- <title>About Page</title>
147
- <meta name='description' content='This is the about page.' />
148
- about page content
149
- </>
150
- )
151
- })
152
-
153
- export default app
154
- ```
155
-
156
- > **Note.** When hoisting occurs, existing elements are not removed. Elements appearing later are added to the end. For example, if you have `<title>Default</title>` in your `<head>` and a component renders `<title>Page Title</title>`, both titles will appear in the head.
157
-
158
- ## Fragment
159
-
160
- Use Fragment to group multiple elements without adding extra nodes:
161
-
162
- ```tsx
163
- import { Fragment } from '@acryldev/blends/jsx'
164
-
165
- const List = () => (
166
- <Fragment>
167
- <p>first child</p>
168
- <p>second child</p>
169
- <p>third child</p>
170
- </Fragment>
171
- )
172
- ```
173
-
174
- Or you can write it with `<></>` if it sets up properly.
175
-
176
- ```tsx
177
- const List = () => (
178
- <>
179
- <p>first child</p>
180
- <p>second child</p>
181
- <p>third child</p>
182
- </>
183
- )
184
- ```
185
-
186
- ## `PropsWithChildren`
187
-
188
- You can use `PropsWithChildren` to correctly infer a child element in a function component.
189
-
190
- ```tsx
191
- import { PropsWithChildren } from '@acryldev/blends/jsx'
192
-
193
- type Post = {
194
- id: number
195
- title: string
196
- }
197
-
198
- function Component({ title, children }: PropsWithChildren<Post>) {
199
- return (
200
- <div>
201
- <h1>{title}</h1>
202
- {children}
203
- </div>
204
- )
205
- }
206
- ```
207
-
208
- ## Inserting Raw HTML
209
-
210
- To directly insert HTML, use `dangerouslySetInnerHTML`:
211
-
212
- ```tsx
213
- app.get('/foo', (c) => {
214
- const inner = { __html: 'JSX &middot; SSR' }
215
- const Div = <div dangerouslySetInnerHTML={inner} />
216
- })
217
- ```
218
-
219
- ## Memoization
220
-
221
- Optimize your components by memoizing computed strings using `memo`:
222
-
223
- ```tsx
224
- import { memo } from '@acryldev/blends/jsx'
225
-
226
- const Header = memo(() => <header>Welcome to Acryl</header>)
227
- const Footer = memo(() => <footer>Powered by Acryl</footer>)
228
- const Layout = (
229
- <div>
230
- <Header />
231
- <p>Acryl is cool!</p>
232
- <Footer />
233
- </div>
234
- )
235
- ```
236
-
237
- ## Context
238
-
239
- By using `useContext`, you can share data globally across any level of the Component tree without passing values through props.
240
-
241
- ```tsx
242
- import type { FC } from '@acryldev/blends/jsx'
243
- import { createContext, useContext } from '@acryldev/blends/jsx'
244
-
245
- const themes = {
246
- light: {
247
- color: '#000000',
248
- background: '#eeeeee',
249
- },
250
- dark: {
251
- color: '#ffffff',
252
- background: '#222222',
253
- },
254
- }
255
-
256
- const ThemeContext = createContext(themes.light)
257
-
258
- const Button: FC = () => {
259
- const theme = useContext(ThemeContext)
260
- return <button style={theme}>Push!</button>
261
- }
262
-
263
- const Toolbar: FC = () => {
264
- return (
265
- <div>
266
- <Button />
267
- </div>
268
- )
269
- }
270
-
271
- // ...
272
-
273
- app.get('/', (c) => {
274
- return c.html(
275
- <div>
276
- <ThemeContext.Provider value={themes.dark}>
277
- <Toolbar />
278
- </ThemeContext.Provider>
279
- </div>
280
- )
281
- })
282
- ```
283
-
284
- ## Async Component
285
-
286
- `acrylblends/jsx` supports an Async Component, so you can use `async`/`await` in your component.
287
- If you render it with `c.html()`, it will await automatically.
288
-
289
- ```tsx
290
- const AsyncComponent = async () => {
291
- await new Promise((r) => setTimeout(r, 1000)) // sleep 1s
292
- return <div>Done!</div>
293
- }
294
-
295
- app.get('/', (c) => {
296
- return c.html(
297
- <html>
298
- <body>
299
- <AsyncComponent />
300
- </body>
301
- </html>
302
- )
303
- })
304
- ```
305
-
306
- ## Suspense *(Experimental)*
307
-
308
- The React-like `Suspense` feature is available.
309
- If you wrap the async component with `Suspense`, the content in the fallback will be rendered first, and once the Promise is resolved, the awaited content will be displayed.
310
- You can use it with `renderToReadableStream()`.
311
-
312
- ```tsx
313
- import { renderToReadableStream, Suspense } from '@acryldev/blends/jsx/streaming'
314
-
315
- //...
316
-
317
- app.get('/', (c) => {
318
- const stream = renderToReadableStream(
319
- <html>
320
- <body>
321
- <Suspense fallback={<div>loading...</div>}>
322
- <Component />
323
- </Suspense>
324
- </body>
325
- </html>
326
- )
327
- return c.body(stream, {
328
- headers: {
329
- 'Content-Type': 'text/html; charset=UTF-8',
330
- 'Transfer-Encoding': 'chunked',
331
- },
332
- })
333
- })
334
- ```
335
-
336
- ## ErrorBoundary *(Experimental)*
337
-
338
- You can catch errors in child components using `ErrorBoundary`.
339
-
340
- In the example below, it will show the content specified in `fallback` if an error occurs.
341
-
342
- ```tsx
343
- function SyncComponent() {
344
- throw new Error('Error')
345
- return <div>Hello</div>
346
- }
347
-
348
- app.get('/sync', async (c) => {
349
- return c.html(
350
- <html>
351
- <body>
352
- <ErrorBoundary fallback={<div>Out of Service</div>}>
353
- <SyncComponent />
354
- </ErrorBoundary>
355
- </body>
356
- </html>
357
- )
358
- })
359
- ```
360
-
361
- `ErrorBoundary` can also be used with async components and `Suspense`.
362
-
363
- ```tsx
364
- async function AsyncComponent() {
365
- await new Promise((resolve) => setTimeout(resolve, 2000))
366
- throw new Error('Error')
367
- return <div>Hello</div>
368
- }
369
-
370
- app.get('/with-suspense', async (c) => {
371
- return c.html(
372
- <html>
373
- <body>
374
- <ErrorBoundary fallback={<div>Out of Service</div>}>
375
- <Suspense fallback={<div>Loading...</div>}>
376
- <AsyncComponent />
377
- </Suspense>
378
- </ErrorBoundary>
379
- </body>
380
- </html>
381
- )
382
- })
383
- ```
384
-
385
- ## StreamingContext *(Experimental)*
386
-
387
- You can use `StreamingContext` to provide configuration for streaming components like `Suspense` and `ErrorBoundary`. This is useful for adding nonce values to script tags generated by these components for Content Security Policy (CSP).
388
-
389
- ```tsx
390
- import { Suspense, StreamingContext } from '@acryldev/blends/jsx/streaming'
391
-
392
- // ...
393
-
394
- app.get('/', (c) => {
395
- const stream = renderToReadableStream(
396
- <html>
397
- <body>
398
- <StreamingContext
399
- value={{ scriptNonce: 'random-nonce-value' }}
400
- >
401
- <Suspense fallback={<div>Loading...</div>}>
402
- <AsyncComponent />
403
- </Suspense>
404
- </StreamingContext>
405
- </body>
406
- </html>
407
- )
408
-
409
- return c.body(stream, {
410
- headers: {
411
- 'Content-Type': 'text/html; charset=UTF-8',
412
- 'Transfer-Encoding': 'chunked',
413
- 'Content-Security-Policy':
414
- "script-src 'nonce-random-nonce-value'",
415
- },
416
- })
417
- })
418
- ```
419
-
420
- The `scriptNonce` value will be automatically added to any `<script>` tags generated by `Suspense` and `ErrorBoundary` components.
421
-
422
- ## Integration with html Middleware
423
-
424
- Combine the JSX and HTML middlewares for powerful templating.
425
- For in-depth details, consult the [HTML middleware documentation](../helpers/html.md).
426
-
427
- ```tsx
428
- import { Acryl } from '@acryldev/blends'
429
- import { html } from '@acryldev/blends/html'
430
-
431
- const app = new Acryl()
432
-
433
- interface SiteData {
434
- title: string
435
- children?: any
436
- }
437
-
438
- const Layout = (props: SiteData) =>
439
- html`<!doctype html>
440
- <html>
441
- <head>
442
- <title>${props.title}</title>
443
- </head>
444
- <body>
445
- ${props.children}
446
- </body>
447
- </html>`
448
-
449
- const Content = (props: { siteData: SiteData; name: string }) => (
450
- <Layout {...props.siteData}>
451
- <h1>Hello {props.name}</h1>
452
- </Layout>
453
- )
454
-
455
- app.get('/:name', (c) => {
456
- const { name } = c.req.param()
457
- const props = {
458
- name: name,
459
- siteData: {
460
- title: 'JSX with html sample',
461
- },
462
- }
463
- return c.html(<Content {...props} />)
464
- })
465
-
466
- export default app
467
- ```
468
-
469
- ## With JSX Renderer Middleware
470
-
471
- The [JSX Renderer Middleware](../middleware/builtin/jsx-renderer.md) allows you to create HTML pages more easily with the JSX.
472
-
473
- ## Override type definitions
474
-
475
- You can override the type definition to add your custom elements and attributes.
476
-
477
- ```ts
478
- declare module '@acryldev/blends/jsx' {
479
- namespace JSX {
480
- interface IntrinsicElements {
481
- 'my-custom-element': HTMLAttributes & {
482
- 'x-event'?: 'click' | 'scroll'
483
- }
484
- }
485
- }
486
- }
487
- ```