Skip to content

Commit ef46f4c

Browse files
arthurfiorettearthurfiorette
committed
docs
1 parent 4b5dcd5 commit ef46f4c

File tree

1 file changed

+106
-75
lines changed

1 file changed

+106
-75
lines changed

‎docs/plugins/html.md

Lines changed: 106 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -15,59 +15,127 @@ head:
1515
---
1616

1717
# HTML Plugin
18-
Return [**JSX**](#jsx), and HTML with proper HTML headers automatically
18+
19+
Allows you to use [JSX](#jsx) and HTML with proper headers and support.
1920

2021
Install with:
22+
2123
```bash
2224
bun add @elysiajs/html
2325
```
2426

2527
Then use it:
26-
```typescript
28+
29+
```tsx
2730
import { Elysia } from 'elysia'
2831
import { html } from '@elysiajs/html'
2932

30-
const page = `<html lang="en">
31-
<head>
32-
<title>Hello World</title>
33-
</head>
34-
<body>
35-
<h1>Hello World</h1>
36-
</body>
37-
</html>`
38-
3933
new Elysia()
4034
.use(html())
41-
.get('/', () => page)
35+
.get(
36+
'/html',
37+
() => `
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">
49+
<head>
50+
<title>Hello World</title>
51+
</head>
52+
<body>
53+
<h1>Hello World</h1>
54+
</body>
55+
</html>
56+
))
4257
.listen(8080)
4358
```
4459

45-
If any html tag is returned, response will be treat as HTML response automatically
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+
## Options
63+
64+
### contentType
65+
66+
- Type: `string`
67+
- Default: `'text/html; charset=utf8'`
68+
69+
The content-type of the response.
70+
71+
### autoDetect
72+
73+
- Type: `boolean`
74+
- Default: `true`
75+
76+
Whether to automatically detect HTML content and set the content-type.
77+
78+
### autoDoctype
79+
80+
- Type: `boolean | 'full'`
81+
- Default: `true`
82+
83+
Whether to automatically add `<!doctype html>` to a response starting with `<html>`, if not found.
84+
85+
Use `full` to also automatically add doctypes on responses returned without this plugin
86+
87+
```ts
88+
// without the plugin
89+
app.get('/', () => '<html></html>')
90+
91+
// With the plugin
92+
app.get('/', ({ html }) => html('<html></html>')
93+
```
94+
95+
### isHtml
4696
47-
## JSX
48-
Starting from HTML plugin > 0.6.1, you can directly use JSX to create, and return HTML automatically.
97+
- Type: `(value: string) => boolean`
98+
- Default: `isHtml` (exported function)
99+
100+
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 `>`.
101+
102+
Keep in mind there's no real way to validate HTML, so the default implementation is a best guess.
103+
104+
## Jsx
105+
106+
<br />
107+
108+
::: warning
109+
110+
# Learn how to [sanitize](https://github.com/kitajs/html#sanitization) and avoid xss vulnerabilities in your code!
111+
112+
:::
113+
114+
<br />
115+
116+
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.
117+
118+
To use JSX, first rename your file extension to either `.tsx` or `.jsx`.
119+
120+
Then, add the following to your `tsconfig.json`:
121+
122+
```jsonc
123+
// tsconfig.json
49124

50-
### Setup
51-
To utilize JSX, modify the tsconfig.json as the following:
52-
```json
53125
{
54-
"compilerOptions": {
55-
"jsx": "react",
56-
"jsxFactory": "ElysiaJSX",
57-
"jsxFragmentFactory": "ElysiaJSX.Fragment",
58-
"types": [
59-
"bun-types"
60-
]
61-
}
126+
"compilerOptions": {
127+
"jsx": "react",
128+
"jsxFactory": "Html.createElement",
129+
"jsxFragmentFactory": "Html.Fragment"
130+
}
62131
}
63132
```
64133
65-
and that's it! 🎉
66-
67-
You can now use JSX to define your web page and Elysia will turns them to HTML automatically.
134+
Then, you can simply use the JSX syntax to create HTML strings:
68135
69136
```tsx
70137
// app.tsx
138+
71139
import { Elysia } from 'elysia'
72140
import { html } from '@elysiajs/html'
73141

@@ -86,63 +154,26 @@ new Elysia()
86154
.listen(8080)
87155
```
88156
89-
::: tip
90-
To use JSX, don't forget to rename your file extension to either `.tsx` or `.jsx`
91-
:::
92-
93-
## Sanitize HTML
94-
If you are using JSX, you can use `safe` attribute to sanitize unsafe value
95-
```tsx
96-
const malicious = `<script>alert("Hello")</script>`
97-
98-
new Elysia()
99-
.get('/unsafe', () => (
100-
<h1 safe>{malicious}</h1>
101-
))
102-
.listen(8080)
103-
```
104-
105-
Otherwise you can use a decorated `sanitize` function decorated in `Context` to explicitly sanitize the value.
106-
```tsx
107-
const malicious = `<script>alert("Hello")</script>`
157+
and that's it! 🎉
108158
109-
new Elysia()
110-
.get('/unsafe', ({ sanitize }) => (
111-
<h1>{sanitize(malicious)}</h1>
112-
))
113-
.listen(8080)
114-
```
115-
```
159+
You can now use JSX to define your web page and Elysia will turns them to HTML automatically.
116160
117-
## Handler
118-
Below are the value added to the handler.
161+
## Sanitization
119162
120-
### html
121-
A function that converts string to `Response` with `Content-Type: text/html; charset=utf8` header.
163+
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.
122164
123-
Type:
124-
```typescript
125-
html(value: string) => Response
126-
```
165+
## Manual handler
127166
128-
#### Example:
129-
Although we recommended relying on automatic response, but you can optionally you can return explictly return any string with HTML header.
167+
We recommend relying on automatic responses, but you can optionally disable `autoDetect` and explicitly only use the `html` function.
130168
131-
```typescript
169+
```ts
132170
import { Elysia } from 'elysia'
133171
import { html } from '@elysiajs/html'
134172

135-
const page = `<html lang="en">
136-
<head>
137-
<title>Hello World</title>
138-
</head>
139-
<body>
140-
<h1>Hello World</h1>
141-
</body>
142-
</html>`
173+
const page = '<html>My Html</html>'
143174

144175
new Elysia()
145-
.use(html())
176+
.use(html({ autoDetect: false }))
146177
.get('/', ({ html }) => html(page))
147178
.listen(8080)
148179
```

0 commit comments

Comments
 (0)