Skip to content

Commit fda61e3

Browse files
SaltyAomSaltyAom
committed
📘 doc: update html plugin
1 parent d7785d0 commit fda61e3

File tree

1 file changed

+90
-95
lines changed

1 file changed

+90
-95
lines changed

‎docs/plugins/html.md

Lines changed: 90 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -35,16 +35,57 @@ new Elysia()
3535
.get(
3636
'/html',
3737
() => `
38-
<html lang="en">
38+
<html lang='en'>
39+
<head>
40+
<title>Hello World</title>
41+
</head>
42+
<body>
43+
<h1>Hello World</h1>
44+
</body>
45+
</html>`
46+
)
47+
.get('/jsx', () => (
48+
<html lang='en'>
3949
<head>
4050
<title>Hello World</title>
4151
</head>
4252
<body>
4353
<h1>Hello World</h1>
4454
</body>
45-
</html> `
46-
)
47-
.get('/jsx', () => (
55+
</html>
56+
))
57+
.listen(3000)
58+
```
59+
60+
This plugin will automatically add `Content-Type: text/html; charset=utf8` header to the response, add `<!doctype html>` and convert it into a Response object.
61+
62+
## JSX
63+
Elysia HTML is based on [@kitajs/html](https://github.com/kitajs/html) allowing us to define JSX to string in compile time to archive high performance.
64+
65+
Name your file that need to use JSX to ends with affix **"x"**:
66+
- .js -> .jsx
67+
- .ts -> .tsx
68+
69+
To register TypeScript type, please appends the following to **tsconfig.json**:
70+
```jsonc
71+
// tsconfig.json
72+
{
73+
"compilerOptions": {
74+
"jsx": "react",
75+
"jsxFactory": "Html.createElement",
76+
"jsxFragmentFactory": "Html.Fragment"
77+
}
78+
}
79+
```
80+
81+
That's it, now you can JSX as your template engine:
82+
```tsx
83+
import { Elysia } from 'elysia'
84+
import { html } from '@elysiajs/html' // [!code ++]
85+
86+
new Elysia()
87+
.use(html()) // [!code ++]
88+
.get('/', () => (
4889
<html lang="en">
4990
<head>
5091
<title>Hello World</title>
@@ -54,10 +95,53 @@ new Elysia()
5495
</body>
5596
</html>
5697
))
57-
.listen(8080)
98+
.listen(3000)
5899
```
59100

60-
This plugin will automatically add `Content-Type: text/html; charset=utf8` header to the response, add `<!doctype html>` and convert it into a Response object.
101+
## XSS
102+
Elysia HTML is based use with Kita HTML plugin to detect possible XSS attack in compile time.
103+
104+
You can use a dedicated `safe` attribute to sanitize user value to prevent XSS vulnerability.
105+
```tsx
106+
import { Elysia, t } from 'elysia'
107+
import { html } from '@elysiajs/html'
108+
109+
new Elysia()
110+
.use(html())
111+
.post('/', ({ body }) => (
112+
<html lang="en">
113+
<head>
114+
<title>Hello World</title>
115+
</head>
116+
<body>
117+
<h1 safe>{body}</h1>
118+
</body>
119+
</html>
120+
), {
121+
body: t.String()
122+
})
123+
.listen(3000)
124+
```
125+
126+
However, when are building a large-scale app, it's best to have a type reminder to detect possible XSS vulnerability in your codebase.
127+
128+
To add a type-safe reminder, please install:
129+
```sh
130+
bun add @kitajs/ts-html-plugin
131+
```
132+
133+
Then appends the following **tsconfig.json
134+
```jsonc
135+
// tsconfig.json
136+
{
137+
"compilerOptions": {
138+
"jsx": "react",
139+
"jsxFactory": "Html.createElement",
140+
"jsxFragmentFactory": "Html.Fragment",
141+
"plugins": [{ "name": "@kitajs/ts-html-plugin" }]
142+
}
143+
}
144+
```
61145

62146
## Options
63147

@@ -100,92 +184,3 @@ app.get('/', ({ html }) => html('<html></html>'))
100184
The function used to detect if a string is a html or not. Default implementation if length is greater than 7, starts with `<` and ends with `>`.
101185

102186
Keep in mind there's no real way to validate HTML, so the default implementation is a best guess.
103-
104-
## Jsx
105-
106-
This plugin re-exports [@kitajs/html](https://github.com/kitajs/html), which is a JSX factory for creating HTML strings from JSX. **Please report JSX related issues to that repository.**
107-
108-
To use JSX, first rename your file extension to either `.tsx` or `.jsx`.
109-
110-
Then, install basic dependencies and add the following to your `tsconfig.json`:
111-
112-
```sh
113-
bun install @kitajs/html @kitajs/ts-html-plugin
114-
```
115-
116-
```jsonc
117-
// tsconfig.json
118-
119-
{
120-
"compilerOptions": {
121-
"jsx": "react",
122-
"jsxFactory": "Html.createElement",
123-
"jsxFragmentFactory": "Html.Fragment",
124-
"plugins": [{ "name": "@kitajs/ts-html-plugin" }]
125-
}
126-
}
127-
```
128-
129-
Then, you can simply use the JSX syntax to create HTML strings:
130-
131-
```tsx
132-
// app.tsx
133-
134-
import { Elysia } from 'elysia'
135-
import { html } from '@elysiajs/html'
136-
137-
new Elysia()
138-
.use(html())
139-
.get('/', () => (
140-
<html lang="en">
141-
<head>
142-
<title>Hello World</title>
143-
</head>
144-
<body>
145-
<h1>Hello World</h1>
146-
</body>
147-
</html>
148-
))
149-
.listen(8080)
150-
```
151-
152-
and that's it! 🎉
153-
154-
You can now use JSX to define your web page and Elysia will turns them to HTML automatically.
155-
156-
::: warning
157-
Learn how to [sanitize](https://github.com/kitajs/html#sanitization) and avoid xss vulnerabilities in your code!
158-
:::
159-
160-
::: tip
161-
162-
new Elysia()
163-
.get('/unsafe', ({ sanitize }) => (
164-
<h1>{sanitize(malicious)}</h1>
165-
))
166-
.listen(8080)
167-
```
168-
169-
Read more about JSX in the [official documentation](https://github.com/kitajs/html) and learn how to add HTMX typings, compiling html, adding more JSX components and so on...
170-
171-
:::
172-
173-
## Sanitization
174-
175-
To keep this section up to date, please refer to the [sanitization](https://github.com/kitajs/html/tree/master#sanitization) section of the `@kitajs/html` repository.
176-
177-
## Manual handler
178-
179-
We recommend relying on automatic responses, but you can optionally disable `autoDetect` and explicitly only use the `html` function.
180-
181-
```ts
182-
import { Elysia } from 'elysia'
183-
import { html } from '@elysiajs/html'
184-
185-
const page = '<html>My Html</html>'
186-
187-
new Elysia()
188-
.use(html({ autoDetect: false }))
189-
.get('/', ({ html }) => html(page))
190-
.listen(8080)
191-
```

0 commit comments

Comments
 (0)