JSX renderer#

kubb/jsx is Kubb's JSX-based renderer, an alternative to building files with the ast.factory node builders from kubb/kit. It provides a JSX runtime and a set of built-in components so a generator can emit files and markdown through JSX.

Setup#

Point your tsconfig.json at the kubb/jsx runtime so JSX syntax compiles against its components instead of React's:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "kubb/jsx"
  }
}

With that in place, .tsx files in the plugin resolve jsx-runtime and jsx-dev-runtime from kubb/jsx automatically.

jsxRenderer()#

jsxRenderer creates a renderer instance with two members, render and files. Call render with a JSX element, then read the generated files back off files.

import { jsxRenderer } from 'kubb/jsx'
import { File, Function, Type } from 'kubb/jsx'

const renderer = jsxRenderer()

await renderer.render(
  <File baseName="petStore.ts" path="src/gen/petStore.ts">
    <File.Source>
      <Type name="Pet">{'{ id: number; name: string }'}</Type>
      <Function name="getPet" async>
        {"return fetch('/pets')"}
      </Function>
    </File.Source>
  </File>,
)

const files = renderer.files

Built-in components#

kubb/jsx groups its built-in components into four sets:

• Core components (File, File.Source, File.Import, File.Export) declare an output file and the imports, exports, and source blocks that make it up.
• JavaScript components (Const, Function, Function.Arrow, Type) emit TypeScript declarations.
• Markdown components (Callout, Frontmatter, Heading, List, Paragraph) emit markdown.
• Jsx embeds a raw JSX string in the generated output.

Core#

File is the container. Its members File.Source, File.Import, and File.Export attach source blocks, imports, and exports to it.

File {#file}#

Declares a generated output file. Pass both baseName and path to register a file entry. Omit both to render the children inline without creating a file.

<File baseName="petStore.ts" path="src/models/petStore.ts">
  <File.Source name="Pet" isExportable isIndexable>
    {`export type Pet = { id: number; name: string }`}
  </File.Source>
</File>

File.Source {#file-source}#

Marks a block of source text that belongs to the enclosing File. The children are the source string.

<File.Source name="PetId" isTypeOnly isExportable>
  {`export type PetId = string`}
</File.Source>

File.Import {#file-import}#

Declares an import for the enclosing File. The renderer emits it at the top of the generated file.

<File.Import name={['useState']} path="react" />
// import { useState } from 'react'

<File.Import name="z" path="zod" isNameSpace />
// import * as z from 'zod'

File.Export {#file-export}#

Declares an export for the enclosing File. The renderer emits it at the top of the generated file.

<File.Export name={['Pet']} path="./models/petStore" />
// export { Pet } from './models/petStore'

<File.Export path="./models/petStore" isTypeOnly />
// export type * from './models/petStore'

JavaScript#

The JavaScript components emit TypeScript declarations. Nest them inside a File.Source so the renderer writes them into a .ts file.

Const {#const}#

Generates a TypeScript constant declaration. The children are the initializer expression.

<Const export name="petSchema" type="z.ZodType<Pet>">
  {`z.object({ id: z.number() })`}
</Const>
// export const petSchema: z.ZodType<Pet> = z.object({ id: z.number() })

Function {#function}#

Generates a TypeScript function declaration. The children are the function body.

<Function export async name="getPet" generics={['TData = Pet']} params="petId: string" returnType="TData">
  {'return client.get("/pets/" + petId)'}
</Function>
// export async function getPet<TData = Pet>(petId: string): Promise<TData> { … }

Function.Arrow {#function-arrow}#

Generates an arrow function assigned to a const. Takes every Function prop plus singleLine.

<Function.Arrow export name="double" params="n: number" returnType="number" singleLine>
  {`n * 2`}
</Function.Arrow>
// export const double = (n: number): number => n * 2

Type {#type}#

Generates a TypeScript type alias. The children are the type expression. name must start with an uppercase letter or the component throws.

<Type export name="PetId">
  {`string | number`}
</Type>
// export type PetId = string | number

Markdown#

The markdown components each emit their own source block, so they go directly inside a File rather than a File.Source. Render the file with parserMd so it is written as markdown.

import { jsxRenderer } from 'kubb/jsx'
import { File, Frontmatter, Heading, Paragraph, List, Callout } from 'kubb/jsx'

const renderer = jsxRenderer()

await renderer.render(
  <File baseName="pets.md" path="src/docs/pets.md">
    <Frontmatter data={{ title: 'Pets', layout: 'doc' }} />
    <Heading level={2}>Pets</Heading>
    <Paragraph>{'A pet object with an id and a name.'}</Paragraph>
    <List items={['id: number', 'name: string']} />
    <Callout type="tip">Keep the generator hot with kubb start --watch.</Callout>
  </File>,
)

Callout {#callout}#

Renders a GitHub-style alert using the > [!TYPE] blockquote syntax.

<Callout type="warning" title="Heads up">Breaking change in v6.</Callout>
// > [!WARNING] Heads up
// > Breaking change in v6.

Frontmatter {#frontmatter}#

Emits a YAML frontmatter envelope at the top of a markdown file. Place it as the first child of the File.

<Frontmatter data={{ title: 'Pets', layout: 'doc' }} />
// ---
// title: Pets
// layout: doc
// ---

Heading {#heading}#

Renders an ATX-style markdown heading.

<Heading level={2}>Installation</Heading>
// ## Installation

List {#list}#

Renders a markdown list, one entry per line.

<List ordered items={['First', 'Second']} />
// 1. First
// 2. Second

Paragraph {#paragraph}#

Renders a markdown paragraph. Inline markdown passes through verbatim.

<Paragraph>{'A pet object with `id` and `name` fields.'}</Paragraph>

JSX#

Jsx {#jsx-component}#

Embeds a raw JSX string in the generated source, including fragments. Use it inside a Function to emit a component body. The children must be a plain string.

<Function name="MyComponent" export>
  <Jsx>{'return (\n <>\n <div>Hello</div>\n </>\n)'}</Jsx>
</Function>

See also#

• Kit API for defineGenerator's renderer field and the ast.factory alternative to JSX
• Creating plugins for how a generator wires a renderer into its output
• Kit API: rendering for how jsxRenderer sits next to createRenderer