Skip to content

Commit

Permalink
docs: updated readme urls
Browse files Browse the repository at this point in the history
  • Loading branch information
@arthurfiorette
arthurfiorette committed Mar 10, 2024
1 parent 9b324af commit e5f84ba
Show file tree
Hide file tree
Showing 3 changed files with 51 additions and 106 deletions.
121 changes: 32 additions & 89 deletions packages/fastify-html-plugin/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@
<br />

<div align="center">
<a title="MIT license" target="_blank" href="https://github.com/kitajs/fastify-html-plugin/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/kitajs/fastify-html-plugin"></a>
<a title="MIT license" target="_blank" href="https://github.com/kitajs/html/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/kitajs/html"></a>
<a title="NPM Package" target="_blank" href="https://www.npmjs.com/package/@kitajs/fastify-html-plugin"><img alt="Downloads" src="https://img.shields.io/npm/dw/@kitajs/fastify-html-plugin?style=flat"></a>
<a title="Bundle size" target="_blank" href="https://bundlephobia.com/package/@kitajs/fastify-html-plugin@latest"><img alt="Bundlephobia" src="https://img.shields.io/bundlephobia/minzip/@kitajs/fastify-html-plugin/latest?style=flat"></a>
<a title="Last Commit" target="_blank" href="https://github.com/kitajs/fastify-html-plugin/commits/master"><img alt="Last commit" src="https://img.shields.io/github/last-commit/kitajs/fastify-html-plugin"></a>
<a href="https://github.com/kitajs/fastify-html-plugin/stargazers"><img src="https://img.shields.io/github/stars/kitajs/fastify-html-plugin?logo=github&label=Stars" alt="Stars"></a>
<a title="Last Commit" target="_blank" href="https://github.com/kitajs/html/commits/master"><img alt="Last commit" src="https://img.shields.io/github/last-commit/kitajs/html"></a>
<a href="https://github.com/kitajs/html/stargazers"><img src="https://img.shields.io/github/stars/kitajs/html?logo=github&label=Stars" alt="Stars"></a>
</div>

<br />
Expand All @@ -44,8 +44,6 @@
- [Documentation](#documentation)
- [API](#api)
- [`reply.html()`](#replyhtml)
- [`reply.streamHtml()`](#replystreamhtml)
- [`reply.setupHtmlStream()`](#replysetuphtmlstream)
- [License](#license)

<br />
Expand Down Expand Up @@ -86,12 +84,9 @@ app.register(kitaHtmlPlugin);
Every option is well documented through their respective JSDoc comments, below are the
default options.

| Name | Description | Default |
| ------------- | ------------------------------------------------------------------------------------------------- | --------------------------- |
| `contentType` | The value of the `Content-Type` header. | `'text/html; charset=utf8'` |
| `autoDetect` | Whether to automatically detect HTML content and set the content-type when `.html()` is not used. | `true` |
| `autoDoctype` | Whether to automatically add `<!doctype html>` to a response starting with <html>, if not found. | `true` |
| `isHtml` | The function used to detect if a string is a html or not when `autoDetect` is enabled. | [isHtml](./lib/is-html.js) |
| Name | Description | Default |
| ------------- | ------------------------------------------------------------------------------------------------ | ------- |
| `autoDoctype` | Whether to automatically add `<!doctype html>` to a response starting with <html>, if not found. | `true` |

<br />

Expand All @@ -103,7 +98,8 @@ for this use case.

- Read [`@kitajs/html` documentation](https://github.com/kitajs/html) for help with
templating, and all other stuff related to `<jsx />`.
- Read [`@kitajs/ts-html-plugin` documentation.](https://github.com/kitajs/ts-html-plugin)
- Read
[`@kitajs/ts-html-plugin` documentation.](https://github.com/kitajs/html/tree/master/packages/ts-html-plugin)
for help setting up the **XSS** detector and IDE intellisense.

<br />
Expand All @@ -112,94 +108,41 @@ for this use case.

### `reply.html()`

**Synchronously** waits for the component tree to resolve and sends it at once to the
browser.
Sends the html to the browser. This method supports all types of components, including
`<Suspense />` and `<ErrorBoundary />`.

This method does not support the usage of `<Suspense />`, please use `streamHtml` instead.
The entire component tree will be awaited before being sent to the browser as a single
piece.

If the HTML does not start with a doctype and `opts.autoDoctype` is enabled, it will be
added automatically.

The correct `Content-Type` header will also be defined.

```tsx
app.get('/', (req, reply) =>
reply.html(
<html lang="en">
<body>
<h1>Hello, world!</h1>
</body>
</html>
)
);
```

### `reply.streamHtml()`

Sends the html to the browser as a single stream, the entire component tree will be waited
synchronously. When using any `Suspense`, its fallback will be synchronously waited and
sent to the browser in the original stream, as its children are resolved, new pieces of
html will be sent to the browser. When all `Suspense`s pending promises are resolved, the
When Suspense components are found, their fallback will be synchronously awaited and sent
to the browser in the original stream, as its children are resolved, new pieces of html
will be sent to the browser. When all `Suspense`s pending promises are resolved, the
connection is closed normally.

> [!NOTE]
> `request.id` must be used as the `Suspense`'s `rid` parameter
This method hijacks the response, as the html stream is just a single continuous stream in
the http body, any changes to the status code or headers after calling this method **will
not have effect**.
> `req.id` must be used as the `Suspense`'s `rid` parameter
If the HTML does not start with a doctype and `opts.autoDoctype` is enabled, it will be
added automatically. The correct `Content-Type` header will also be defined.

**Http trailers are not yet supported when using `streamHtml`**

```tsx
app.get('/', (req, reply) =>
reply.streamHtml(
<Suspense rid={req.id} fallback={<div>Loading...</div>}>
<MyAsyncComponent />
</Suspense>
app
.get('/html', (req, reply) =>
reply.html(
<html lang="en">
<body>
<h1>Hello, world!</h1>
</body>
</html>
)
)
);
```

### `reply.setupHtmlStream()`

This function is called internally by the `streamHtml` getter.

> [!NOTE]
> Executing code before sending the response and after creating your html is a bad pattern
> and should be avoided!
This function must be called **manually** at the top of the route handler when you have to
execute some code **after** your root layout and **before** the `streamHtml call.

If `setupHtmlStream` is executed and no call to `streamHtml` happens before the request
finishes, a memory leak will be created. Make sure that `setupHtmlStream` will never be
executed without being followed by `streamHtml`.

```tsx
app.get('/bad', (_, reply) => {
const html = <Layout />; // Error: Request data was deleted before all
// suspense components were resolved.

// code that must be executed after the template
foo();

return reply.streamHtml(html);
});

app.get('/good', (_, reply) => {
reply.setupHtmlStream();

const html = <Layout />; // works!

// code that must be executed after the template
foo();

return reply.streamHtml(html);
});
.get('/stream', (req, reply) =>
reply.html(
<Suspense rid={req.id} fallback={<div>Loading...</div>}>
<MyAsyncComponent />
</Suspense>
)
);
```

<br />
Expand Down
30 changes: 16 additions & 14 deletions packages/html/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,11 +109,11 @@ To use the `@kitajs/html` package, follow these steps:
```

3. Append the
[`xss-scan`](https://github.com/kitajs/ts-html-plugin/tree/main#running-as-cli) command
into your test script. This CLI comes from @kitajs/ts-html-plugin, which catches XSS
vulnerabilities that may be introduced into your codebase, automating the xss scanning
process to run everytime you test your code, like inside your CI/CD environment. Open
your `package.json` file and add the following script:
[`xss-scan`](https://github.com/kitajs/html/tree/master/packages/ts-html-plugin/tree/main#running-as-cli)
command into your test script. This CLI comes from @kitajs/ts-html-plugin, which
catches XSS vulnerabilities that may be introduced into your codebase, automating the
xss scanning process to run everytime you test your code, like inside your CI/CD
environment. Open your `package.json` file and add the following script:

```jsonc
// package.json
Expand Down Expand Up @@ -147,9 +147,9 @@ To use the `@kitajs/html` package, follow these steps:
>
> Try writing `console.log(<div>{String.name}</div>);` in your editor. If it **THROWS** a
> `XSS` error, then your setup is correct. Refer to the
> [@kitajs/ts-html-plugin](https://github.com/kitajs/ts-html-plugin) repository for more
> details on setting up editor intellisense. _(It should throw, as `String.name` has a
> type of `string`, type which may or may not have special caracters)_
> [@kitajs/ts-html-plugin](https://github.com/kitajs/html/tree/master/packages/ts-html-plugin)
> repository for more details on setting up editor intellisense. _(It should throw, as
> `String.name` has a type of `string`, type which may or may not have special caracters)_
<br />
<br />
Expand All @@ -173,8 +173,9 @@ Always use the `safe` attribute or manually call `Html.escapeHtml` to protect ag
vulnerabilities when rendering user input.

Ensuring XSS prevention is vital to guarantee your application's security. You can employ
the [`@kitajs/ts-html-plugin`](https://github.com/kitajs/ts-html-plugin) to catch XSS
issues in your code editor and enhance your code's security.
the
[`@kitajs/ts-html-plugin`](https://github.com/kitajs/html/tree/master/packages/ts-html-plugin)
to catch XSS issues in your code editor and enhance your code's security.

<br />

Expand Down Expand Up @@ -267,17 +268,18 @@ where it's needed.
## Editor Intellisense and CLI tool

<p align="center">
<img align="center" src="https://github.com/kitajs/ts-html-plugin/blob/main/assets/preview.png?raw=true" alt="Example of an error thrown by @kitajs/ts-html-plugin." width="75%" />
<img align="center" src="https://github.com/kitajs/html/tree/master/packages/ts-html-plugin/blob/main/assets/preview.png?raw=true" alt="Example of an error thrown by @kitajs/ts-html-plugin." width="75%" />
</p>

<h2>⚠️</h2>

**Note:** This section has been relocated to the
[@kitajs/ts-html-plugin](https://github.com/kitajs/ts-html-plugin) repository.
[@kitajs/ts-html-plugin](https://github.com/kitajs/html/tree/master/packages/ts-html-plugin)
repository.

Please consult their
"[Getting Started](https://github.com/kitajs/ts-html-plugin#getting-started)" section for
instructions on enabling editor IntelliSense and using the CLI tool.
"[Getting Started](https://github.com/kitajs/html/tree/master/packages/ts-html-plugin#getting-started)"
section for instructions on enabling editor IntelliSense and using the CLI tool.

<br />
<br />
Expand Down
6 changes: 3 additions & 3 deletions packages/ts-html-plugin/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@
<br />

<div align="center">
<a title="MIT license" target="_blank" href="https://github.com/kitajs/ts-html-plugin/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/kitajs/ts-html-plugin"></a>
<a title="MIT license" target="_blank" href="https://github.com/kitajs/html/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/kitajs/html"></a>
<a title="NPM Package" target="_blank" href="https://www.npmjs.com/package/@kitajs/ts-html-plugin"><img alt="Downloads" src="https://img.shields.io/npm/dw/@kitajs/ts-html-plugin?style=flat"></a>
<a title="Bundle size" target="_blank" href="https://bundlephobia.com/package/@kitajs/ts-html-plugin@latest"><img alt="Bundlephobia" src="https://img.shields.io/bundlephobia/minzip/@kitajs/ts-html-plugin/latest?style=flat"></a>
<a title="Last Commit" target="_blank" href="https://github.com/kitajs/ts-html-plugin/commits/master"><img alt="Last commit" src="https://img.shields.io/github/last-commit/kitajs/ts-html-plugin"></a>
<a href="https://github.com/kitajs/ts-html-plugin/stargazers"><img src="https://img.shields.io/github/stars/kitajs/ts-html-plugin?logo=github&label=Stars" alt="Stars"></a>
<a title="Last Commit" target="_blank" href="https://github.com/kitajs/html/commits/master"><img alt="Last commit" src="https://img.shields.io/github/last-commit/kitajs/html"></a>
<a href="https://github.com/kitajs/html/stargazers"><img src="https://img.shields.io/github/stars/kitajs/html?logo=github&label=Stars" alt="Stars"></a>
</div>

<br />
Expand Down

0 comments on commit e5f84ba

Please sign in to comment.