@acryldev/create-blends 1.7.1 → 1.7.3
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/{LICENSE → docs/framework/LICENSE} +3 -1
- package/docs/framework/README.md +70 -0
- package/docs/framework/agents/index.md +59 -0
- package/docs/framework/api/acryl.md +247 -0
- package/docs/framework/api/context.md +478 -0
- package/docs/framework/api/exception.md +80 -0
- package/docs/framework/api/index.md +12 -0
- package/docs/framework/api/presets.md +62 -0
- package/docs/framework/api/request.md +396 -0
- package/docs/framework/api/routing.md +303 -0
- package/docs/framework/api/summary.md +143 -0
- package/docs/framework/concepts/benchmarks.md +26 -0
- package/docs/framework/concepts/developer-experience.md +5 -0
- package/docs/framework/concepts/middleware.md +21 -0
- package/docs/framework/concepts/motivation.md +14 -0
- package/docs/framework/concepts/routers.md +63 -0
- package/docs/framework/concepts/stacks.md +235 -0
- package/docs/framework/concepts/web-standard.md +27 -0
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
- package/docs/framework/cordis/concepts.md +105 -0
- package/docs/framework/cordis/middleware.md +8 -0
- package/docs/framework/cordis/migration-from-0-3.md +111 -0
- package/docs/framework/cordis/migration-from-0-4.md +14 -0
- package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
- package/docs/framework/cordis/migration-to-1-0.md +46 -0
- package/docs/framework/cordis/mounting.md +85 -0
- package/docs/framework/cordis/node-server.md +100 -0
- package/docs/framework/cordis/plugin-lifecycle.md +111 -0
- package/docs/framework/cordis/surfaces.md +71 -0
- package/docs/framework/cordis/transport-and-cancellation.md +57 -0
- package/docs/framework/cordis/validation.md +135 -0
- package/docs/framework/getting-started/basic.md +201 -0
- package/docs/framework/getting-started/bun.md +219 -0
- package/docs/framework/getting-started/deploy.md +133 -0
- package/docs/framework/getting-started/desktop.md +80 -0
- package/docs/framework/getting-started/nodejs.md +365 -0
- package/docs/framework/getting-started/other-runtimes.md +30 -0
- package/docs/framework/guides/best-practices.md +231 -0
- package/docs/framework/guides/bring-your-own-tool.md +218 -0
- package/docs/framework/guides/client-modules.md +210 -0
- package/docs/framework/guides/create-acrylblends.md +143 -0
- package/docs/framework/guides/data.md +314 -0
- package/docs/framework/guides/examples.md +3 -0
- package/docs/framework/guides/faq.md +19 -0
- package/docs/framework/guides/forms-and-sessions.md +235 -0
- package/docs/framework/guides/helpers.md +33 -0
- package/docs/framework/guides/jsx-dom.md +301 -0
- package/docs/framework/guides/jsx.md +487 -0
- package/docs/framework/guides/middleware.md +253 -0
- package/docs/framework/guides/production.md +80 -0
- package/docs/framework/guides/rpc.md +878 -0
- package/docs/framework/guides/testing.md +133 -0
- package/docs/framework/guides/validation.md +470 -0
- package/docs/framework/helpers/accepts.md +60 -0
- package/docs/framework/helpers/adapter.md +57 -0
- package/docs/framework/helpers/conninfo.md +77 -0
- package/docs/framework/helpers/cookie.md +232 -0
- package/docs/framework/helpers/css.md +282 -0
- package/docs/framework/helpers/dev.md +64 -0
- package/docs/framework/helpers/factory.md +180 -0
- package/docs/framework/helpers/html.md +123 -0
- package/docs/framework/helpers/jwt.md +184 -0
- package/docs/framework/helpers/proxy.md +115 -0
- package/docs/framework/helpers/route.md +143 -0
- package/docs/framework/helpers/ssg.md +390 -0
- package/docs/framework/helpers/streaming.md +224 -0
- package/docs/framework/helpers/testing.md +118 -0
- package/docs/framework/helpers/websocket.md +208 -0
- package/docs/framework/middleware/builtin/basic-auth.md +165 -0
- package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
- package/docs/framework/middleware/builtin/body-limit.md +71 -0
- package/docs/framework/middleware/builtin/cache.md +99 -0
- package/docs/framework/middleware/builtin/combine.md +94 -0
- package/docs/framework/middleware/builtin/compress.md +59 -0
- package/docs/framework/middleware/builtin/context-storage.md +74 -0
- package/docs/framework/middleware/builtin/cors.md +134 -0
- package/docs/framework/middleware/builtin/csrf.md +105 -0
- package/docs/framework/middleware/builtin/etag.md +54 -0
- package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
- package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
- package/docs/framework/middleware/builtin/jwk.md +192 -0
- package/docs/framework/middleware/builtin/jwt.md +145 -0
- package/docs/framework/middleware/builtin/language.md +232 -0
- package/docs/framework/middleware/builtin/logger.md +74 -0
- package/docs/framework/middleware/builtin/loopback-only.md +31 -0
- package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
- package/docs/framework/middleware/builtin/method-override.md +80 -0
- package/docs/framework/middleware/builtin/mount.md +103 -0
- package/docs/framework/middleware/builtin/pretty-json.md +53 -0
- package/docs/framework/middleware/builtin/request-id.md +87 -0
- package/docs/framework/middleware/builtin/secure-headers.md +247 -0
- package/docs/framework/middleware/builtin/timeout.md +98 -0
- package/docs/framework/middleware/builtin/timing.md +100 -0
- package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
- package/docs/framework/middleware/third-party.md +4 -0
- package/docs/framework/workshop/README.md +294 -0
- package/docs/framework/workshop/facilitator.md +101 -0
- package/package.json +3 -3
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# CORS Middleware
|
|
2
|
+
|
|
3
|
+
A web API is often called from a page served by another origin. For that we have to implement CORS, and this middleware does it.
|
|
4
|
+
|
|
5
|
+
## Import
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { Acryl } from '@acryldev/blends'
|
|
9
|
+
import { cors } from '@acryldev/blends/cors'
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Usage
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
const app = new Acryl()
|
|
16
|
+
|
|
17
|
+
// CORS should be called before the route
|
|
18
|
+
app.use('/api/*', cors())
|
|
19
|
+
app.use(
|
|
20
|
+
'/api2/*',
|
|
21
|
+
cors({
|
|
22
|
+
origin: 'http://example.com',
|
|
23
|
+
allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'],
|
|
24
|
+
allowMethods: ['POST', 'GET', 'OPTIONS'],
|
|
25
|
+
exposeHeaders: ['Content-Length', 'X-Kuma-Revision'],
|
|
26
|
+
maxAge: 600,
|
|
27
|
+
credentials: true,
|
|
28
|
+
})
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
app.all('/api/abc', (c) => {
|
|
32
|
+
return c.json({ success: true })
|
|
33
|
+
})
|
|
34
|
+
app.all('/api2/abc', (c) => {
|
|
35
|
+
return c.json({ success: true })
|
|
36
|
+
})
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Multiple origins:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
app.use(
|
|
43
|
+
'/api3/*',
|
|
44
|
+
cors({
|
|
45
|
+
origin: ['https://example.com', 'https://example.org'],
|
|
46
|
+
})
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
// Or you can use "function"
|
|
50
|
+
app.use(
|
|
51
|
+
'/api4/*',
|
|
52
|
+
cors({
|
|
53
|
+
// `c` is a `Context` object
|
|
54
|
+
origin: (origin, c) => {
|
|
55
|
+
return origin.endsWith('.example.com')
|
|
56
|
+
? origin
|
|
57
|
+
: 'http://example.com'
|
|
58
|
+
},
|
|
59
|
+
})
|
|
60
|
+
)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Dynamic allowed methods based on origin:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
app.use(
|
|
67
|
+
'/api5/*',
|
|
68
|
+
cors({
|
|
69
|
+
origin: (origin) =>
|
|
70
|
+
origin === 'https://example.com' ? origin : '*',
|
|
71
|
+
// `c` is a `Context` object
|
|
72
|
+
allowMethods: (origin, c) =>
|
|
73
|
+
origin === 'https://example.com'
|
|
74
|
+
? ['GET', 'HEAD', 'POST', 'PATCH', 'DELETE']
|
|
75
|
+
: ['GET', 'HEAD'],
|
|
76
|
+
})
|
|
77
|
+
)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Options
|
|
81
|
+
|
|
82
|
+
### *(optional)* origin: `string` | `string[]` | `(origin:string, c:Context) => string`
|
|
83
|
+
|
|
84
|
+
The value of "_Access-Control-Allow-Origin_" CORS header. You can also pass the callback function like `origin: (origin) => (origin.endsWith('.example.com') ? origin : 'http://example.com')`. The default is `*`.
|
|
85
|
+
|
|
86
|
+
### *(optional)* allowMethods: `string[]` | `(origin:string, c:Context) => string[]`
|
|
87
|
+
|
|
88
|
+
The value of "_Access-Control-Allow-Methods_" CORS header. You can also pass a callback function to dynamically determine allowed methods based on the origin. The default is `['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH', 'QUERY']`.
|
|
89
|
+
|
|
90
|
+
### *(optional)* allowHeaders: `string[]`
|
|
91
|
+
|
|
92
|
+
The value of "_Access-Control-Allow-Headers_" CORS header. The default is `[]`.
|
|
93
|
+
|
|
94
|
+
### *(optional)* maxAge: `number`
|
|
95
|
+
|
|
96
|
+
The value of "_Access-Control-Max-Age_" CORS header.
|
|
97
|
+
|
|
98
|
+
### *(optional)* credentials: `boolean`
|
|
99
|
+
|
|
100
|
+
The value of "_Access-Control-Allow-Credentials_" CORS header.
|
|
101
|
+
|
|
102
|
+
### *(optional)* exposeHeaders: `string[]`
|
|
103
|
+
|
|
104
|
+
The value of "_Access-Control-Expose-Headers_" CORS header. The default is `[]`.
|
|
105
|
+
|
|
106
|
+
## Environment-dependent CORS configuration
|
|
107
|
+
|
|
108
|
+
If you want to adjust CORS configuration according to the execution environment, such as development or production, injecting values from environment variables is convenient as it eliminates the need for the application to be aware of its own execution environment. See the example below for clarification.
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
app.use('*', async (c, next) => {
|
|
112
|
+
const corsMiddlewareHandler = cors({
|
|
113
|
+
origin: c.env.CORS_ORIGIN,
|
|
114
|
+
})
|
|
115
|
+
return corsMiddlewareHandler(c, next)
|
|
116
|
+
})
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Using with Vite
|
|
120
|
+
|
|
121
|
+
When using Acryl with Vite, you should disable Vite's built-in CORS feature by setting `server.cors` to `false` in your `vite.config.ts`. This prevents conflicts with Acryl's CORS middleware.
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
// vite.config.ts
|
|
125
|
+
import { cloudflare } from '@cloudflare/vite-plugin'
|
|
126
|
+
import { defineConfig } from 'vite'
|
|
127
|
+
|
|
128
|
+
export default defineConfig({
|
|
129
|
+
server: {
|
|
130
|
+
cors: false, // disable Vite's built-in CORS setting
|
|
131
|
+
},
|
|
132
|
+
plugins: [cloudflare()],
|
|
133
|
+
})
|
|
134
|
+
```
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# CSRF Protection
|
|
2
|
+
|
|
3
|
+
This middleware protects against CSRF attacks by checking both the `Origin` header and the `Sec-Fetch-Site` header. The request is allowed if either validation passes.
|
|
4
|
+
|
|
5
|
+
The middleware only validates requests that:
|
|
6
|
+
|
|
7
|
+
- Use unsafe HTTP methods (not GET, HEAD, or OPTIONS)
|
|
8
|
+
- Have content types that can be sent by HTML forms (`application/x-www-form-urlencoded`, `multipart/form-data`, or `text/plain`)
|
|
9
|
+
|
|
10
|
+
Old browsers that do not send `Origin` headers, or environments that use reverse proxies to remove these headers, may not work well. In such environments, use other CSRF token methods.
|
|
11
|
+
|
|
12
|
+
## Import
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
import { Acryl } from '@acryldev/blends'
|
|
16
|
+
import { csrf } from '@acryldev/blends/csrf'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
const app = new Acryl()
|
|
23
|
+
|
|
24
|
+
// Default: both origin and sec-fetch-site validation
|
|
25
|
+
app.use(csrf())
|
|
26
|
+
|
|
27
|
+
// Allow specific origins
|
|
28
|
+
app.use(csrf({ origin: 'https://myapp.example.com' }))
|
|
29
|
+
|
|
30
|
+
// Allow multiple origins
|
|
31
|
+
app.use(
|
|
32
|
+
csrf({
|
|
33
|
+
origin: [
|
|
34
|
+
'https://myapp.example.com',
|
|
35
|
+
'https://development.myapp.example.com',
|
|
36
|
+
],
|
|
37
|
+
})
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
// Allow specific sec-fetch-site values
|
|
41
|
+
app.use(csrf({ secFetchSite: 'same-origin' }))
|
|
42
|
+
app.use(csrf({ secFetchSite: ['same-origin', 'none'] }))
|
|
43
|
+
|
|
44
|
+
// Dynamic origin validation
|
|
45
|
+
// It is strongly recommended that the protocol be verified to ensure a match to `$`.
|
|
46
|
+
// You should *never* do a forward match.
|
|
47
|
+
app.use(
|
|
48
|
+
'*',
|
|
49
|
+
csrf({
|
|
50
|
+
origin: (origin) =>
|
|
51
|
+
/https:\/\/(\w+\.)?myapp\.example\.com$/.test(origin),
|
|
52
|
+
})
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
// Dynamic sec-fetch-site validation
|
|
56
|
+
app.use(
|
|
57
|
+
csrf({
|
|
58
|
+
secFetchSite: (secFetchSite, c) => {
|
|
59
|
+
// Always allow same-origin
|
|
60
|
+
if (secFetchSite === 'same-origin') return true
|
|
61
|
+
// Allow cross-site for webhook endpoints
|
|
62
|
+
if (
|
|
63
|
+
secFetchSite === 'cross-site' &&
|
|
64
|
+
c.req.path.startsWith('/webhook/')
|
|
65
|
+
) {
|
|
66
|
+
return true
|
|
67
|
+
}
|
|
68
|
+
return false
|
|
69
|
+
},
|
|
70
|
+
})
|
|
71
|
+
)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Options
|
|
75
|
+
|
|
76
|
+
### *(optional)* origin: `string` | `string[]` | `Function`
|
|
77
|
+
|
|
78
|
+
Specify allowed origins for CSRF protection.
|
|
79
|
+
|
|
80
|
+
- **`string`**: Single allowed origin (e.g., `'https://example.com'`)
|
|
81
|
+
- **`string[]`**: Array of allowed origins
|
|
82
|
+
- **`Function`**: Custom handler `(origin: string, context: Context) => boolean` for flexible origin validation and bypass logic
|
|
83
|
+
|
|
84
|
+
**Default**: Only same origin as the request URL
|
|
85
|
+
|
|
86
|
+
The function handler receives the request's `Origin` header value and the request context, allowing for dynamic validation based on request properties like path, headers, or other context data.
|
|
87
|
+
|
|
88
|
+
### *(optional)* secFetchSite: `string` | `string[]` | `Function`
|
|
89
|
+
|
|
90
|
+
Specify allowed Sec-Fetch-Site header values for CSRF protection using [Fetch Metadata](https://web.dev/articles/fetch-metadata).
|
|
91
|
+
|
|
92
|
+
- **`string`**: Single allowed value (e.g., `'same-origin'`)
|
|
93
|
+
- **`string[]`**: Array of allowed values (e.g., `['same-origin', 'none']`)
|
|
94
|
+
- **`Function`**: Custom handler `(secFetchSite: string, context: Context) => boolean` for flexible validation
|
|
95
|
+
|
|
96
|
+
**Default**: Only allows `'same-origin'`
|
|
97
|
+
|
|
98
|
+
Standard Sec-Fetch-Site values:
|
|
99
|
+
|
|
100
|
+
- `same-origin`: Request from same origin
|
|
101
|
+
- `same-site`: Request from same site (different subdomain)
|
|
102
|
+
- `cross-site`: Request from different site
|
|
103
|
+
- `none`: Request not from a web page (e.g., browser address bar, bookmark)
|
|
104
|
+
|
|
105
|
+
The function handler receives the request's `Sec-Fetch-Site` header value and the request context, enabling dynamic validation based on request properties.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# ETag Middleware
|
|
2
|
+
|
|
3
|
+
Using this middleware, you can add ETag headers easily.
|
|
4
|
+
|
|
5
|
+
## Import
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { Acryl } from '@acryldev/blends'
|
|
9
|
+
import { etag } from '@acryldev/blends/etag'
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Usage
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
const app = new Acryl()
|
|
16
|
+
|
|
17
|
+
app.use('/etag/*', etag())
|
|
18
|
+
app.get('/etag/abc', (c) => {
|
|
19
|
+
return c.text('Acryl is cool')
|
|
20
|
+
})
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## The retained headers
|
|
24
|
+
|
|
25
|
+
The 304 Response must include the headers that would have been sent in an equivalent 200 OK response. The default headers are Cache-Control, Content-Location, Date, ETag, Expires, and Vary.
|
|
26
|
+
|
|
27
|
+
If you want to add the header that is sent, you can use `retainedHeaders` option and `RETAINED_304_HEADERS` strings array variable that includes the default headers:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { etag, RETAINED_304_HEADERS } from '@acryldev/blends/etag'
|
|
31
|
+
|
|
32
|
+
// ...
|
|
33
|
+
|
|
34
|
+
app.use(
|
|
35
|
+
'/etag/*',
|
|
36
|
+
etag({
|
|
37
|
+
retainedHeaders: ['x-message', ...RETAINED_304_HEADERS],
|
|
38
|
+
})
|
|
39
|
+
)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Options
|
|
43
|
+
|
|
44
|
+
### *(optional)* weak: `boolean`
|
|
45
|
+
|
|
46
|
+
Define using or not using a [weak validation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests#weak_validation). If `true` is set, then `w/` is added to the prefix of the value. The default is `false`.
|
|
47
|
+
|
|
48
|
+
### *(optional)* retainedHeaders: `string[]`
|
|
49
|
+
|
|
50
|
+
The headers that you want to retain in the 304 Response.
|
|
51
|
+
|
|
52
|
+
### *(optional)* generateDigest: `(body: Uint8Array) => ArrayBuffer | Promise<ArrayBuffer>`
|
|
53
|
+
|
|
54
|
+
A custom digest generation function. By default, it uses `SHA-1`. This function is called with the response body as a `Uint8Array` and should return a hash as an `ArrayBuffer` or a Promise of one.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# IP Restriction Middleware
|
|
2
|
+
|
|
3
|
+
IP Restriction Middleware is middleware that limits access to resources based on the IP address of the user.
|
|
4
|
+
|
|
5
|
+
## Import
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { Acryl } from '@acryldev/blends'
|
|
9
|
+
import { ipRestriction } from '@acryldev/blends/ip-restriction'
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Usage
|
|
13
|
+
|
|
14
|
+
For your application running on Node.js, if you want to allow access only from local, you can write it as follows. Specify the rules you want to deny in the `denyList` and the rules you want to allow in the `allowList`.
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
import { Acryl } from '@acryldev/blends'
|
|
18
|
+
import { getConnInfo } from '@acryldev/blends/node-server'
|
|
19
|
+
import { ipRestriction } from '@acryldev/blends/ip-restriction'
|
|
20
|
+
|
|
21
|
+
const app = new Acryl()
|
|
22
|
+
|
|
23
|
+
app.use(
|
|
24
|
+
'*',
|
|
25
|
+
ipRestriction(getConnInfo, {
|
|
26
|
+
denyList: [],
|
|
27
|
+
allowList: ['127.0.0.1', '::1'],
|
|
28
|
+
})
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
app.get('/', (c) => c.text('Acryl!'))
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. Every adapter has one (`acrylblends/node-server` and `acrylblends/bun`).
|
|
35
|
+
|
|
36
|
+
## Rules
|
|
37
|
+
|
|
38
|
+
Follow the instructions below for writing rules.
|
|
39
|
+
|
|
40
|
+
### IPv4
|
|
41
|
+
|
|
42
|
+
- `192.168.2.0` - Static IP Address
|
|
43
|
+
- `192.168.2.0/24` - CIDR Notation
|
|
44
|
+
- `*` - ALL Addresses
|
|
45
|
+
|
|
46
|
+
### IPv6
|
|
47
|
+
|
|
48
|
+
- `::1` - Static IP Address
|
|
49
|
+
- `::1/10` - CIDR Notation
|
|
50
|
+
- `*` - ALL Addresses
|
|
51
|
+
|
|
52
|
+
## Error handling
|
|
53
|
+
|
|
54
|
+
To customize the error, return a `Response` in the third argument.
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
app.use(
|
|
58
|
+
'*',
|
|
59
|
+
ipRestriction(
|
|
60
|
+
getConnInfo,
|
|
61
|
+
{
|
|
62
|
+
denyList: ['192.168.2.0/24'],
|
|
63
|
+
},
|
|
64
|
+
async (remote, c) => {
|
|
65
|
+
return c.text(`Blocking access from ${remote.addr}`, 403)
|
|
66
|
+
}
|
|
67
|
+
)
|
|
68
|
+
)
|
|
69
|
+
```
|
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
# JSX Renderer Middleware
|
|
2
|
+
|
|
3
|
+
JSX Renderer Middleware allows you to set up the layout when rendering JSX with the `c.render()` function, without the need for using `c.setRenderer()`. Additionally, it enables access to instances of Context within components through the use of `useRequestContext()`.
|
|
4
|
+
|
|
5
|
+
## Import
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { Acryl } from '@acryldev/blends'
|
|
9
|
+
import { jsxRenderer, useRequestContext } from '@acryldev/blends/jsx-renderer'
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Usage
|
|
13
|
+
|
|
14
|
+
```jsx
|
|
15
|
+
const app = new Acryl()
|
|
16
|
+
|
|
17
|
+
app.get(
|
|
18
|
+
'/page/*',
|
|
19
|
+
jsxRenderer(({ children }) => {
|
|
20
|
+
return (
|
|
21
|
+
<html>
|
|
22
|
+
<body>
|
|
23
|
+
<header>Menu</header>
|
|
24
|
+
<div>{children}</div>
|
|
25
|
+
</body>
|
|
26
|
+
</html>
|
|
27
|
+
)
|
|
28
|
+
})
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
app.get('/page/about', (c) => {
|
|
32
|
+
return c.render(<h1>About me!</h1>)
|
|
33
|
+
})
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Options
|
|
37
|
+
|
|
38
|
+
### *(optional)* docType: `boolean` | `string`
|
|
39
|
+
|
|
40
|
+
If you do not want to add a DOCTYPE at the beginning of the HTML, set the `docType` option to `false`.
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
app.use(
|
|
44
|
+
'*',
|
|
45
|
+
jsxRenderer(
|
|
46
|
+
({ children }) => {
|
|
47
|
+
return (
|
|
48
|
+
<html>
|
|
49
|
+
<body>{children}</body>
|
|
50
|
+
</html>
|
|
51
|
+
)
|
|
52
|
+
},
|
|
53
|
+
{ docType: false }
|
|
54
|
+
)
|
|
55
|
+
)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
And you can specify the DOCTYPE.
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
app.use(
|
|
62
|
+
'*',
|
|
63
|
+
jsxRenderer(
|
|
64
|
+
({ children }) => {
|
|
65
|
+
return (
|
|
66
|
+
<html>
|
|
67
|
+
<body>{children}</body>
|
|
68
|
+
</html>
|
|
69
|
+
)
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
docType:
|
|
73
|
+
'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
|
|
74
|
+
}
|
|
75
|
+
)
|
|
76
|
+
)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### *(optional)* stream: `boolean` | `Record<string, string>`
|
|
80
|
+
|
|
81
|
+
If you set it to `true` or provide a Record value, it will be rendered as a streaming response.
|
|
82
|
+
|
|
83
|
+
```tsx
|
|
84
|
+
const AsyncComponent = async () => {
|
|
85
|
+
await new Promise((r) => setTimeout(r, 1000)) // sleep 1s
|
|
86
|
+
return <div>Hi!</div>
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
app.get(
|
|
90
|
+
'*',
|
|
91
|
+
jsxRenderer(
|
|
92
|
+
({ children }) => {
|
|
93
|
+
return (
|
|
94
|
+
<html>
|
|
95
|
+
<body>
|
|
96
|
+
<h1>SSR Streaming</h1>
|
|
97
|
+
{children}
|
|
98
|
+
</body>
|
|
99
|
+
</html>
|
|
100
|
+
)
|
|
101
|
+
},
|
|
102
|
+
{ stream: true }
|
|
103
|
+
)
|
|
104
|
+
)
|
|
105
|
+
|
|
106
|
+
app.get('/', (c) => {
|
|
107
|
+
return c.render(
|
|
108
|
+
<Suspense fallback={<div>loading...</div>}>
|
|
109
|
+
<AsyncComponent />
|
|
110
|
+
</Suspense>
|
|
111
|
+
)
|
|
112
|
+
})
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
If `true` is set, the following headers are added:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
{
|
|
119
|
+
'Transfer-Encoding': 'chunked',
|
|
120
|
+
'Content-Type': 'text/html; charset=UTF-8',
|
|
121
|
+
'Content-Encoding': 'Identity'
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
You can customize the header values by specifying the Record values.
|
|
126
|
+
|
|
127
|
+
### Function-based Options
|
|
128
|
+
|
|
129
|
+
You can pass a function that receives a `Context` object instead of a static options object. This allows you to dynamically set options based on the request context, such as environment variables or request parameters.
|
|
130
|
+
|
|
131
|
+
```tsx
|
|
132
|
+
app.use(
|
|
133
|
+
'*',
|
|
134
|
+
jsxRenderer(
|
|
135
|
+
({ children }) => {
|
|
136
|
+
return (
|
|
137
|
+
<html>
|
|
138
|
+
<body>{children}</body>
|
|
139
|
+
</html>
|
|
140
|
+
)
|
|
141
|
+
},
|
|
142
|
+
(c) => ({
|
|
143
|
+
stream: c.req.header('X-Enable-Streaming') === 'true',
|
|
144
|
+
})
|
|
145
|
+
)
|
|
146
|
+
)
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
As a concrete example, you can use this to disable streaming when generating static sites (SSG) with `<Suspense>`, by using the [`isSSGContext`](../../helpers/ssg.md#isssgcontext) helper:
|
|
150
|
+
|
|
151
|
+
```tsx
|
|
152
|
+
app.use(
|
|
153
|
+
'*',
|
|
154
|
+
jsxRenderer(
|
|
155
|
+
({ children }) => {
|
|
156
|
+
return (
|
|
157
|
+
<div>
|
|
158
|
+
<Suspense fallback={'loading...'}>
|
|
159
|
+
<Component />
|
|
160
|
+
</Suspense>
|
|
161
|
+
</div>
|
|
162
|
+
)
|
|
163
|
+
},
|
|
164
|
+
(c) => ({
|
|
165
|
+
stream: !isSSGContext(c),
|
|
166
|
+
})
|
|
167
|
+
)
|
|
168
|
+
)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Nested Layouts
|
|
172
|
+
|
|
173
|
+
The `Layout` component enables nesting the layouts.
|
|
174
|
+
|
|
175
|
+
```tsx
|
|
176
|
+
app.use(
|
|
177
|
+
jsxRenderer(({ children }) => {
|
|
178
|
+
return (
|
|
179
|
+
<html>
|
|
180
|
+
<body>{children}</body>
|
|
181
|
+
</html>
|
|
182
|
+
)
|
|
183
|
+
})
|
|
184
|
+
)
|
|
185
|
+
|
|
186
|
+
const blog = new Acryl()
|
|
187
|
+
blog.use(
|
|
188
|
+
jsxRenderer(({ children, Layout }) => {
|
|
189
|
+
return (
|
|
190
|
+
<Layout>
|
|
191
|
+
<nav>Blog Menu</nav>
|
|
192
|
+
<div>{children}</div>
|
|
193
|
+
</Layout>
|
|
194
|
+
)
|
|
195
|
+
})
|
|
196
|
+
)
|
|
197
|
+
|
|
198
|
+
app.route('/blog', blog)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## `useRequestContext()`
|
|
202
|
+
|
|
203
|
+
`useRequestContext()` returns an instance of Context.
|
|
204
|
+
|
|
205
|
+
```tsx
|
|
206
|
+
import { useRequestContext, jsxRenderer } from '@acryldev/blends/jsx-renderer'
|
|
207
|
+
|
|
208
|
+
const app = new Acryl()
|
|
209
|
+
app.use(jsxRenderer())
|
|
210
|
+
|
|
211
|
+
const RequestUrlBadge: FC = () => {
|
|
212
|
+
const c = useRequestContext()
|
|
213
|
+
return <b>{c.req.url}</b>
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
app.get('/page/info', (c) => {
|
|
217
|
+
return c.render(
|
|
218
|
+
<div>
|
|
219
|
+
You are accessing: <RequestUrlBadge />
|
|
220
|
+
</div>
|
|
221
|
+
)
|
|
222
|
+
})
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**Warning.**
|
|
226
|
+
|
|
227
|
+
You can't use `useRequestContext()` with a JSX option that precompiles the templates ahead of the build. Use `react-jsx`:
|
|
228
|
+
|
|
229
|
+
```json
|
|
230
|
+
"compilerOptions": {
|
|
231
|
+
"jsx": "react-jsx",
|
|
232
|
+
"jsxImportSource": "@acryldev/blends/jsx"
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
## Extending `ContextRenderer`
|
|
238
|
+
|
|
239
|
+
By defining `ContextRenderer` as shown below, you can pass additional content to the renderer. This is handy, for instance, when you want to change the contents of the head tag depending on the page.
|
|
240
|
+
|
|
241
|
+
```tsx
|
|
242
|
+
declare module '@acryldev/blends' {
|
|
243
|
+
interface ContextRenderer {
|
|
244
|
+
(
|
|
245
|
+
content: string | Promise<string>,
|
|
246
|
+
props: { title: string }
|
|
247
|
+
): Response
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
const app = new Acryl()
|
|
252
|
+
|
|
253
|
+
app.get(
|
|
254
|
+
'/page/*',
|
|
255
|
+
jsxRenderer(({ children, title }) => {
|
|
256
|
+
return (
|
|
257
|
+
<html>
|
|
258
|
+
<head>
|
|
259
|
+
<title>{title}</title>
|
|
260
|
+
</head>
|
|
261
|
+
<body>
|
|
262
|
+
<header>Menu</header>
|
|
263
|
+
<div>{children}</div>
|
|
264
|
+
</body>
|
|
265
|
+
</html>
|
|
266
|
+
)
|
|
267
|
+
})
|
|
268
|
+
)
|
|
269
|
+
|
|
270
|
+
app.get('/page/favorites', (c) => {
|
|
271
|
+
return c.render(
|
|
272
|
+
<div>
|
|
273
|
+
<ul>
|
|
274
|
+
<li>Eating sushi</li>
|
|
275
|
+
<li>Watching baseball games</li>
|
|
276
|
+
</ul>
|
|
277
|
+
</div>,
|
|
278
|
+
{
|
|
279
|
+
title: 'My favorites',
|
|
280
|
+
}
|
|
281
|
+
)
|
|
282
|
+
})
|
|
283
|
+
```
|