---
url: /guide/introduction.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# What is Kita Html

Kita Html is a JSX runtime where every element evaluates to a string. Where React's
`<div />` produces a virtual DOM node that must be reconciled and serialized, Kita Html's
`<div />` returns `'<div></div>'` directly. There is no intermediate representation, no
diffing step, and no serialization pass. The JSX you write compiles to function calls that
concatenate strings.

This architecture makes Kita Html significantly faster than virtual DOM-based renderers
for any scenario where the output is an HTML string: server-side rendering, static site
generation, email templates, HTMX applications, or any HTTP handler that sends HTML over
the wire.

[Go to getting started](/guide/getting-started.md)

## Performance through simplicity

A virtual DOM renderer performs three operations per render cycle: it constructs an object
tree, diffs it against the previous tree, and serializes the result to a string. Kita Html
skips all three. The TypeScript compiler rewrites JSX expressions into `jsx()` and
`jsxs()` function calls at build time. At runtime, those functions concatenate attribute
strings and child strings into a single result. The output is the final HTML with no
post-processing.

```tsx twoslash kita
import { jsx as __jsx } from '@kitajs/html/jsx-runtime'
const username: string = 'Username'
export let html: JSX.Element

// ---cut---
// What you write
html = (
  <div class="card">
    <h1 safe>{username}</h1>
  </div>
)

// What TypeScript compiles to
html = __jsx('div', {
  class: 'card',
  children: __jsx('h1', {
    safe: true,
    children: username
  })
})

// Click on the <> icon in the top right to see the compiled output
```

This directness is why Kita Html benchmarks 7-40x faster than React's `renderToString`
across real-world component trees. The runtime has zero dependencies beyond TypeScript
itself.

[Read more about how JSX becomes HTML](/guide/how-jsx-becomes-html.md)

## XSS protection

Because `JSX.Element` is a `string`, the runtime cannot distinguish between HTML produced
by a component and raw user input injected as a child. Children are not escaped by
default. This is a deliberate trade-off for performance and composability, and it is fully
addressed by three layers of protection that work together to make accidental XSS
practically impossible.

The `safe` attribute escapes children at render time. Adding it to any native element
causes the runtime to pass all children through HTML entity escaping before concatenation.

```tsx twoslash kita
// @noErrors
let userInput = `<script>alert('XSS')</script>` as const
// ---cut---
const html = <div safe>{userInput}</div>
//                        ^?
```

A TypeScript language service plugin analyzes every JSX expression in your editor and
flags any child whose type could carry unescaped HTML. The same analysis runs as a CLI
tool [`xss-scan`](/guide/xss/scanner-cli.md) in CI/CD pipelines, failing the build on any
finding. Between the editor diagnostics and the CI gate, unsafe expressions are caught
before they reach production.

**The only way to ship XSS-vulnerable code is to explicitly suppress the warnings.**

[Read more about the XSS protection system](/guide/xss/safe-attribute.md)

## Async components and Suspense

Kita Html supports async components natively. Any function component that returns a
`Promise<string>` is valid JSX. When an async child appears anywhere in the tree, the
entire parent chain becomes a `Promise<string>` through automatic propagation.

```tsx twoslash kita
const db = {
  async getUser(id: string) {
    return { name: 'Arthur' }
  }
}
// ---cut---
async function UserCard({ id }: { id: string }) {
  const user = await db.getUser(id)
  return <div safe>{user.name}</div>
}

// The result is a Promise<string> because UserCard is async,
// Type still is JSX.Element so it can be used in JSX
const html = <UserCard id="123" />
```

For streaming scenarios, the Suspense component renders a fallback immediately and
replaces it with the resolved content as each async subtree completes. This uses HTTP
chunked transfer encoding to stream updates to the client without waiting for the entire
page to resolve. A small inline script handles the client-side DOM replacement.

```tsx twoslash kita=stream
import { Suspense, renderToStream } from '@kitajs/html/suspense'
async function UserCard({ id }: { id: string }) {
  return <div>Async Component</div>
}
// ---cut---
const stream = renderToStream((rid) => (
  <Suspense rid={rid} fallback={<div>Loading...</div>}>
    <UserCard id="123" />
  </Suspense>
))

// Pipe the stream to your HTTP response or use one of our integrations.
```

Each Suspense boundary operates independently, so fast components appear instantly while
slow ones show their fallback. The `rid` parameter ties each Suspense instance to a
specific request for safe concurrent rendering.

- [Read more about Suspense streaming](/guide/async/async-components.md)

## Packages

As of now, Kita Html is composed of two main packages:

- `@kitajs/html` is the core runtime that compiles JSX to strings and provides Suspense
  streaming.
- `@kitajs/ts-html-plugin` is the TypeScript plugin and CLI scanner for XSS detection.

Official [framework integrations](/integrations/overview.md) are available for Fastify,
Elysia, and others. The core runtime works with any framework that accepts strings.

- [Read more about the packages and integrations](/integrations/overview.md)



---
url: /guide/getting-started.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Getting Started

Install `@kitajs/html` and `@kitajs/ts-html-plugin` together. The first is the JSX
runtime; the second provides editor diagnostics and the `xss-scan` CLI for catching XSS at
compile time.


```sh [npm]
npm i @kitajs/html@next @kitajs/ts-html-plugin@next
```

```sh [yarn]
yarn add @kitajs/html@next @kitajs/ts-html-plugin@next
```

```sh [pnpm]
pnpm add @kitajs/html@next @kitajs/ts-html-plugin@next
```

```sh [bun]
bun add @kitajs/html@next @kitajs/ts-html-plugin@next
```

## TypeScript configuration

Add the following to your `tsconfig.json`. The `jsx` and `jsxImportSource` fields tell
TypeScript to compile JSX using the Kita Html runtime. The `plugins` entry activates the
XSS detection plugin in your editor.

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

If your editor uses a globally installed TypeScript version instead of the project's local
copy, the plugin will not load. In VS Code, configure the workspace to use the local
TypeScript:

```json title=".vscode/settings.json"
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}
```

## XSS scanner

Add `xss-scan` to your test script so it runs in CI alongside your tests. The CLI performs
the same XSS analysis as the editor plugin, but against your entire codebase.

```json title="package.json"
{
  "scripts": {
    "test": "xss-scan && vitest"
  }
}
```

## Verification

Write the following in a `.tsx` file:

```tsx twoslash
// @errors: 88601
console.log(<div>{String.name}</div>)
```

Your editor should show an XSS error on `String.name`, because its type is `string` and it
is not escaped. If you see the error, the plugin is working. Run `xss-scan` from the
terminal to confirm the CLI catches the same issue.

If no error appears, verify that your editor is using the workspace TypeScript version and
that the `plugins` array is present in the `tsconfig.json` that covers the file.



---
url: /guide/how-jsx-becomes-html.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# How JSX Becomes HTML

The transformation from JSX to an HTML string happens in two stages: a compile-time
rewrite by TypeScript and a runtime evaluation by the Kita Html functions.

## Compile time

When `tsconfig.json` specifies `jsx: "react-jsx"` and `jsxImportSource: "@kitajs/html"`,
TypeScript rewrites every JSX expression into a function call. Elements with a single
child call `jsx()`. Elements with multiple children call `jsxs()`. Attributes and children
are passed as a single props object.

```tsx title="Source TSX" twoslash kita
const html = (
  <ol start={2}>
    {[1, 2].map((i) => (
      <li>{i}</li>
    ))}
  </ol>
)
```

TypeScript compiles this to:

```tsx title="Compiled output" twoslash kita
// @showEmit
const html = (
  <ol start={2}>
    {[1, 2].map((i) => (
      <li>{i}</li>
    ))}
  </ol>
)
```

The JSX syntax is fully removed at compile time. The runtime never parses JSX.

## Runtime

The `jsx()` and `jsxs()` functions receive the tag name and the props object. They perform
three operations in sequence: serialize attributes into an HTML attribute string,
serialize children into a content string, and concatenate the opening tag, content, and
closing tag.

If any child is a `Promise`, the concatenation returns a `Promise<string>` instead of a
`string`. This propagation is automatic: a single async component anywhere in the tree
makes every ancestor async up to the root.

Void elements like `<br />`, `<img />`, and `<meta />` skip the closing tag entirely. The
runtime checks the tag name against a list ordered by frequency so the most common void
elements resolve in a single comparison.

Attributes are always escaped. The `class` attribute accepts arrays for conditional
composition. The `style` attribute accepts both strings and objects, with automatic
camelCase-to-kebab-case conversion for object keys. Boolean attributes like `disabled`
render as valueless attributes when `true` and are omitted when `false`.



---
url: /guide/ai-support.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# AI Support

Kita Html exposes multiple AI-friendly entry points so coding agents can understand the
runtime without falling back to React assumptions. Use the installable skill when you want
behavior guidance inside an agent, then use the published docs formats to provide focused
or broad reference material.

## Agent skill

The `kita-html` skill is designed for coding agents that support installable skills. It
teaches the core runtime model, XSS rules, framework adapters, async components, and
Suspense streaming so the agent stops treating every `.tsx` file as React.

Install it with:


```sh [npx]
npx skills add kitajs/html --skill kita-html
```

```sh [yarn]
yarn dlx skills add kitajs/html --skill kita-html
```

```sh [pnpm]
pnpm dlx skills add kitajs/html --skill kita-html
```

```sh [bunx]
bunx skills add kitajs/html --skill kita-html
```

```sh [deno]
deno run -A npm:skills add kitajs/html --skill kita-html
```

After installation, prompt the agent normally. Useful examples:

```text
Build this Fastify page with Kita Html and stream async sections.
```

```text
Fix this Kita TSX so user bios render safely and xss-scan passes.
```

```text
Convert this React-style server component into Kita Html.
```

## Documentation formats

Kita Html publishes the docs in three useful formats.

- [`llms.txt`](https://html.kitajs.org/llms.txt) is the lightweight index. Use it when AI
  should pick the right page first.
- [`llms-full.txt`](https://html.kitajs.org/llms-full.txt) is the full concatenated
  documentation dump. Use it when AI needs broad Kita Html context in a single fetch.
- Every page also has a raw Markdown version, such as
  [Getting Started.md](https://html.kitajs.org/guide/getting-started.md) or
  [Safe Attribute.md](https://html.kitajs.org/guide/xss/safe-attribute.md).

Choose the smallest format that matches the task. `llms.txt` is usually best for
discovery. Raw Markdown is usually best for one topic. `llms-full.txt` is best when the
agent needs a full view of the framework.

## Project instructions

If your editor or coding agent supports project instruction files, point it at Kita Html
before it writes JSX.

```markdown title="AGENTS.md"
# AGENTS.md

This project uses Kita Html, not React.

## Docs

- Kita Html index: https://html.kitajs.org/llms.txt
- Kita Html full docs: https://html.kitajs.org/llms-full.txt
- Getting started: https://html.kitajs.org/guide/getting-started.md
- Safe attribute: https://html.kitajs.org/guide/xss/safe-attribute.md

## Rules

- `JSX.Element` is `string | Promise<string>`.
- Children are not escaped by default.
- Use `safe` on native elements that render untrusted text.
- Run `xss-scan` during validation.
```

If your tool also supports a file like `CLAUDE.md`, reference the same instructions there.
The important part is that the agent sees Kita-specific rules before it starts generating
TSX.

## What To Share With AI

Share the narrowest document that answers the task.

- For setup issues, share
  [Getting Started.md](https://html.kitajs.org/guide/getting-started.md).
- For escaping questions, share
  [Safe Attribute.md](https://html.kitajs.org/guide/xss/safe-attribute.md) or
  [Safety Rules.md](https://html.kitajs.org/guide/xss/safety-rules.md).
- For streaming and async behavior, share
  [Using Suspense.md](https://html.kitajs.org/guide/async/using-suspense.md).
- For framework integration, share the matching Fastify, Express, or Elysia guide.
- For broader assistance, start with [`llms.txt`](https://html.kitajs.org/llms.txt) and
  move to [`llms-full.txt`](https://html.kitajs.org/llms-full.txt) only when the task
  needs wider context.



---
url: /guide/xss/safe-attribute.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Using the Safe Attribute

Every child expression in Kita Html renders without escaping by default. To escape user
input, apply the `safe` attribute to the nearest native element wrapping the expression.

## Native elements

Add `safe` to the element that directly contains the dynamic content. The runtime passes
all children through HTML entity escaping before concatenation.

```tsx twoslash kita
// @noErrors
let userInput = `<script>alert('XSS')</script>` as const
// ---cut---
const html = <div safe>{userInput}</div>
//                        ^?
```

Without `safe`, malicious input executes. Consider a user profile where the description
field contains
`</div><script>fetch('/steal', {method: 'POST', body: document.cookie})</script>`.
Rendering this without escaping closes the container early, injects a script tag, and runs
arbitrary code. The `safe` attribute converts the angle brackets to `&lt;` and `&gt;`,
rendering the payload as harmless text.

Place `safe` on the innermost element that holds the untrusted value. Do not add it to a
parent wrapper, as that would escape the HTML of child components too.

```tsx twoslash kita
function UserCard({ name, bio }: { name: string; bio: string }) {
  return (
    <div class="card">
      <h2 safe>{name}</h2>
      <p safe>{bio}</p>
    </div>
  )
}
// ---cut-after---
const html = <UserCard name="Name" bio="Bio" />
```

## Component children

The `safe` attribute only applies to native elements. If you pass an unsafe value as a
child to a component, you must either escape it manually or wrap it in a Fragment with the
`safe` attribute to tell the plugin it's already escaped. This prevents components from
accidentally rendering unescaped HTML when they receive dynamic content as children.

```tsx twoslash kita
let userInput: string = 'User input!'
import { Fragment, Children, escapeHtml } from '@kitajs/html'
function MyComponent({ children }: { children: Children }) {
  return <div>{children}</div>
}
let html: JSX.Element
// ---cut---
html = (
  <MyComponent>
    <Fragment safe>{userInput}</Fragment>
  </MyComponent>
)

// Or escape explicitly when the component doesn't support safe
html = <MyComponent>{escapeHtml(userInput)}</MyComponent>
```

## Template literal helper

The `e` tagged template is an alias to `escapeHtml()` that you can use as interpolated
content in template literals. It provides a convenient way to escape dynamic values
outside of JSX.

```tsx twoslash kita
const userName = '<script>untrusted()</script>' as const
// ---cut---
import { e } from '@kitajs/html'

const html = e`Hello, ${userName}!`
```

## Suppression conventions

When the XSS detection plugin flags a value that you know is safe, you can suppress the
warning without adding `safe` to the element, which would escape all children and
potentially break components.

::: danger

Suppressing warnings is dangerous because it allows unescaped HTML to slip through. Only
use these techniques when you have a guarantee of safety.

:::

Prefix the variable name with `safe`. The plugin treats any identifier starting with
`safe` as pre-escaped.

```tsx twoslash kita
const rawInput = "<script>alert('XSS')</script>" as const
function sanitizeElsewhere(raw: string): string {
  // Some external library or custom logic that guarantees safety
  return raw.replace(/</g, '&lt;').replace(/>/g, '&gt;')
}
// ---cut---
const safeContent = sanitizeElsewhere(rawInput)
//                                     ^?
const html = <div>{safeContent}</div>
//                      ^?
```

Following the same logic, prefixing a variable with `unsafe` explicitly marks it as
unescaped and triggers a warning if used in JSX.

```tsx twoslash kita
// @errors: 88601
const unsafeContent = 'My safe string' as const
const html = <div>{unsafeContent}</div>
```

::: warning

Manual casts and naming conventions are not enforced by the compiler. They rely on
developer discipline and code reviews to ensure safety. Use them judiciously and document
the rationale for any exceptions.

:::

Cast the expression to `'safe'` inline. This tells the plugin to skip the check for that
specific usage and not warn about possible XSS vulnerabilities.

```tsx twoslash kita
const content: string = '<script>untrusted()</script>'
// ---cut---
const html = <div>{content as 'safe'}</div>
```

Call `Html.escapeHtml()` directly. The plugin recognizes the return value as escaped.

```tsx twoslash kita
const content: string = '<script>untrusted()</script>'
// ---cut---
import { Html } from '@kitajs/html'

const html = <div>{Html.escapeHtml(content)}</div>
```



---
url: /guide/xss/scanner-cli.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Running the XSS Scanner

The `xss-scan` CLI ships with `@kitajs/ts-html-plugin` and performs project-wide XSS
analysis from the command line.

## Usage

```bash
xss-scan [options] [files...]
```

The command can also be invoked as `ts-html-plugin`, which is an alias for the same CLI.

When called without file arguments, it scans all files included by the project's
`tsconfig.json`. When file paths are provided, only those files are analyzed.

```bash
# Scan entire project
xss-scan

# Scan specific files
xss-scan src/pages/login.tsx src/pages/profile.tsx
```

## Options

`--cwd <path>` sets the working directory. Defaults to the current directory.

`-p, --project <path>` specifies the path to `tsconfig.json`. Defaults to `tsconfig.json`
in the working directory.

`-s, --simplified` outputs diagnostics in a compact single-line format, useful for machine
parsing.

## Exit codes

The scanner exits with code 0 when no issues are found, 1 when errors are present, and 2
when only warnings exist. This makes it suitable for CI gates where you want to fail on
errors but optionally allow warnings.

## Integration

Add the scanner to your test script so it runs before or alongside your test suite.

```json
{
  "scripts": {
    "test": "xss-scan && vitest"
  }
}
```

In a GitHub Actions workflow:

```yaml
- name: XSS scan
  run: npx xss-scan
```

The scanner uses the same TypeScript program and analysis engine as the editor plugin, so
findings are identical between the two.



---
url: /guide/xss/safety-rules.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Safety Rules

The XSS detection engine classifies every JSX child expression as safe or unsafe based on
its TypeScript type. This page lists the rules the engine follows.

## Safe types

Expressions with these types render without escaping and produce no diagnostic:

- `number`, `boolean`, `bigint`, `null`, `undefined`
- String literals (e.g. `'hello'` rather than `string`)
- `JSX.Element` (the output of another component, already rendered)
- `Html.Children` (the typed children alias)
- Return values of `Html.escapeHtml()`, `Html.escape()`, or `e` template literals
- Variables whose name starts with `safe` (e.g. `safeContent`, `safeHtml`)

## Unsafe types

Expressions with these types trigger a diagnostic unless wrapped with `safe` or escaped
manually:

- `string` (a dynamic string that could contain HTML)
- `any` (the engine cannot verify safety without a concrete type)
- Objects relying on `toString()` for rendering

## Composite types

Union types are safe only if every member of the union is safe. `string | number` is
unsafe because `string` is unsafe. `number | boolean` is safe because both members are
safe.

Both branches of ternary and binary expressions are checked independently. Even if one
branch is unreachable at runtime, the engine still analyzes its type.

```tsx twoslash
// @errors: 88601
const condition = true
const safeValue = 42
const unsafeString = 'user input'

;<div>{condition ? safeValue : unsafeString}</div>
```

## Exceptions

Content inside `<script>` elements is exempt from analysis. Script content is intended to
be executable and is not subject to HTML escaping rules.



---
url: /guide/xss/error-codes.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Error Codes

The XSS detection engine emits four diagnostic codes. Each code links to a specific kind
of safety issue with a defined fix.

## TS88601 Error
**Content may introduce an XSS vulnerability and must be marked with the `safe`
attribute.**



An expression with type `string` or `any` is used as a child of a native element without
the `safe` attribute.

```tsx twoslash kita
//@errors: 88601
let username = 'Arthur'
// ---cut---
const html = <div>{username}</div>
```

Variables prefixed with `safe` are exempt from this rule, as are expressions with safe
types _(numbers, booleans, string literals...)_.

::: tip Fix

Add the `safe` attribute to escape the content

```tsx twoslash kita
//@errors: 88601
let username: string = 'Arthur'
// ---cut---
const html = <div safe>{username}</div>
```

:::

## TS88602 Error
**The `safe` attribute causes this content to be escaped more than once.**



Severity: error. The `safe` attribute is applied to an element whose children include JSX
elements. This would escape the HTML output of those child components, corrupting their
markup.

```tsx twoslash kita
//@errors: 88602
const user = { name: 'Arthur', badgeUrl: 'https://example.com/badge.png' }
function UserBadge(props: { url: string }) {
  return (
    <div class="badge">
      <img src={props.url} alt="User badge" />
    </div>
  )
}
// ---cut---
const html = (
  <div safe>
    {user.name}
    <UserBadge url={user.badgeUrl} />
  </div>
)
```

You can also wrap inner components inside fragments or use `escapeHtml()` manually to
avoid the double escaping.

::: tip Fix

Remove `safe` from the parent element. You can use `Fragment` to apply `safe` to a group
of children without affecting nested components, since fragments don't render actual HTML
elements.

```tsx twoslash kita
//@errors: 88602
const user = { name: 'Arthur', badgeUrl: 'https://example.com/badge.png' }
function UserBadge(props: { url: string }) {
  return (
    <div class="badge">
      <img src={props.url} alt="User badge" />
    </div>
  )
}
// ---cut---
import { Fragment } from '@kitajs/html'

const html = (
  <div>
    <Fragment safe>{user.name}</Fragment>
    <UserBadge url={user.badgeUrl} />
  </div>
)
```

:::

## TS88603 Error
**Content inside a Component must be escaped using escapeHtml().**



An expression with type `string` or `any` is passed as a child to a component (uppercase
tag name). Unlike native elements, components cannot use the `safe` attribute directly on
children.

```tsx twoslash kita
//@errors: 88603
let userName: string = 'Arthur'
function Card({ children }: { children: string }) {
  return <div>{children}</div>
}
// ---cut---
const html = <Card>{userName}</Card>
```

Components cannot apply the `safe` attribute directly to their children. You must either
escape the content before passing it, or wrap it in a Fragment with the `safe` attribute.

::: tip Fix

Escape manually using `Html.escapeHtml()`

```tsx twoslash kita
//@errors: 88603
import Html from '@kitajs/html'

let userName: string = 'Arthur'
function Card({ children }: { children: string }) {
  return <div>{children}</div>
}
// ---cut---
const html = <Card>{Html.escapeHtml(userName)}</Card>
```

Or wrap the content in a Fragment with `safe`

```tsx twoslash kita
//@errors: 88603
import { Fragment } from '@kitajs/html'

let userName: string = 'Arthur'
function Card({ children }: { children: JSX.Element }) {
  return <div>{children}</div>
}

// ---cut---
const html = (
  <Card>
    <Fragment safe>{userName}</Fragment>
  </Card>
)
```

:::

## TS88604 Warning
**The `safe` attribute is unused in this context.**



The `safe` attribute is applied to an element whose children are already safe types
(numbers, booleans, `JSX.Element`, etc.). The escaping is redundant and can be removed.

```tsx twoslash kita
//@errors: 88604
const count = 42
// ---cut---
const html = <span safe>{count}</span>
```

Numbers, booleans, bigints, string literals, and `JSX.Element` types are already safe and
cannot introduce XSS vulnerabilities. The `safe` attribute has no effect on these types.

::: tip Fix

Remove the `safe` attribute since numbers are already safe

```tsx twoslash kita
//@errors: 88604
const count = 42
// ---cut---
const html = <span>{count}</span>
```

:::



---
url: /guide/xss/why-not-auto-escape.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Why Not Auto-Escape

In React, every JSX element is an object with a `$$typeof` symbol, a type field, and a
props object. When React renders children, it can inspect each child's type at runtime:
objects with `$$typeof` are component output and pass through unchanged, while strings are
user content and get escaped. The object wrapper is what makes auto-escaping possible.

Kita Html takes a different approach. Every JSX element evaluates to a plain `string`. A
`<div>` returns `'<div></div>'`, and a component that renders a `<div>` also returns
`'<div></div>'`. At the point where a parent element concatenates its children, there is
no runtime marker to distinguish between a string that came from a component and a string
that came from user input. Both are the same type with the same structure.

This is a fundamental consequence of the string-based architecture. Wrapping every string
in an object to enable auto-escaping would eliminate the performance advantage that makes
the library useful. The entire design relies on avoiding intermediate representations.

## How the tooling compensates

Instead of runtime auto-escaping, Kita Html shifts the responsibility to compile-time
analysis. The TypeScript plugin and CLI scanner inspect the type of every JSX child
expression. If the type is `string` or `any`, the tools emit an error. If the type is
`number`, `boolean`, `JSX.Element`, or another safe type, the expression passes without a
diagnostic.

This means the protection is type-driven rather than value-driven. A variable of type
`string` is always flagged, even if its value at runtime happens to be safe HTML. A
variable of type `number` is never flagged, because numbers cannot contain HTML. The
analysis is conservative: it produces false positives (flagging safe strings) but never
false negatives (missing unsafe ones).

The practical result is that developers must mark every point where user input enters the
JSX tree, either with the `safe` attribute or with an explicit `escapeHtml()` call. The
tooling enforces this exhaustively. Code that compiles without diagnostics and passes
`xss-scan` contains no unescaped user input unless the developer explicitly suppressed the
check.



---
url: /guide/xss/detection.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# How XSS Detection Works

Kita Html catches XSS vulnerabilities before they reach production through two tools that
share the same analysis engine: a TypeScript language service plugin for real-time editor
feedback, and a CLI scanner for CI/CD pipelines.

## Editor plugin

The TypeScript plugin hooks into `getSemanticDiagnostics`. When a `.tsx` or `.jsx` file is
analyzed, the plugin walks the JSX AST depth-first and inspects every expression used as a
child of an element. For each expression, it resolves the TypeScript type and determines
whether that type could carry unescaped HTML.

If the type is `string`, `any`, or an object with `toString()`, the expression is flagged
as unsafe. If the type is a number, boolean, string literal, `JSX.Element`, or
`Html.Children`, it is considered safe. Union types are safe only if every member is safe.
Both branches of ternary expressions are checked independently.

The plugin emits diagnostics directly in the editor with error codes TS88601 through
TS88604. These appear as red or yellow squiggles on the unsafe expression, with a message
explaining the issue and how to fix it.

## CLI scanner

The `xss-scan` CLI creates a TypeScript program from your `tsconfig.json`, loads all
project files, and runs the same analysis as the editor plugin. It outputs colored
diagnostics to the terminal and exits with code 0 (clean), 1 (errors found), or 2
(warnings only).

Adding `xss-scan` to your test script ensures that every CI run catches XSS issues that
may have been introduced since the last commit. The scanner analyzes the entire project in
a single pass, making it suitable for pre-commit hooks or CI gates.

## What this means in practice

The combination of editor-time and CI-time detection creates a closed loop. The editor
catches issues as you type. The CI scanner catches anything that slipped through, such as
changes from a developer without the plugin configured, or type changes in a dependency
that make a previously safe expression unsafe. The only way to ship XSS-vulnerable code is
to explicitly suppress the diagnostic using one of the documented suppression techniques.



---
url: /guide/async/async-components.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Async Components

A Kita Html component can be an `async` function. When it is, the JSX expression evaluates
to a `Promise<string>` instead of a `string`.

```tsx twoslash kita
import { jsx as __jsx } from '@kitajs/html/jsx-runtime'
let db = {
  async getUser(id: string): Promise<{ name: string }> {
    return { name: 'John Doe' }
  }
}

// ---cut---
async function UserCard({ id }: { id: string }) {
  const user = await db.getUser(id)
  return <div safe>User card for user: {user.name}</div>
}

const html = <UserCard id="123" />
// html is Promise<string>
```

## Promise propagation

When any child in a component tree is async, the entire parent chain becomes async
automatically. The runtime detects promises during child concatenation and wraps the
result in `Promise.all`. No manual promise handling is required at intermediate levels.

```tsx twoslash kita
async function UserCard({ id }: { id: string }) {
  return <div safe>User card for id: {id}</div>
}
// ---cut---
function Page() {
  return (
    <div>
      <UserCard id="123" />
      <p>Static content</p>
    </div>
  )
}

const html = <Page />
// Page() returns Promise<string> because UserCard is async
```

This propagation is transitive. If `UserCard` is nested three levels deep, every ancestor
up to the root becomes a `Promise<string>`.

## JSX.Element type

The type `JSX.Element` is defined as `string | Promise<string>`. This reflects the reality
that any component tree may or may not contain async components. When you are certain that
a tree is fully synchronous, you can cast the result to `string`.

```tsx twoslash kita
function StaticPage() {
  return <div>Static page content</div>
}
// ---cut---
// When you know the tree is sync-only
const html = (<StaticPage />) as string
```

TypeScript cannot infer whether a component tree is synchronous or asynchronous at the
type level, because the presence of async children is a runtime property of the tree
structure. This is a known TypeScript limitation
([microsoft/TypeScript#14729](https://github.com/microsoft/TypeScript/issues/14729)).

## When to await

If you need the resolved HTML string, await the result. If you are passing it to a stream
or to a [framework integration](/integrations/overview.md) that handles promises, you can
pass the promise directly without awaiting.

```tsx
// Await when you need the string
const html = await (<Page />)
response.end(html)

// Pass directly when the consumer handles promises, e.g our fastify or express plugins
reply.html(<Page />)
```



---
url: /guide/async/suspense.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Suspense Streaming

Without Suspense, the server must wait for every async component to resolve before sending
any HTML to the client. For pages with multiple independent data sources, this means the
total response time equals the slowest component.

Suspense solves this by streaming. The server sends the page skeleton with fallback
content immediately, then streams the resolved content for each async subtree as it
becomes ready. The client replaces each fallback in place, so the page progressively fills
in without a full reload.

## How it works

A `Suspense` component wraps async children and provides a synchronous fallback. When
rendered, it returns the fallback immediately wrapped in a marker element. The async
children resolve in the background. Once resolved, the runtime pushes a `<template>`
containing the real content and a `<script>` that triggers the DOM replacement.

The client-side replacement script is injected automatically before the first Suspense
result is streamed. It reads each `<template>`, replaces the corresponding fallback
`<div>`, and processes any pending templates that arrived before their fallback was in the
DOM.

## Request isolation

Every Suspense boundary requires a `rid` (request ID) that ties it to a specific HTTP
request. This is necessary because multiple requests may be rendering concurrently, and
the global Suspense state must track which stream belongs to which request.

When using `renderToStream`, the `rid` is generated automatically and passed to your
component function. When using a [framework integration](/integrations/overview.md), use the
request's built-in ID (e.g. `req.id` in Fastify).

## When to use Suspense

Suspense is valuable when a page has multiple independent async sections with different
latencies. Each Suspense boundary operates independently, so a fast database query can
appear immediately while a slow API call shows its fallback. Without Suspense, the entire
page waits for the slowest operation.

For pages with a single async operation or where all data is fetched at once, a simple
`await` is sufficient and Suspense adds no benefit.



---
url: /guide/async/using-suspense.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Using Suspense

Import `Suspense` and `renderToStream` from `@kitajs/html/suspense`.

## Basic usage

Wrap async components in a `Suspense` element with a `rid`, a `fallback`, and optionally a
`catch` handler. Then pass the tree to `renderToStream`, which returns a `Readable`
stream.

```tsx twoslash kita=stream
import { jsx as __jsx } from '@kitajs/html/jsx-runtime'
import { Suspense, renderToStream } from '@kitajs/html/suspense'

let api = {
  async getStats(id: string): Promise<{ totalPosts: number }> {
    return { totalPosts: Number(id) }
  }
}

// ---cut---

async function UserStats({ id }: { id: string }) {
  const stats = await api.getStats(id)
  return <div>{stats.totalPosts} posts</div>
}

const stream = renderToStream((rid) => (
  <html>
    <body>
      <h1>Dashboard</h1>
      <Suspense rid={rid} fallback={<div>Loading stats...</div>}>
        <UserStats id="123" />
      </Suspense>
    </body>
  </html>
))
```

The `renderToStream` callback receives the `rid` automatically. Pipe the returned stream
to your HTTP response.

```tsx
import { text } from 'node:stream/consumers'

// As a stream
stream.pipe(response)

// Or consume entirely (loses streaming benefits, useful for testing)
const html = await text(stream)
```

## Custom request IDs

If you need to control the request ID, pass it as the second argument and use it directly
in your JSX.

```tsx twoslash kita=stream
import { jsx as __jsx } from '@kitajs/html/jsx-runtime'
import { Suspense, renderToStream } from '@kitajs/html/suspense'

const myCustomId = `req-${Math.random().toString(36).slice(2)}`

async function AsyncContent() {
  return <div>Loaded content</div>
}

// ---cut---
const stream = renderToStream(
  (rid) => (
    <Suspense rid={rid} fallback={<div>Loading...</div>}>
      <AsyncContent />
    </Suspense>
  ),
  myCustomId
)
```

## Error handling

The `catch` prop handles errors thrown by async children. It accepts a JSX element or a
function that receives the error and returns JSX.

```tsx twoslash kita
import { Suspense } from '@kitajs/html/suspense'

const rid = 'req-1'

async function AsyncContent() {
  return <div>Loaded content</div>
}
// ---cut---
const html = (
  <Suspense
    rid={rid}
    fallback={<div>Loading...</div>}
    catch={(error) => <div>Failed: {String(error)}</div>}
  >
    <AsyncContent />
  </Suspense>
)
```

Without a `catch` prop, errors propagate to the stream as an `'error'` event. Always
provide a `catch` handler in production to prevent the stream from closing unexpectedly.

## Multiple boundaries

Each Suspense boundary resolves independently. Place separate boundaries around sections
that fetch different data so they can appear as soon as their data is ready.

```tsx twoslash kita=stream
import { Suspense, renderToStream } from '@kitajs/html/suspense'

async function UserProfile({ id }: { id: string }) {
  return <div>User {id}</div>
}

async function ActivityFeed({ id }: { id: string }) {
  return <div>Feed {id}</div>
}
// ---cut---
const stream = renderToStream((rid) => (
  <html>
    <body>
      <Suspense rid={rid} fallback={<div>Loading user...</div>}>
        <UserProfile id="123" />
      </Suspense>
      <Suspense rid={rid} fallback={<div>Loading feed...</div>}>
        <ActivityFeed id="123" />
      </Suspense>
    </body>
  </html>
))
```

The same `rid` is shared across all Suspense boundaries in the same request. The stream
closes automatically when the last boundary resolves.

## Async fallbacks

The `fallback` prop can be an async component, but this blocks the entire stream until the
fallback resolves. The server will not send any HTML until the async fallback is ready.

```tsx twoslash kita=stream
import { Suspense, renderToStream } from '@kitajs/html/suspense'

async function loadTranslations() {
  return
}

async function UserProfile({ id }: { id: string }) {
  return <div>User {id}</div>
}
// ---cut---
async function LoadingMessage() {
  await loadTranslations()
  return <div>Loading user data...</div>
}

const stream = renderToStream((rid) => (
  <Suspense rid={rid} fallback={<LoadingMessage />}>
    <UserProfile id="123" />
  </Suspense>
))
```

The stream waits for `LoadingMessage` to resolve before sending anything to the client.
This defeats the purpose of streaming. Use synchronous fallbacks whenever possible.

If an async fallback throws an error, wrap the Suspense in an `ErrorBoundary` to handle
it. The `catch` prop only handles errors from the async children, not from the fallback
itself.



---
url: /guide/async/error-boundaries.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Error Boundaries

Error boundaries catch errors thrown by async components and render a fallback instead of
crashing the entire tree.

## Usage

Import `ErrorBoundary` from `@kitajs/html/error-boundary` and wrap async components. The
`catch` prop accepts a JSX element or a function that receives the error.

```tsx twoslash
import { ErrorBoundary } from '@kitajs/html/error-boundary'

let db = {
  async getUser(id: string): Promise<{ name: string }> {
    return { name: `user-${id}` }
  }
}

// ---cut---
async function UserProfile({ id }: { id: string }) {
  const user = await db.getUser(id) // may reject
  return <div safe>{user.name}</div>
}

const html = await (
  <ErrorBoundary catch={(err) => <div>Error: {String(err)}</div>}>
    <UserProfile id="123" />
  </ErrorBoundary>
)
```

If `UserProfile` throws, the boundary renders the catch fallback. If it succeeds, the
boundary renders the component output unchanged.

## Sync components

Error boundaries only catch errors from async components, because synchronous errors
propagate before the boundary can intercept them. For synchronous components, use a
standard try/catch.

```tsx twoslash kita
function riskyOperation() {
  return 'Loaded safely'
}

// ---cut---
function SyncComponent() {
  try {
    const data = riskyOperation()
    return <div>{data}</div>
  } catch (err) {
    return <div>Error: {String(err)}</div>
  }
}

// ---cut-start---
const html = <SyncComponent />
// ---cut-end---
```

## Combining with Suspense

Error boundaries and Suspense serve different purposes and are used together. Suspense's
`catch` prop handles errors from its async children. An `ErrorBoundary` wrapping the
Suspense handles errors from the fallback itself.

```tsx twoslash
import { ErrorBoundary } from '@kitajs/html/error-boundary'
import { Suspense } from '@kitajs/html/suspense'

const rid = 'req-1'

async function AsyncFallback() {
  return <div>Loading fallback...</div>
}

async function AsyncContent() {
  return <div>Loaded content</div>
}
// ---cut---
const html = (
  <ErrorBoundary catch={<div>Fallback failed</div>}>
    <Suspense rid={rid} fallback={<AsyncFallback />} catch={<div>Children failed</div>}>
      <AsyncContent />
    </Suspense>
  </ErrorBoundary>
)
```

If `AsyncContent` throws, Suspense renders "Children failed". If `AsyncFallback` throws,
the ErrorBoundary renders "Fallback failed". These are independent error paths.



---
url: /guide/async/streaming-internals.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Streaming Internals

This page describes how Suspense streaming works at the protocol level, from the initial
HTML response to the client-side DOM replacement.

## Initial response

When `renderToStream` produces the initial HTML, each Suspense boundary renders its
fallback content wrapped in a `<div>` with a `data-sf` attribute and a unique ID derived
from the request id and the boundary's run number.

```html
<div id="B:req-1:1" data-sf>Loading...</div>
```

This div is part of the initial HTML chunk sent to the client. The browser renders it
immediately.

## Async resolution

When an async child resolves, the runtime pushes two elements to the stream: a
`<template>` containing the resolved HTML and a `<script>` that triggers the replacement.

```html
<template id="N:req-1:1" data-sr><div>Actual content</div></template>
<script id="S:req-1:1" data-ss>
  $KITA_RC('req-1:1')
</script>
```

The `<template>` is inert, the browser does not render its content. The `<script>`
executes immediately when the browser receives it, calling the replacement function.

## Client-side replacement

The `$KITA_RC` function is a small script injected before the first Suspense result. It
finds the fallback div by ID, extracts the template's content into a document fragment,
and replaces the div with the fragment. It then removes the template and script elements
from the DOM.

After each replacement, the function scans for any pending templates whose fallback divs
were not yet in the DOM when they arrived. This handles cases where a fast async boundary
resolves before the initial HTML containing its fallback has been parsed.

## HTTP transfer

The response uses chunked transfer encoding. The initial HTML is the first chunk. Each
resolved Suspense boundary produces an additional chunk. The response has no
`Content-Length` header, so the connection remains open until the last boundary resolves
and the stream is closed.

Runtimes like Node.js and Bun handle chunked encoding automatically when data is written
to the response without a content-length header.



---
url: /guide/jsx/syntax.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# JSX Syntax

Kita Html uses standard JSX syntax. All HTML elements and attributes defined in the
[HTML specification](https://html.spec.whatwg.org/multipage#toc-semantics) are supported
with full TypeScript type checking.

## Fragments

Use fragments to return multiple elements without a wrapper.

```tsx
const html = (
  <>
    <div>First</div>
    <div>Second</div>
  </>
)
// '<div>First</div><div>Second</div>'
```

## Void elements

Self-closing elements like `<br />`, `<img />`, `<input />`, and `<meta />` do not produce
a closing tag. The runtime detects void elements by tag name.

## Boolean attributes

When a boolean attribute is `true`, it renders as a valueless attribute. When `false`, it
is omitted entirely.

```tsx
<input disabled={true} />
// '<input disabled>'

<input disabled={false} />
// '<input>'
```

## Style attribute

The `style` attribute accepts both strings and objects. Object keys are converted from
camelCase to kebab-case automatically.

```tsx
<div style="color: red" />
<div style={{ color: 'red', fontSize: '14px' }} />
// Both: '<div style="color:red;font-size:14px"></div>'
```

## Conditional classes

The `class` attribute accepts an array. Falsy values are filtered out and the remaining
values are joined with spaces. This pattern is similar to
[clsx](https://github.com/lukeed/clsx) but does not support objects.

```tsx
<div class={['base', isActive && 'active', size]} />
// If isActive is false and size is 'lg':
// '<div class="base lg"></div>'
```

## The tag tag

The `<tag of="name">` element renders a tag whose name is determined at runtime. Use this
when the tag name is dynamic or when you need kebab-case tag names that JSX syntax does
not support.

```tsx
<tag of="my-custom-element" id="el">
  content
</tag>
// '<my-custom-element id="el">content</my-custom-element>'
```

For tags known at compile time, prefer extending the JSX type system instead.

## Serialization

Different JavaScript types serialize differently when used as children.

| Expression     | Output    |
| -------------- | --------- |
| `{"abc"}`      | `abc`     |
| `{42}`         | `42`      |
| `{true}`       | `true`    |
| `{false}`      | `false`   |
| `{null}`       | _(empty)_ |
| `{undefined}`  | _(empty)_ |
| `{[1, 2, 3]}`  | `123`     |
| `{BigInt(42)}` | `42`      |

Arrays are concatenated with no separator. `null` and `undefined` produce no output.
Booleans render as their string representation, unlike React which suppresses `true` and
`false`.

## Missing elements or attributes

If an HTML element or attribute is missing from the type definitions, open a pull request
adding it. See the
[contributing guide](https://github.com/kitajs/html/blob/master/CONTRIBUTING.md) for setup
instructions.



---
url: /guide/jsx/extending-types.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Extending JSX Types

Kita Html's type system can be extended to support custom elements, custom attributes, or
both.

## Custom elements

Declare new entries in `JSX.IntrinsicElements` to add custom HTML elements with typed
attributes.

```tsx
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'math-power': HtmlTag & {
        exponent: number
        children: number
      }
    }
  }
}

;<math-power exponent={2}>{3}</math-power>
// '<math-power exponent="2">3</math-power>'
```

## Custom attributes on all elements

Extend the `HtmlTag` interface to add attributes to every native HTML element.

```tsx
declare global {
  namespace JSX {
    interface HtmlTag {
      'data-testid'?: string
    }
  }
}

;<div data-testid="header">content</div>
```

## Allow any tag and attribute

If you need to bypass type checking entirely, add a triple-slash directive to your
`src/kita.d.ts` file. This is not recommended for production code.

```ts title="src/kita.d.ts"
/// <reference types="@kitajs/html/all-types.d.ts" />
```



---
url: /guide/jsx/design-decisions.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Design Decisions

This page documents the major architectural decisions in Kita Html and their rationale.

## Why there is no context API

Kita Html only produces strings or promises of strings. It does not manage lifecycle,
state, or render cycles. The primary use case for a context API in other JSX frameworks is
to avoid prop drilling, passing data through many layers of components without explicit
props at each level.

A context API in a string-based renderer would need to be scoped per request to be safe in
concurrent environments. If two requests render simultaneously and both use async
components, a global context would be corrupted: one request's async resolution would read
the other request's context values.

The only way to scope context per request is to attach a request identifier (`rid`) to
every context read. But if every component that reads context must receive an `rid`, the
API offers no advantage over passing data as props directly.

An alternative is `AsyncLocalStorage`, which provides implicit per-request scoping without
explicit identifiers. However, ALS introduces measurable performance overhead on every
async boundary and adds a hidden dependency between components and their execution
context. This conflicts with the library's goal of minimal runtime cost.

The recommended approach is props and composition. Structure components so that data flows
explicitly through the tree. If deeply nested components need access to request-level
data, restructure the tree so the data is passed at a higher level rather than drilled
through intermediate components.

## Why JSX.Element includes Promise

The type `JSX.Element` is defined as `string | Promise<string>` because the presence of
async children is a runtime property of the component tree, not a static property of any
single component. A synchronous component becomes async if any of its descendants are
async. TypeScript cannot express this conditional relationship in the type system
([microsoft/TypeScript#14729](https://github.com/microsoft/TypeScript/issues/14729)).

Defining `JSX.Element` as just `string` would require every async component to be awaited
at the call site, breaking the seamless composition model. Defining it as just
`Promise<string>` would force unnecessary async overhead on fully synchronous trees. The
union type is the correct representation of the runtime behavior.



---
url: /guide/reference/benchmarks.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Benchmarks

Kita Html is a string builder. The most representative way to measure its performance is
through micro benchmarks that compare string generation speed against other HTML builders.

## Results

Benchmarked on a 13th Gen Intel Core i5-13600K (\~4.80 GHz) running Node.js v24.13.0 on
2026-02-23. Run `pnpm bench` in the repository root to reproduce.

### RealWorldPage (170.5 KiB output)

| Library    | Avg time  | Avg memory | Notes                          |
| ---------- | --------- | ---------- | ------------------------------ |
| KitaJs     | 361.79 µs | 1.83 mb    | baseline                       |
| Preact     | 806.05 µs | 3.09 mb    | 2.2x slower                    |
| ReactJsx   | 1.01 ms   | 3.30 mb    | 2.8x slower                    |
| React      | 1.04 ms   | 3.68 mb    | 2.9x slower                    |
| HonoJsx    | 1.05 ms   | 3.14 mb    | 2.9x slower                    |
| vHtml      | 2.06 ms   | 3.54 mb    | 5.7x slower, different output  |
| TypedHtml  | 2.11 ms   | 7.13 mb    | 5.8x slower, different output  |
| CommonTags | 3.58 ms   | 6.30 mb    | 9.9x slower, template engine   |
| Jsxte      | 3.95 ms   | 13.94 mb   | 10.9x slower, different output |
| Ghtml      | 230.79 µs | 0.65 mb    | template engine, 204.5 KiB     |
| HonoHtml   | 118.12 µs | 0.55 mb    | template engine, 204.5 KiB     |

Libraries marked "different output" produce HTML that differs from React's output for the
same input. Libraries marked "template engine" lack JSX syntax, so they have no per-call
function overhead and produce a larger output for the same logical content.

## Methodology

The RealWorldPage benchmark is the most meaningful, as it represents a realistic workload
scenario with a full component tree. Template engines such as Ghtml and HonoHtml have an
inherent advantage: with no function call per element and no JSX transform, they trade
away syntax highlighting and editor intellisense. The JSX-based results reflect the actual
cost incurred by any JSX library.

## Why it is fast

The performance comes from the string-only architecture. There is no object tree
construction, no diffing, and no serialization step. The runtime uses
character-by-character loops for HTML escaping instead of regex replacements, checks
before converting (regex test before expensive operations), and orders void element checks
by frequency. When running on Bun, the runtime delegates escaping to Bun's native
`escapeHTML` implementation.



---
url: /guide/reference/compatibility.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Compatibility

## Runtimes

Kita Html works on Node.js 20.13 and later. Bun is fully supported and uses its native
`Bun.escapeHTML` for faster escaping. Deno is untested but expected to work since the
library has no native dependencies.

## TypeScript

TypeScript 6.0 or later is required for full compatibility with the latest type
definitions.

The native TypeScript compiler `tsgo` works for building projects that use Kita Html. The
language service plugin (`@kitajs/ts-html-plugin`) requires the standard TypeScript
language server and will not work with `tsgo` while
[`tsgo` doesn't publish its own support for plugins](https://github.com/microsoft/typescript-go#what-works-so-far).

## Module system

The packages emit CommonJS. ESM consumers can import them with `esModuleInterop` enabled
in `tsconfig.json`.

## Frameworks

Official [framework integrations](/integrations/overview.md) exist for Fastify (4.x and 5.x),
Express (4.x and 5.x), and Elysia. Kita Html also works with any framework that accepts
strings: Hono, Bun's built-in server, AdonisJS, and others. Send the string or stream
directly in the response body.

## Browsers

The core HTML string output works anywhere the browser can render HTML. Suspense streaming
has a stricter client requirement because the injected replacement script depends on
`HTMLTemplateElement.content` and `Element.remove()`.

In practice, Suspense streaming supports modern evergreen browsers released since
late 2015. IE11 is not supported.

## Editors

The XSS detection plugin works in any editor that supports TypeScript language service
plugins. VS Code requires the workspace TypeScript to be selected instead of the built-in
version.



---
url: /guide/reference/migrating-from-html.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Migrating from HTML

Converting existing HTML templates to JSX requires a few mechanical transformations.

## Automated conversion

Use [Html To Jsx](https://magic.reactjs.net/htmltojsx.htm) for bulk conversion. Paste HTML
and receive JSX output.

## Manual conversion rules

Unlike React, Kita Html uses standard HTML attribute names. `class` stays as `class`, not
`className`. `for` stays as `for`, not `htmlFor`.

Void elements must be explicitly self-closed: `<br>` becomes `<br />`, `<img src="...">`
becomes `<img src="..." />`.

HTML comments become JSX comments: `<!-- comment -->` becomes `{/* comment */}`.

Inline styles can remain as strings. Kita Html accepts `style="color: red"` directly,
unlike React which requires an object.

Multiple root elements must be wrapped in a fragment:

```tsx
// HTML
<div>First</div>
<div>Second</div>

// JSX
<>
  <div>First</div>
  <div>Second</div>
</>
```



---
url: /guide/reference/additional-config.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Additional Configuration

## Formatting HTML output

Kita Html emits compact HTML strings with no whitespace or indentation. If you need
pretty-printed output for debugging or readability, use
[html-prettify](https://www.npmjs.com/package/html-prettify).

```tsx
import prettify from 'html-prettify'

const html = (
  <div>
    <div>1</div>
    <div>2</div>
  </div>
)

console.log(html)
// '<div><div>1</div><div>2</div></div>'

console.log(prettify(html))
// '<div>\n  <div>1</div>\n  <div>2</div>\n</div>'
```

## Legacy JSX transform

Kita Html can be used with the older `jsx: "react"` transform instead of
`jsx: "react-jsx"`. This requires manually importing the `Html` namespace in every file
that uses JSX.

```json
{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "Html.createElement",
    "jsxFragmentFactory": "Html.Fragment"
  }
}
```

```tsx
import { Html } from '@kitajs/html'

const html = <div>Hello</div>
```

This approach has a slight performance penalty because TypeScript generates
`Html.createElement` calls with rest parameters for children, rather than the optimized
`jsx`/`jsxs` calls of the modern transform. Use the `react-jsx` transform unless you have
a specific reason not to.



---
url: /integrations/overview.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Integrations

Kita Html produces strings. Any framework or library that can send a string as an HTTP
response works with Kita Html without additional setup. Express, Hono, Bun's built-in
server, and AdonisJS all accept strings directly in their response methods.

Official framework plugins are available for [Fastify](/integrations/frameworks/fastify.md),
[Express](/integrations/frameworks/express.md), and
[Elysia](/integrations/frameworks/elysia.md), providing automatic content type headers,
doctype injection, and Suspense streaming support.

For frontend libraries that use custom HTML attributes, Kita Html provides TypeScript type
definitions that enable autocomplete and type checking for HTMX, Alpine.js, and Hotwire
Turbo attributes. These are opt-in through triple-slash directives or `tsconfig.json`
entries.



---
url: /integrations/frameworks/fastify.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Fastify

`@kitajs/fastify-html-plugin` adds a `reply.html()` method to Fastify that handles content
type headers, Suspense streaming, and automatic doctype injection.

## Setup

:::danger XSS Protection Required

You must install and configure `@kitajs/ts-html-plugin` before using this plugin to avoid
XSS vulnerabilities. See the [Getting Started](/guide/getting-started.md) guide for complete
setup instructions including TypeScript configuration and XSS detection.

:::


```sh [npm]
npm i @kitajs/fastify-html-plugin
```

```sh [yarn]
yarn add @kitajs/fastify-html-plugin
```

```sh [pnpm]
pnpm add @kitajs/fastify-html-plugin
```

```sh [bun]
bun add @kitajs/fastify-html-plugin
```

Register the plugin on your Fastify instance:

```tsx
import fastify from 'fastify'
import fastifyKitaHtml from '@kitajs/fastify-html-plugin'

const app = fastify()
await app.register(fastifyKitaHtml)
```

## Sending HTML

Use `reply.html()` with any JSX expression. The plugin sets the `Content-Type` header to
`text/html; charset=utf-8`.

```tsx
app.get('/', (req, reply) => {
  reply.html(<div>Hello World</div>)
})
```

For async components, `reply.html()` accepts promises and awaits them before sending.

```tsx
app.get('/profile', (req, reply) => {
  reply.html(<UserProfile id={req.params.userId} />)
})
```

For synchronous responses, the plugin calculates and sets the `Content-Length` header
automatically. For Suspense streaming (below), the response uses chunked transfer encoding
without a `Content-Length` header.

## Suspense streaming

When the JSX tree contains `Suspense` components, the plugin automatically switches from a
buffered response to a chunked stream. Use `req.id` as the Suspense `rid` to tie the
stream to the request.

```tsx
import { Suspense } from '@kitajs/html/suspense'

app.get('/dashboard', (req, reply) => {
  reply.html(
    <Suspense rid={req.id} fallback={<div>Loading...</div>}>
      <AsyncDashboard />
    </Suspense>
  )
})
```

No manual stream handling is required. The plugin detects Suspense usage through the
`SuspenseRoot` store and calls `resolveHtmlStream` internally.

## Error handling

The plugin supports `ErrorBoundary` components for catching async errors. Wrap async
content in an `ErrorBoundary` to handle failures gracefully.

```tsx
import { ErrorBoundary } from '@kitajs/html/error-boundary'
import { Suspense } from '@kitajs/html/suspense'

app.get('/dashboard', (req, reply) => {
  reply.html(
    <ErrorBoundary catch={(error) => <div>Error: {String(error)}</div>}>
      <Suspense rid={req.id} fallback={<div>Loading...</div>}>
        <AsyncDashboard />
      </Suspense>
    </ErrorBoundary>
  )
})
```

See the [Error Boundaries](/guide/async/error-boundaries.md) guide for details on error
handling patterns.

## Auto-doctype

By default, the plugin prepends `<!doctype html>` to responses that start with an `<html>`
tag. To disable this globally:

```tsx
await app.register(fastifyKitaHtml, { autoDoctype: false })
```

To disable it for a single request, use the exported `kAutoDoctype` symbol:

```tsx
import { kAutoDoctype } from '@kitajs/fastify-html-plugin'

app.get('/fragment', (req, reply) => {
  reply[kAutoDoctype] = false
  reply.html(<div>Just a fragment</div>)
})
```

## Compatibility

The plugin works with Fastify 4.x and 5.x.



---
url: /integrations/frameworks/express.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Express

`@kitajs/express-html-plugin` adds a `res.html()` method to Express that handles content
type headers, Suspense streaming, automatic doctype injection, and request ids for
Suspense.

## Setup

:::danger XSS Protection Required

You must install and configure `@kitajs/ts-html-plugin` before using this plugin to avoid
XSS vulnerabilities. See the [Getting Started](/guide/getting-started.md) guide for complete
setup instructions including TypeScript configuration and XSS detection.

:::


```sh [npm]
npm i @kitajs/express-html-plugin express
```

```sh [yarn]
yarn add @kitajs/express-html-plugin express
```

```sh [pnpm]
pnpm add @kitajs/express-html-plugin express
```

```sh [bun]
bun add @kitajs/express-html-plugin express
```

Register the middleware before your routes:

```tsx
import express from 'express'
import { expressKitaHtml } from '@kitajs/express-html-plugin'

const app = express()
app.use(expressKitaHtml())
```

## Sending HTML

Use `res.html()` with any JSX expression. The plugin sets the `Content-Type` header to
`text/html; charset=utf-8`.

```tsx
app.get('/', (req, res) => {
  res.html(<div>Hello World</div>)
})
```

For async components, `res.html()` accepts promises and awaits them before sending.

```tsx
app.get('/profile', (req, res) => {
  res.html(<UserProfile id={req.params.userId} />)
})
```

For synchronous responses, the plugin calculates and sets the `Content-Length` header
automatically. For Suspense streaming, the response uses chunked transfer encoding without
a `Content-Length` header.

## Suspense streaming

When the JSX tree contains `Suspense` components, the plugin automatically switches from a
buffered response to a chunked stream.

The middleware preserves any existing `req.id`. If another middleware already sets a
request id, this plugin uses that exact value and does not overwrite it.

When `req.id` is missing, the middleware generates one as `req-1`, `req-2`, `req-3`, and
so on, with the numeric part encoded in base 36.

Use the final `req.id` value as the Suspense `rid`.

```tsx
import { Suspense } from '@kitajs/html/suspense'

app.get('/dashboard', (req, res) => {
  res.html(
    <Suspense rid={req.id} fallback={<div>Loading...</div>}>
      <AsyncDashboard />
    </Suspense>
  )
})
```

No manual stream handling is required. The plugin detects Suspense usage through the
`SuspenseRoot` store and calls `resolveHtmlStream` internally.

If you already have your own request id middleware, register it before
`expressKitaHtml()`. The plugin will reuse that value for both `res.html()` and Suspense
stream detection.

To disable the built-in request id assignment completely, pass `disableRequestId: true`.
When you do this, your own middleware must populate `req.id` before any route that uses
`Suspense rid={req.id}`.

```tsx
app.use(assignCustomRequestId())
app.use(expressKitaHtml({ disableRequestId: true }))
```

## Error handling

The plugin supports `ErrorBoundary` components and `Suspense`'s `catch` prop for async
errors. Wrap async content in one of those boundaries to handle failures gracefully.

```tsx
import { ErrorBoundary } from '@kitajs/html/error-boundary'
import { Suspense } from '@kitajs/html/suspense'

app.get('/dashboard', (req, res) => {
  res.html(
    <ErrorBoundary catch={(error) => <div>Error: {String(error)}</div>}>
      <Suspense rid={req.id} fallback={<div>Loading...</div>}>
        <AsyncDashboard />
      </Suspense>
    </ErrorBoundary>
  )
})
```

See the [Error Boundaries](/guide/async/error-boundaries.md) guide for details on error
handling patterns.

## Auto-doctype

By default, the plugin prepends `<!doctype html>` to responses that start with an `<html>`
tag. To disable this globally:

```tsx
app.use(expressKitaHtml({ autoDoctype: false }))
```

To disable it for a single response, use the exported `kAutoDoctype` symbol:

```tsx
import { kAutoDoctype } from '@kitajs/express-html-plugin'

app.get('/fragment', (req, res) => {
  res[kAutoDoctype] = false
  res.html(<html lang="en" />)
})
```

## Compatibility

The plugin works with Express 4.x and 5.x.



---
url: /integrations/frameworks/elysia.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Elysia

[`@elysiajs/html`](https://elysiajs.com/plugins/html) integrates Kita Html with
[Elysia](https://elysiajs.com/). The plugin is maintained as part of the Elysia ecosystem
and uses `@kitajs/html` as its JSX runtime.

## Setup


```sh [npm]
npm i @elysiajs/html
```

```sh [yarn]
yarn add @elysiajs/html
```

```sh [pnpm]
pnpm add @elysiajs/html
```

```sh [bun]
bun add @elysiajs/html
```

```tsx
import { Elysia } from 'elysia'
import { html } from '@elysiajs/html'

const app = new Elysia()
  .use(html())
  .get('/', () => (
    <html>
      <body>
        <h1>Hello from Elysia</h1>
      </body>
    </html>
  ))
  .listen(3000)
```

The plugin automatically sets `Content-Type: text/html; charset=utf8`, prepends the
doctype, and converts JSX output into a proper response.

## Configuration

The plugin accepts options for content type, auto-detection, and doctype behavior. Refer
to the [Elysia HTML plugin documentation](https://elysiajs.com/plugins/html) for the full
configuration reference and up-to-date usage examples.

## XSS protection

The same XSS protection tooling applies. Install `@kitajs/ts-html-plugin` alongside
`@elysiajs/html` for editor diagnostics and CI scanning with `xss-scan`.



---
url: /integrations/type-extensions/htmx.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# HTMX

Kita Html provides type definitions for all [HTMX](https://htmx.org/) attributes. Once
enabled, attributes like `hx-get`, `hx-post`, `hx-trigger`, `hx-target`, and `hx-swap` are
available on all HTML elements with full autocomplete.

## Setup

Create a `src/kita.d.ts` file in your project and add the triple-slash directive:

```ts title="src/kita.d.ts"
/// <reference types="@kitajs/html/htmx.d.ts" />
```

## Usage

```tsx
<button hx-post="/api/click" hx-target="#count" hx-swap="innerHTML">
  Click me
</button>

<div id="count">0</div>
```

All standard HTMX attributes are typed, including `hx-trigger` event specifications,
`hx-swap` modifiers, and extension attributes like `hx-ext`.



---
url: /integrations/type-extensions/alpine.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Alpine.js

Kita Html provides type definitions for [Alpine.js](https://alpinejs.dev/) directives.
Once enabled, attributes like `x-data`, `x-show`, `x-on`, and `x-text` are available on
all HTML elements with autocomplete.

## Setup

Create a `src/kita.d.ts` file in your project and add the triple-slash directive. If you
already have this file for another type extension, append the new directive to it.

```ts title="src/kita.d.ts"
/// <reference types="@kitajs/html/alpine.d.ts" />
```

## Usage

```tsx
<div x-data="{ open: false }">
  <button x-on:click="open = !open">Toggle</button>
  <div x-show="open">Content</div>
</div>
```

## Combining with other extensions

Add multiple directives to the same `src/kita.d.ts` file:

```ts title="src/kita.d.ts"
/// <reference types="@kitajs/html/htmx.d.ts" />
/// <reference types="@kitajs/html/alpine.d.ts" />
```



---
url: /integrations/type-extensions/hotwire-turbo.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Hotwire Turbo

Kita Html provides type definitions for [Hotwire Turbo](https://turbo.hotwired.dev/)
elements and attributes. Once enabled, `<turbo-frame>` and `<turbo-stream>` elements are
available as valid JSX with typed attributes.

## Setup

Create a `src/kita.d.ts` file in your project and add the triple-slash directive. If you
already have this file for another type extension, append the new directive to it.

```ts title="src/kita.d.ts"
/// <reference types="@kitajs/html/hotwire-turbo.d.ts" />
```

## Usage

Turbo Frames for partial page updates:

```tsx
<turbo-frame id="messages">
  <a href="/messages/expanded">Show all expanded messages in this frame.</a>
  <form action="/messages">Show response from this form within this frame.</form>
</turbo-frame>
```

Turbo Streams for targeted DOM mutations:

```tsx
<turbo-stream action="append" target="messages">
  <template>
    <div id="message-1">New message</div>
  </template>
</turbo-stream>
```

Turbo Drive attributes for controlling navigation behavior are also typed on standard HTML
elements.



---
url: /integrations/base-templates.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Base Templates

Most applications use a shared layout with a doctype, `<head>`, and `<body>`. In Kita
Html, layouts are regular components that accept children and slot props.

## Basic layout

```tsx
import type { PropsWithChildren } from '@kitajs/html'

function Layout({ title, children }: PropsWithChildren<{ title?: string }>) {
  return (
    <>
      {'<!doctype html>'}
      <html lang="en">
        <head>
          <meta charset="UTF-8" />
          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
          <title>{title || 'My App'}</title>
        </head>
        <body>{children}</body>
      </html>
    </>
  )
}
```

The `{'<!doctype html>'}` string is concatenated before the `<html>` tag. JSX cannot
express a doctype natively, so it is inserted as a string expression.

## Slot props

For layouts with multiple content regions, use additional props for each slot.

```tsx
function Layout(
  props: PropsWithChildren<{
    title?: string
    head?: JSX.Element
    footer?: JSX.Element
  }>
) {
  return (
    <>
      {'<!doctype html>'}
      <html lang="en">
        <head>
          <meta charset="UTF-8" />
          <title>{props.title || 'My App'}</title>
          {props.head}
        </head>
        <body>
          {props.children}
          {props.footer}
        </body>
      </html>
    </>
  )
}

const page = (
  <Layout
    title="Home"
    head={
      <>
        <link rel="stylesheet" href="/style.css" />
        <script src="/app.js" />
      </>
    }
    footer={<footer>Copyright 2024</footer>}
  >
    <main>Page content</main>
  </Layout>
)
```

## Framework auto-doctype

When using `@kitajs/fastify-html-plugin` or `@kitajs/express-html-plugin`, the plugin
automatically prepends `<!doctype html>` to responses that start with an `<html>` tag.
This means you can omit the manual `{'<!doctype html>'}` string in your layout when using
either integration.



---
url: /api/index.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# API Reference

This section documents the public API of each Kita Html package.

## Core packages (auto-generated)

API documentation is generated from source code using TypeDoc. These pages update
automatically on each build.

- [@kitajs/html](/api/html/index.md)
- [@kitajs/fastify-html-plugin](/api/fastify/index.md)
- [@kitajs/express-html-plugin](/api/express/index.md)

## XSS tooling

`@kitajs/ts-html-plugin` provides XSS detection through three capabilities.

- [XSS Analysis](/api/xss-analysis.md)
- [Editor Plugin](/api/editor-plugin.md)
- [CLI Scanner](/api/scanner-cli.md)



---
url: /api/xss-analysis.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# XSS Analysis

The XSS analysis engine inspects JSX expressions at the TypeScript type level and emits
diagnostics for potentially unsafe content. This engine is shared between the editor
plugin and the CLI scanner.

## Analysis functions

### recursiveDiagnoseJsxElements

Entry point for JSX tree analysis. Walks the AST depth-first and calls
`diagnoseJsxElement` for each JSX node. Deduplicates diagnostics by source position.

### diagnoseJsxElement

Analyzes a single JSX element. Checks whether the element has the `safe` attribute,
iterates through JSX expression children, and delegates to `diagnoseExpression` for each.

Skips `<script>` elements, which are exempt from analysis.

### diagnoseExpression

Analyzes a single expression within JSX children. Unwraps parenthesized expressions,
recurses through ternary and binary expressions (checking both branches), and calls
`isSafeAttribute` to determine type safety.

### isSafeAttribute

The core type safety check. Returns `true` if the expression's TypeScript type is safe to
render without escaping. The full rule set is documented in the
[Safety Rules](/guide/xss/safety-rules.md) page.

## Diagnostic codes

The engine emits four diagnostic codes: TS88601 (unsafe expression), TS88602 (double
escaping), TS88603 (component children XSS), and TS88604 (unnecessary safe). Full
descriptions with examples are in the [Error Codes](/guide/xss/error-codes.md) page.

## Component vs element detection

The engine distinguishes native elements from components based on tag name casing.
Lowercase names are native elements where the `safe` attribute works. Uppercase names are
components where `Html.escapeHtml()` is required instead.



---
url: /api/editor-plugin.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Editor Plugin

The TypeScript language service plugin provides real-time XSS diagnostics in editors that
support TypeScript plugins.

## Configuration

Add the plugin to `tsconfig.json`:

```json
{
  "compilerOptions": {
    "plugins": [{ "name": "@kitajs/ts-html-plugin" }]
  }
}
```

The editor must use the project's local TypeScript installation. In VS Code, set
`typescript.tsdk` to `node_modules/typescript/lib` and enable
`typescript.enablePromptUseWorkspaceTsdk`.

## How it works

The plugin wraps the TypeScript language service's `getSemanticDiagnostics` method. When a
`.tsx` or `.jsx` file is analyzed, the plugin runs the XSS analysis engine over the file's
AST and appends any findings to the standard TypeScript diagnostics.

Diagnostics appear as editor squiggles with error codes TS88601 through TS88604. Each
diagnostic includes a message describing the issue and the recommended fix.

## Supported editors

Any editor with TypeScript language service plugin support works, including VS Code,
Neovim with nvim-lspconfig, and JetBrains IDEs. The plugin communicates through the
standard TypeScript language service protocol.

## Limitations

The plugin does not work with `tsgo` (the native TypeScript compiler). It requires the
standard TypeScript language server. Build-time compilation with `tsgo` is unaffected
since the plugin only runs in the language service.



---
url: /api/scanner-cli.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# CLI Scanner

The `xss-scan` command-line tool runs the XSS analysis engine against an entire project or
specific files.

## Command

```
xss-scan [options] [files...]
```

When called without file arguments, scans all files included by the project's
`tsconfig.json`. When file paths are provided, only those files are analyzed.

## Options

| Flag                   | Description                                                                    |
| ---------------------- | ------------------------------------------------------------------------------ |
| `--cwd <path>`         | Working directory. Defaults to current directory.                              |
| `-p, --project <path>` | Path to `tsconfig.json`. Defaults to `tsconfig.json` in the working directory. |
| `-s, --simplified`     | Compact single-line diagnostic output.                                         |
| `--version`            | Print version and exit.                                                        |

## Exit codes

| Code | Meaning                                   |
| ---- | ----------------------------------------- |
| 0    | No issues found.                          |
| 1    | Errors found (TS88601, TS88602, TS88603). |
| 2    | Warnings only (TS88604).                  |

## How it works

The CLI creates a TypeScript program from the specified `tsconfig.json`, loads all source
files, and runs the same analysis engine used by the editor plugin. Diagnostics are
printed to the terminal with colored output. The process exits with the appropriate code
for CI gate integration.



---
url: /api/html/classes/error-boundary.HtmlTimeout.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Class: HtmlTimeout

An error thrown by the ErrorBoundary's `timeout` property.

## Extends

- `Error`

## Constructors

### Constructor

```ts
new HtmlTimeout(message?): HtmlTimeout;
```

#### Parameters

##### message?

`string`

#### Returns

`HtmlTimeout`

#### Inherited from

```ts
Error.constructor
```

### Constructor

```ts
new HtmlTimeout(message?, options?): HtmlTimeout;
```

#### Parameters

##### message?

`string`

##### options?

`ErrorOptions`

#### Returns

`HtmlTimeout`

#### Inherited from

```ts
Error.constructor
```

## Properties

### cause?

```ts
optional cause: unknown;
```

#### Inherited from

```ts
Error.cause
```

***

### message

```ts
message: string
```

#### Inherited from

```ts
Error.message
```

***

### name

```ts
name: string
```

#### Inherited from

```ts
Error.name
```

***

### stack?

```ts
optional stack: string;
```

#### Inherited from

```ts
Error.stack
```

***

### stackTraceLimit

```ts
static stackTraceLimit: number;
```

The `Error.stackTraceLimit` property specifies the number of stack frames collected by a
stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes will
affect any stack trace captured _after_ the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture
any frames.

#### Inherited from

```ts
Error.stackTraceLimit
```

## Methods

### captureStackTrace()

```ts
static captureStackTrace(targetObject, constructorOpt?): void;
```

Creates a `.stack` property on `targetObject`, which when accessed returns a string
representing the location in the code at which `Error.captureStackTrace()` was called.

```js
const myObject = {}
Error.captureStackTrace(myObject)
myObject.stack // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with `${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames above
`constructorOpt`, including `constructorOpt`, will be omitted from the generated stack
trace.

The `constructorOpt` argument is useful for hiding implementation details of error
generation from the user. For instance:

```js
function a() {
  b()
}

function b() {
  c()
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error
  Error.stackTraceLimit = 0
  const error = new Error()
  Error.stackTraceLimit = stackTraceLimit

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b) // Neither function c, nor b is included in the stack trace
  throw error
}

a()
```

#### Parameters

##### targetObject

`object`

##### constructorOpt?

`Function`

#### Returns

`void`

#### Inherited from

```ts
Error.captureStackTrace
```

***

### isError()

```ts
static isError(error): error is Error;
```

Indicates whether the argument provided is a built-in Error instance or not.

#### Parameters

##### error

`unknown`

#### Returns

`error is Error`

#### Inherited from

```ts
Error.isError
```

***

### prepareStackTrace()

```ts
static prepareStackTrace(err, stackTraces): any;
```

#### Parameters

##### err

`Error`

##### stackTraces

`CallSite`\[]

#### Returns

`any`

#### See

[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

#### Inherited from

```ts
Error.prepareStackTrace
```

***

### reject()

```ts
static reject(): never;
```

Throws the error.

#### Returns

`never`



---
url: /api/html/functions/error-boundary.ErrorBoundary.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: ErrorBoundary()

```ts
function ErrorBoundary(props): Element
```

A component that adds an error boundary to catch any inner promise rejection.

## Parameters

### props

[`ErrorBoundaryProps`](/api/html/interfaces/error-boundary.ErrorBoundaryProps.md)

## Returns

`Element`



---
url: /api/html/functions/index.attributesToString.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: attributesToString()

```ts
function attributesToString(this, attributes): string
```

Transforms an object of attributes into a html attributes string.

**This function does not support Date objects.**

## Parameters

### this

`void`

### attributes

`object`

A record of literal values to use as attributes.

## Returns

`string`

The generated html attributes string.

## Example

```ts
;`a b="c" d="1"`
```



---
url: /api/html/functions/index.contentsToString.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: contentsToString()

```ts
function contentsToString(this, contents, escape?): Element
```

Joins raw string html elements into a single html string.

A raw html fragment is just an array of strings, this method concatenates them.

## Parameters

### this

`void`

### contents

[`Children`](/api/html/types/index.Children.md)\[]

An maybe nested array of strings to concatenate.

### escape?

`boolean`

If it should escape the contents before concatenating them. Default is `false`

## Returns

`Element`

The concatenated and escaped string of contents.



---
url: /api/html/functions/index.createElement.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: createElement()

```ts
function createElement(this, name, attributes?, ...children): Element
```

Generates a html string from the given contents.

## Parameters

### this

`void`

### name

The name of the element to create or a function that creates the element.

`string` | `Function`

### attributes?

`any`

A record of literal values to use as attributes. A property named `children` will be used
as the children of the element.

### children?

...[`Children`](/api/html/types/index.Children.md)\[]

The inner contents of the element.

## Returns

`Element`

The generated html string.



---
url: /api/html/functions/index.escape.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: escape()

```ts
function escape(this, strings, ...values): string
```

Tag function that escapes the given string pieces and interpolates the given values.
Internally it uses [`escapeHtml`](/api/html/variables/index.escapeHtml.md) to escape the
values.

## Parameters

### this

`void`

### strings

`TemplateStringsArray`

Template string.

### values

...`any`\[]

Values to interpolate.

## Returns

`string`

The escaped string.



---
url: /api/html/functions/index.Fragment.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: Fragment()

```ts
function Fragment(props): Element
```

A JSX Fragment is used to return multiple elements from a component.

## Parameters

### props

[`PropsWithChildren`](/api/html/types/index.PropsWithChildren.md)\<`Pick`\<`HtmlTag`,
`"safe"`>>

## Returns

`Element`

## Example

```tsx
// renders <div>1</div> and <div>2</div> without needing a wrapper element
const html = (
  <>
    <div>1</div>
    <div>2</div>
  </>
)

// Html.Fragment is the same as <>...</>
const html = (
  <Html.Fragment>
    <div>1</div>
    <div>2</div>
  </Html.Fragment>
)
```



---
url: /api/html/functions/index.isVoidElement.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: isVoidElement()

```ts
function isVoidElement(this, tag): boolean
```

Returns true if the element is a html void element.

## Parameters

### this

`void`

### tag

`string`

The name of the element to check.

## Returns

`boolean`

If the element is a html void element.



---
url: /api/html/functions/jsx-runtime.jsx.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: jsx()

```ts
function jsx(this, name, attributes): Element
```

Generates a html string from an attribute name of component and it's props.

This function is meant to be used by the jsx runtime and should not be called directly.

## Parameters

### this

`void`

### name

The name of the element to create or another component function

`string` | `Function`

### attributes

The props to apply to the component

#### children?

[`Children`](/api/html/types/index.Children.md)

## Returns

`Element`

The generated html string or a promise that resolves to the generated html string



---
url: /api/html/functions/jsx-runtime.jsxs.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: jsxs()

```ts
function jsxs(this, name, attributes): Element
```

Generates a html string from an attribute name of component and it's props.

This function is meant to be used by the jsx runtime and should not be called directly.

## Parameters

### this

`void`

### name

The name of the element to create or another component function

`string` | `Function`

### attributes

The props to apply to the component

#### children

[`Children`](/api/html/types/index.Children.md)\[]

## Returns

`Element`

The generated html string or a promise that resolves to the generated html string



---
url: /api/html/functions/suspense.renderToStream.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: renderToStream()

```ts
function renderToStream(html, rid?): Readable
```

Transforms a component tree who may contain `Suspense` components into a stream of HTML.

## Parameters

### html

The component tree to render or a function that returns the component tree.

`Element` | (`rid`) => `Element`

### rid?

The request id to identify the request, if not provided, a new incrementing id will be
used.

`string` | `number`

## Returns

`Readable`

## Example

```tsx
import { text } from 'node:stream/consumers'

// Prints out the rendered stream (2nd example shows with a custom id)
const stream = renderToStream((r) => <AppWithSuspense rid={r} />)
const stream = renderToStream(<AppWithSuspense rid={myCustomId} />, myCustomId)

// You can consume it as a stream
for await (const html of stream) {
  console.log(html.toString())
}

// Or join it all together (Wastes ALL Suspense benefits, but useful for testing)
console.log(await text(stream))
```

## See

[`Suspense`](/api/html/functions/suspense.Suspense.md)



---
url: /api/html/functions/suspense.resolveHtmlStream.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: resolveHtmlStream()

```ts
function resolveHtmlStream(template, requestData): Readable
```

Joins the html base template (with possible suspense's fallbacks) with the request data
and returns the final Readable to be piped into the response stream.

**This API is meant to be used by library authors and should not be used directly.**

## Parameters

### template

`Element`

The initial HTML template, possibly containing suspense fallbacks.

### requestData

[`RequestData`](/api/html/types/suspense.RequestData.md)

The request data containing the stream to write resolved content into.

## Returns

`Readable`

The same stream or a new one with the template prepended.

## Example

```tsx
const html = <RootLayout rid={rid} />
const requestData = SuspenseRoot.requests.get(rid)

if (!requestData) {
  return html
}

// This prepends the html into the stream, handling possible
// cases where the html resolved after one of its async children
return resolveHtmlStream(html, requestData)
```

## See

[`renderToStream`](/api/html/functions/suspense.renderToStream.md)



---
url: /api/html/functions/suspense.Suspense.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: Suspense()

```ts
function Suspense(props): Element
```

A component that returns a fallback while the async children are loading.

The `rid` prop is the one
[`renderToStream`](/api/html/functions/suspense.renderToStream.md) returns, this way the
suspense knows which request it belongs to.

**Warning**: Using `Suspense` without any type of runtime support will _**LEAK memory**_
and not work. Always use with `renderToStream` or within a framework that supports it.

## Parameters

### props

[`SuspenseProps`](/api/html/interfaces/suspense.SuspenseProps.md)

## Returns

`Element`



---
url: /api/html/interfaces/error-boundary.ErrorBoundaryProps.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Interface: ErrorBoundaryProps

The props for the `ErrorBoundary` component.

## See

[`ErrorBoundary`](/api/html/functions/error-boundary.ErrorBoundary.md)

## Properties

### catch

```ts
catch: Element | (error) => Element;
```

The error boundary to use if the async children throw an error.

The error will be string `timeout` if the rejection was caused by the `timeout` property.

If the timeout gets triggered, it will throw an
[`HtmlTimeout`](/api/html/classes/error-boundary.HtmlTimeout.md) error.

***

### children

```ts
children: Children
```

The async children to render as soon as they are ready.

***

### error?

```ts
optional error: object;
```

The error class we should throw if the timeout gets triggered. Defaults to
[`HtmlTimeout`](/api/html/classes/error-boundary.HtmlTimeout.md)

#### reject()

```ts
reject(): never;
```

##### Returns

`never`

***

### timeout?

```ts
optional timeout: number;
```

If we should use the catch error boundary if the children takes longer than the timeout.
Use `undefined` or `0` to disable the timeout.



---
url: /api/html/interfaces/suspense.SuspenseProps.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Interface: SuspenseProps

The props for the `Suspense` component.

## See

[`Suspense`](/api/html/functions/suspense.Suspense.md)

## Properties

### catch?

```ts
optional catch: Element | (error) => Element;
```

This error boundary is used to catch any error thrown by an async component and streams
its fallback instead.

### Undefined behaviors happens on each browser kind when the html stream is unexpected closed by the server if an error is thrown. You should always define an error boundary to catch errors.

This does not catches for errors thrown by the suspense itself or async fallback
components. Please use ErrorBoundary to catch them instead.

***

### children

```ts
children: Children
```

The async children to render as soon as they are ready.

***

### fallback

```ts
fallback: Element
```

The fallback to render while the async children are loading.

***

### rid

```ts
rid: string | number
```

The request id is used to identify the request for this suspense.



---
url: /api/html/modules/index.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Module: index

## Type Aliases

- [Children](/api/html/types/index.Children.md)
- [Component](/api/html/types/index.Component.md)
- [PropsWithChildren](/api/html/types/index.PropsWithChildren.md)

## Variables

- [e](/api/html/variables/index.e.md)
- [escapeHtml](/api/html/variables/index.escapeHtml.md)
- [~~h~~](/api/html/variables/index.h.md)
- [~~Html~~](/api/html/variables/index.Html.md)

## Functions

- [attributesToString](/api/html/functions/index.attributesToString.md)
- [contentsToString](/api/html/functions/index.contentsToString.md)
- [createElement](/api/html/functions/index.createElement.md)
- [escape](/api/html/functions/index.escape.md)
- [Fragment](/api/html/functions/index.Fragment.md)
- [isVoidElement](/api/html/functions/index.isVoidElement.md)



---
url: /api/html/modules/error-boundary.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Module: error-boundary

## Classes

- [HtmlTimeout](/api/html/classes/error-boundary.HtmlTimeout.md)

## Interfaces

- [ErrorBoundaryProps](/api/html/interfaces/error-boundary.ErrorBoundaryProps.md)

## Functions

- [ErrorBoundary](/api/html/functions/error-boundary.ErrorBoundary.md)



---
url: /api/html/modules/jsx-runtime.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Module: jsx-runtime

## Functions

- [jsx](/api/html/functions/jsx-runtime.jsx.md)
- [jsxs](/api/html/functions/jsx-runtime.jsxs.md)

## References

### Fragment

Re-exports [Fragment](/api/html/functions/index.Fragment.md)



---
url: /api/html/modules/suspense.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Module: suspense

## Interfaces

- [SuspenseProps](/api/html/interfaces/suspense.SuspenseProps.md)

## Type Aliases

- [RequestData](/api/html/types/suspense.RequestData.md)

## Variables

- [SuspenseRoot](/api/html/variables/suspense.SuspenseRoot.md)
- [SuspenseScript](/api/html/variables/suspense.SuspenseScript.md)

## Functions

- [renderToStream](/api/html/functions/suspense.renderToStream.md)
- [resolveHtmlStream](/api/html/functions/suspense.resolveHtmlStream.md)
- [Suspense](/api/html/functions/suspense.Suspense.md)



---
url: /api/html/types/index.Children.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Type Alias: Children

```ts
type Children =
  | number
  | string
  | boolean
  | null
  | undefined
  | bigint
  | Promise<Children>
  | Children[]
```



---
url: /api/html/types/index.Component.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Type Alias: Component()\<T>

```ts
type Component<T> = (this, props) => JSX.Element
```

## Type Parameters

### T

`T` = \{ }

## Parameters

### this

`void`

### props

[`PropsWithChildren`](/api/html/types/index.PropsWithChildren.md)\<`T`>

## Returns

`JSX.Element`



---
url: /api/html/types/index.PropsWithChildren.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Type Alias: PropsWithChildren\<T>

```ts
type PropsWithChildren<T> = object & T
```

## Type Declaration

### children?

```ts
optional children: Children;
```

## Type Parameters

### T

`T` = \{ }



---
url: /api/html/types/suspense.RequestData.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Type Alias: RequestData

```ts
type RequestData = object
```

Everything a suspense needs to know about its request lifecycle.

## Properties

### running

```ts
running: number
```

How many are still running

***

### sent

```ts
sent: boolean
```

If the first suspense has already resolved

***

### stream

```ts
stream: Readable
```

The stream we should write

WeakRef requires ES2021 typings (node 14+) to be installed.



---
url: /api/html/variables/index.e.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Variable: e

```ts
const e: typeof escape = escape
```

Alias of [`escape`](/api/html/functions/index.escape.md) to reduce verbosity.

## Example

```tsx
import { e } from '@kitajs/html'

;<div>{e`My name is ${user.name}!`}</div>
```



---
url: /api/html/variables/index.escapeHtml.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Variable: escapeHtml()

```ts
escapeHtml: (this, value) => string
```

Escapes a string for safe use as HTML text content. If the value is not a string, it is
coerced to one with its own `toString()` method.

If the Bun runtime is available, this function will be swapped out to Bun.escapeHTML.

## Parameters

### this

`void`

### value

`any`

The value to escape.

## Returns

`string`

The escaped string.



---
url: /api/html/variables/index.h.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# ~~Variable: h~~

```ts
const h: typeof createElement = createElement
```

## Deprecated

Here for interop with `preact` and many build systems.



---
url: /api/html/variables/index.Html.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).404

# PAGE NOT FOUND

[Take me home](/)


---
url: /api/html/variables/suspense.SuspenseRoot.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Variable: SuspenseRoot

```ts
const SuspenseRoot: object
```

The `SuspenseRoot` is a store that holds the state of all the suspense components rendered
in the server.

This was previously a global object called `SUSPENSE_ROOT`, but it was moved out of the
global scope to avoid many issues related to global state.

## Type Declaration

### autoScript

```ts
autoScript: boolean = true
```

If we should automatically stream
[`SuspenseScript`](/api/html/variables/suspense.SuspenseScript.md) before the first
suspense is rendered. If you disable this setting, you need to manually load the
[`SuspenseScript`](/api/html/variables/suspense.SuspenseScript.md) in your HTML before any
suspense is rendered. Otherwise, the suspense will not work.

#### Default

```ts
true
```

### requestCounter

```ts
requestCounter: number = 1
```

This value is used (and incremented shortly after) when no requestId is provided for
[`renderToStream`](/api/html/functions/suspense.renderToStream.md)

#### Default

```ts
1
```

### requests

```ts
requests: Map<string | number, RequestData>
```

The requests map is a map of RequestId x SuspenseData containing the stream to write the
HTML, the number of running promises and if the first suspense has already resolved.



---
url: /api/html/variables/suspense.SuspenseScript.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Variable: SuspenseScript

```ts
const SuspenseScript: string
```

Small client-side helper used to replace suspense fallbacks with streamed template
content.

As this script is the only residue of this package that is actually sent to the client,
it's important to keep it as small as possible and also include the license to avoid legal
issues.

It requires support for `<template>.content` and `Element.remove()`. IE11 is not
supported.

Pending data-sr elements are kept pending if their fallback has not yet been rendered, on
each render a try to switch all pending data-sr is attempted until no elements are
substituted.

This script must be loaded before streamed suspense replacement chunks execute. You do not
need to load it manually unless
[`SuspenseRoot.autoScript`](/api/html/variables/suspense.SuspenseRoot.md#autoscript) is
set to false.

## See

[`Suspense`](/api/html/functions/suspense.Suspense.md)



---
url: /api/fastify/interfaces/FastifyKitaHtmlOptions.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Interface: FastifyKitaHtmlOptions

Options for @kitajs/fastify-html-plugin plugin.

## Properties

### autoDoctype

```ts
autoDoctype: boolean
```

Whether to automatically add `<!doctype html>` to a response starting with <html>, if not
found.

```tsx
// With autoDoctype: true you can just return the html
app.get('/', () => <html></html>)

// With autoDoctype: false you must use rep.html
app.get('/', (req, rep) => rep.html(<html></html>)
```

#### Default

```ts
true
```



---
url: /api/fastify/variables/fastifyKitaHtml.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Variable: fastifyKitaHtml

```ts
const fastifyKitaHtml: FastifyPluginCallback<NonNullable<Partial<FastifyKitaHtmlOptions>>>
```

The `@kitajs/fastify-html-plugin` Fastify plugin.

## Example

```ts
import Fastify from 'fastify';
import { fastifyKitaHtml } from '@kitajs/fastify-html-plugin';

const app = Fastify();

// Register the plugin
app.register(fastifyKitaHtml, { autoDoctype: true });

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

app.listen({ port: 3000 });
```



---
url: /api/fastify/variables/kAutoDoctype.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Variable: kAutoDoctype

```ts
const kAutoDoctype: unique symbol
```

This gets assigned to every reply instance. You can manually change this value to `false`
if you want to "hand pick" when or when not to add the doctype.



---
url: /api/express/functions/expressKitaHtml.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Function: expressKitaHtml()

```ts
function expressKitaHtml(opts): RequestHandler
```

The `@kitajs/express-html-plugin` middleware.

It decorates `res.html()`, optionally assigns `req.id`, and enables Suspense streaming by
matching that request id with `Suspense rid={req.id}`.

## Parameters

### opts

`NonNullable`\<`Partial`\<[`ExpressKitaHtmlOptions`](/api/express/interfaces/ExpressKitaHtmlOptions.md)>>
\= `{}`

## Returns

`RequestHandler`

## Example

```ts
import express from 'express'
import { expressKitaHtml } from '@kitajs/express-html-plugin'

const app = express()

app.use(expressKitaHtml())

app.get('/', (req, res) => {
  res.html(
    <html lang="en">
      <body>
        <h1>Hello, world!</h1>
      </body>
    </html>
  )
})
```



---
url: /api/express/interfaces/ExpressKitaHtmlOptions.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Interface: ExpressKitaHtmlOptions

Options for @kitajs/express-html-plugin middleware.

## Properties

### autoDoctype

```ts
autoDoctype: boolean
```

Whether to automatically add `<!doctype html>` to a response starting with <html>, if not
found.

#### Default

```ts
true
```

***

### disableRequestId

```ts
disableRequestId: boolean
```

Whether the middleware should avoid assigning `req.id`.

Disable this if another middleware already owns request ids. When disabled, you must
ensure `req.id` is available before using `Suspense rid={req.id}`.

#### Default

```ts
false
```



---
url: /api/express/variables/kAutoDoctype.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Variable: kAutoDoctype

```ts
const kAutoDoctype: unique symbol
```

This gets assigned to every response instance. You can manually change this value to
`false` if you want to "hand pick" when or when not to add the doctype.



---
url: /api/express/index.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Kita Html

## Interfaces

- [ExpressKitaHtmlOptions](/api/express/interfaces/ExpressKitaHtmlOptions.md)

## Variables

- [kAutoDoctype](/api/express/variables/kAutoDoctype.md)

## Functions

- [expressKitaHtml](/api/express/functions/expressKitaHtml.md)



---
url: /api/fastify/index.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Kita Html

## Interfaces

- [FastifyKitaHtmlOptions](/api/fastify/interfaces/FastifyKitaHtmlOptions.md)

## Variables

- [fastifyKitaHtml](/api/fastify/variables/fastifyKitaHtml.md)
- [kAutoDoctype](/api/fastify/variables/kAutoDoctype.md)



---
url: /api/html/index.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Kita Html

## Modules

- [error-boundary](/api/html/modules/error-boundary.md)
- [index](/api/html/modules/index.md)
- [jsx-runtime](/api/html/modules/jsx-runtime.md)
- [suspense](/api/html/modules/suspense.md)



---
url: /index.md
---

You are viewing documentation for the upcoming [**v5**](https://github.com/kitajs/html/tree/next) release. For the current stable version, see the [v4 readme on npm](https://www.npmjs.com/package/@kitajs/html).# Kita Html

The fastest server-side JSX runtime

> JSX that compiles to plain strings, not a virtual DOM. No diffing, no serialization, no overhead.

[Introduction](/guide/introduction) | [Quick Start](/guide/getting-started)

## Features

- ⚡ **The Fastest JSX Runtime**: No virtual DOM means no object tree sitting in memory. Rendering a 170 KiB page runs 2-3x faster than React, Preact, and HonoJsx, while allocating half the memory, all producing identical output.
- 🛡️ **Compile-Time XSS Detection**: The TypeScript plugin flags unsafe string interpolations in your editor as you type. The xss-scan CLI blocks them in CI. Vulnerabilities caught before they reach production, with no runtime penalty on safe paths.
- 🔄 **Async and Streaming**: Async children automatically make their parents async. Suspense streams HTML via chunked transfer encoding, sending a fallback instantly and replacing it when the promise resolves.
- 📦 **Zero Dependencies**: The runtime ships with no dependencies. Small, predictable footprint for serverless functions, edge runtimes, and any environment where cold-start latency matters.
- 🎯 **Type Safe**: Complete JSX type definitions for every HTML5 element and attribute. HTMX, Alpine.js, and Hotwire Turbo type extensions are included and opt-in via triple-slash directives.
- 🔌 **Framework Agnostic**: The output is a plain string. Kita Html integrates with Fastify, Express, Hono, Bun, or any server that returns strings. If it works with strings, it works with Kita Html.