Getting Started

    Estimated reading time: 2 minutes

    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.

    npm
    yarn
    pnpm
    bun
    npm i @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.

    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:

    .vscode/settings.json
    {
  "js/ts.tsdk.path": "node_modules/typrscript/lib",
  "js/ts.tsdk.promptToUseWorkspaceVersion": 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.

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

    Verification

    Write the following in a .tsx file:

    const 
    const html: JSX.Element
    html     = <
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >{String.name}</
    JSX.IntrinsicElements.div: JSX.HtmlTag
    div    >
    Content may introduce an XSS vulnerability and must be marked with the `safe` attribute.
See https://html.kitajs.org/TS88601
    <div>String</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.