Skip to content

Commit 6d928a5

Browse files
SaltyAomSaltyAom
authored
Merge pull request #106 from arthurfiorette/main
Updated documentation for @elysiajs/html.
2 parents 4b5dcd5 + 549e8a4 commit 6d928a5

File tree

1 file changed

+114
-72
lines changed

1 file changed

+114
-72
lines changed

‎docs/plugins/html.md

Lines changed: 114 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -15,59 +15,132 @@ 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)
4699
47-
## JSX
48-
Starting from HTML plugin > 0.6.1, you can directly use JSX to create, and return HTML automatically.
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, install basic dependencies and add the following to your `tsconfig.json`:
121+
122+
```sh
123+
bun install @kitajs/html @kitajs/ts-html-plugin
124+
```
125+
126+
```jsonc
127+
// tsconfig.json
49128

50-
### Setup
51-
To utilize JSX, modify the tsconfig.json as the following:
52-
```json
53129
{
54-
"compilerOptions": {
55-
"jsx": "react",
56-
"jsxFactory": "ElysiaJSX",
57-
"jsxFragmentFactory": "ElysiaJSX.Fragment",
58-
"types": [
59-
"bun-types"
60-
]
61-
}
130+
"compilerOptions": {
131+
"jsx": "react",
132+
"jsxFactory": "Html.createElement",
133+
"jsxFragmentFactory": "Html.Fragment",
134+
"plugins": [{ "name": "@kitajs/ts-html-plugin" }]
135+
}
62136
}
63137
```
64138
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.
139+
Then, you can simply use the JSX syntax to create HTML strings:
68140
69141
```tsx
70142
// app.tsx
143+
71144
import { Elysia } from 'elysia'
72145
import { html } from '@elysiajs/html'
73146

@@ -86,63 +159,32 @@ new Elysia()
86159
.listen(8080)
87160
```
88161
89-
::: tip
90-
To use JSX, don't forget to rename your file extension to either `.tsx` or `.jsx`
91-
:::
162+
and that's it! 🎉
92163
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>`
164+
You can now use JSX to define your web page and Elysia will turns them to HTML automatically.
97165
98-
new Elysia()
99-
.get('/unsafe', () => (
100-
<h1 safe>{malicious}</h1>
101-
))
102-
.listen(8080)
103-
```
166+
::: tip
104167
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>`
168+
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...
108169
109-
new Elysia()
110-
.get('/unsafe', ({ sanitize }) => (
111-
<h1>{sanitize(malicious)}</h1>
112-
))
113-
.listen(8080)
114-
```
115-
```
170+
:::
116171
117-
## Handler
118-
Below are the value added to the handler.
172+
## Sanitization
119173
120-
### html
121-
A function that converts string to `Response` with `Content-Type: text/html; charset=utf8` header.
174+
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.
122175
123-
Type:
124-
```typescript
125-
html(value: string) => Response
126-
```
176+
## Manual handler
127177
128-
#### Example:
129-
Although we recommended relying on automatic response, but you can optionally you can return explictly return any string with HTML header.
178+
We recommend relying on automatic responses, but you can optionally disable `autoDetect` and explicitly only use the `html` function.
130179
131-
```typescript
180+
```ts
132181
import { Elysia } from 'elysia'
133182
import { html } from '@elysiajs/html'
134183

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

144186
new Elysia()
145-
.use(html())
187+
.use(html({ autoDetect: false }))
146188
.get('/', ({ html }) => html(page))
147189
.listen(8080)
148190
```

0 commit comments

Comments
 (0)