Skip to content

Commit

Permalink
docs: update with example using tsconfig jsxImportSource
Browse files Browse the repository at this point in the history
  • Loading branch information
JacopoPatroclo committed Feb 18, 2024
1 parent 22afadf commit fd9a819
Showing 1 changed file with 27 additions and 15 deletions.
42 changes: 27 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
<h1>🏛️ KitaJS Html</h1>

<p align="center">
<code>@kitajs/html</code> is a <a href="#performance">super fast</a> JSX runtime to generate HTML strings that works everywhere.
<code>@kitajs/html</code> is a <a href="#performance">super fast</a> JSX runtime to generate HTML strings that works everywhere.
<br /><i><a href="https://expressjs.com">Express</a>? <a href="https://fastify.dev">Fastify</a>? <a href="https://hono.dev">Hono</a>? <a href="https://bun.sh">Bun</a>? <a href="https://htmx.org/">Htmx</a>?</i>
<br /><br /><b>If your code works with strings, we got you covered.</b>
<br />
Expand Down Expand Up @@ -105,6 +105,21 @@ To use the `@kitajs/html` package, follow these steps:
}
```

or you can choose to auto import the jsx runtime by setting the `jsxImportSource` like
this:

```jsonc
// tsconfig.json

{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "@kitajs/html",
"plugins": [{ "name": "@kitajs/ts-html-plugin" }]
}
}
```

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
Expand Down Expand Up @@ -167,7 +182,8 @@ to generate HTML. Here are two options for importing the `@kitajs/html` package:
```

2. **Use the register to add a global namespace**: Import the `register` to globally
register all necessary functions for convenience.
register all necessary functions for convenience. You don't need to do that if you are
using the `jsxImportSource` option in your `tsconfig.json`.

```tsx
// Import the register to globally register all needed functions
Expand All @@ -191,10 +207,9 @@ issues in your code editor and enhance your code's security.

<br />

> [!IMPORTANT]
> Please utilize our `@kitajs/ts-html-plugin` to emit TypeScript errors wherever you are
> exposed to XSS. Refer to [Getting Started](#getting-started) for installation
> instructions.
> [!IMPORTANT] Please utilize our `@kitajs/ts-html-plugin` to emit TypeScript errors
> wherever you are exposed to XSS. Refer to [Getting Started](#getting-started) for
> installation instructions.
<br />

Expand Down Expand Up @@ -373,8 +388,7 @@ const html = renderToStream(renderUserPage);

<br />

> [!NOTE]
> The `renderToStream()` is returns a native node/bun stream, head over to our
> [!NOTE] The `renderToStream()` is returns a native node/bun stream, head over to our
> [suspense-server](examples/suspense-server.tsx) example to see how to use it with
> node:http, Express or Fastify servers.
Expand Down Expand Up @@ -485,10 +499,9 @@ error is thrown.

<br />

> [!NOTE]
> Until [#14729](https://github.com/microsoft/TypeScript/issues/14729) gets implemented,
> you need to manually cast `JSX.Element` into strings if you are sure there is no inner
> async components in your component tree.
> [!NOTE] Until [#14729](https://github.com/microsoft/TypeScript/issues/14729) gets
> implemented, you need to manually cast `JSX.Element` into strings if you are sure there
> is no inner async components in your component tree.
<br />

Expand Down Expand Up @@ -678,9 +691,8 @@ component. This does not support unclean components / props processing.

<br />

> [!WARNING]
> This feature is a special use case for rendering **entire page templates** like what you
> would do with handlebars or nunjucks.
> [!WARNING] This feature is a special use case for rendering **entire page templates**
> like what you would do with handlebars or nunjucks.
>
> It does not works with mostly JSX components and, for small components,
> [it will be slower than the normal](benchmark.md) JSX syntax.
Expand Down

0 comments on commit fd9a819

Please sign in to comment.