Skip to content

Commit 8d13709

Browse files
iamshanvyiamshanvy
committed
Merge remote-tracking branch 'upstream/main'
2 parents ce90f57 + 855de65 commit 8d13709

File tree

1 file changed

+108
-72
lines changed

1 file changed

+108
-72
lines changed

‎docs/plugins/html.md

Lines changed: 108 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -15,59 +15,122 @@ 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
96+
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+
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+
```
46115
47-
## JSX
48-
Starting from HTML plugin > 0.6.1, you can directly use JSX to create, and return HTML automatically.
116+
```jsonc
117+
// tsconfig.json
49118

50-
### Setup
51-
To utilize JSX, modify the tsconfig.json as the following:
52-
```json
53119
{
54-
"compilerOptions": {
55-
"jsx": "react",
56-
"jsxFactory": "ElysiaJSX",
57-
"jsxFragmentFactory": "ElysiaJSX.Fragment",
58-
"types": [
59-
"bun-types"
60-
]
61-
}
120+
"compilerOptions": {
121+
"jsx": "react",
122+
"jsxFactory": "Html.createElement",
123+
"jsxFragmentFactory": "Html.Fragment",
124+
"plugins": [{ "name": "@kitajs/ts-html-plugin" }]
125+
}
62126
}
63127
```
64128
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.
129+
Then, you can simply use the JSX syntax to create HTML strings:
68130
69131
```tsx
70132
// app.tsx
133+
71134
import { Elysia } from 'elysia'
72135
import { html } from '@elysiajs/html'
73136

@@ -86,63 +149,36 @@ new Elysia()
86149
.listen(8080)
87150
```
88151
89-
::: tip
90-
To use JSX, don't forget to rename your file extension to either `.tsx` or `.jsx`
91-
:::
152+
and that's it! 🎉
92153
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>`
154+
You can now use JSX to define your web page and Elysia will turns them to HTML automatically.
97155
98-
new Elysia()
99-
.get('/unsafe', () => (
100-
<h1 safe>{malicious}</h1>
101-
))
102-
.listen(8080)
103-
```
156+
::: warning
157+
Learn how to [sanitize](https://github.com/kitajs/html#sanitization) and avoid xss vulnerabilities in your code!
158+
:::
104159
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>`
160+
::: tip
108161
109-
new Elysia()
110-
.get('/unsafe', ({ sanitize }) => (
111-
<h1>{sanitize(malicious)}</h1>
112-
))
113-
.listen(8080)
114-
```
115-
```
162+
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...
116163
117-
## Handler
118-
Below are the value added to the handler.
164+
:::
119165
120-
### html
121-
A function that converts string to `Response` with `Content-Type: text/html; charset=utf8` header.
166+
## Sanitization
122167
123-
Type:
124-
```typescript
125-
html(value: string) => Response
126-
```
168+
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.
127169
128-
#### Example:
129-
Although we recommended relying on automatic response, but you can optionally you can return explictly return any string with HTML header.
170+
## Manual handler
130171
131-
```typescript
172+
We recommend relying on automatic responses, but you can optionally disable `autoDetect` and explicitly only use the `html` function.
173+
174+
```ts
132175
import { Elysia } from 'elysia'
133176
import { html } from '@elysiajs/html'
134177

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>`
178+
const page = '<html>My Html</html>'
143179

144180
new Elysia()
145-
.use(html())
181+
.use(html({ autoDetect: false }))
146182
.get('/', ({ html }) => html(page))
147183
.listen(8080)
148184
```

0 commit comments

Comments
 (0)