Skip to content
Reference

JSX renderer

Reference for kubb/jsx, backed by @kubb/renderer-jsx: the jsxRenderer, the tsconfig setup, and the props of every built-in component.

kubb/jsx lets you write a generator's files as JSX instead of ast.factory node builders.

Renderers

A renderer turns what a generator returns into FileNodes. Set renderer: jsxRenderer on the generator. Leave renderer unset or null when it returns FileNodes from ast.factory.

Generator returns JSXjsxRendererFileNode listParser, such as parserTsGenerated file
jsxRenderer does not use React. Components run once as plain functions, so hooks, suspense, and class components do not work.

For another template format, pass createRenderer from kubb/kit a factory that returns { render, files, [Symbol.dispose] }.

Setup

Point tsconfig.json at the kubb/jsx runtime instead of React:

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

jsxRenderer()

jsxRenderer() returns a renderer. Call render with a JSX element, then read files.

render.tsx
import { File, Function, Type, jsxRenderer } 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

Inside a code component or File.Source, <br /> adds a line break.

Core

File

With baseName and path, File declares a generated file. Without them, it renders its children inline. Text directly in a File, outside File.Source, throws.

PropTypeDescription
baseName`${string}.${string}`The file name, such as petStore.ts
pathstringThe full output path
meta?object | nullMetadata for plugins to read
banner?string | nullText before the source blocks
footer?string | nullText after the source blocks
copy?string | nullAn absolute path of a file to copy into the output
children?KubbReactNodeThe file's sources, imports, and exports
<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

A block of source text in the enclosing File.

PropTypeDescription
name?string | nullNames the source for deduplication and barrels
isExportable?boolean | nullMarks an exported declaration. The text still needs its own export.
isIndexable?boolean | nullIncludes the source in barrels
isTypeOnly?boolean | nullMarks a type-only export
inline?{ expression: string } | nullLets importing files use expression in place of the name
pointer?stringThe input location, such as #/components/schemas/Pet
children?KubbReactNodeThe source text

See Inline sources for copy and inline.

File.Import

An import at the top of the enclosing File.

PropTypeDescription
namestring | Array<string | { propertyName: string; name?: string }>A string for a default or namespace import, or an array of named imports
pathstringThe module to import from
root?string | nullThe file path the import is relative to
isTypeOnly?boolean | nullEmits import type
isNameSpace?boolean | nullEmits import * as name
<File.Import name={['useState']} path="react" />
// import { useState } from 'react'

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

File.Export

An export at the top of the enclosing File.

PropTypeDescription
name?string | Array<string> | nullThe names to export, or none for a wildcard export
pathstringThe module to export from
isTypeOnly?boolean | nullEmits export type
asAlias?boolean | nullEmits export * as name
<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 inside a File.Source. Each takes export?: boolean | null to add export, and JSDoc?: { comments?: Array<string | undefined> } | null for a JSDoc block.

Const

A const declaration, with the children as the initializer.

PropTypeDescription
namestringThe name
type?string | nullThe annotation after const name:
asConst?boolean | nullAdds as const after the initializer
<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

A function declaration, with the children as the body.

PropTypeDescription
namestringThe name
default?boolean | nullAdds default after export
async?boolean | nullAdds async and wraps returnType in Promise<…>
params?string | nullThe parameter list
generics?string | Array<string> | nullThe type parameters. An array joins with commas.
returnType?string | nullThe return type after :
<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

An arrow function in a const. It takes every Function prop, plus singleLine?: boolean | null for an expression body without braces.

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

Type

A type alias, with the children as the type. name must start with an uppercase letter, or Type throws.

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

Markdown

Each Markdown component emits its own source block, so put it directly in a File, not a File.Source. Name the file .md so parserMd prints it.

docs.tsx
import { Callout, File, Frontmatter, Heading, List, Paragraph, jsxRenderer } 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 generate --watch.</Callout>
  </File>,
)

Callout

A GitHub alert in > [!TYPE] syntax.

PropTypeDescription
type'tip' | 'note' | 'important' | 'warning' | 'caution'The alert kind, printed in uppercase
title?string | nullText on the marker line
childrenstringThe body. Each line gets a > prefix.
<Callout type="warning" title="Heads up">Breaking change in v6.</Callout>
// > [!WARNING] Heads up
// > Breaking change in v6.

Frontmatter

YAML frontmatter between --- fences, as the first child of the File. An empty data prints nothing.

PropTypeDescription
dataRecord<string, unknown>The object to write as YAML

Heading

An ATX heading, such as ## Installation for level={2}.

PropTypeDescription
level1 | 2 | 3 | 4 | 5 | 6The number of # characters
childrenstringThe heading text

List

A list with one item per line.

PropTypeDescription
itemsReadonlyArray<string>The items
ordered?boolean | nullNumbers the items 1., 2., and so on. Default: a - list.

Paragraph

A paragraph. Inline Markdown passes through as written.

PropTypeDescription
childrenstringThe paragraph text

JSX

Jsx

Embeds a raw JSX string, fragments included, such as a component body in a Function. The children must be one plain string.

PropTypeDescription
children?stringThe JSX source, written as is
<Function name="MyComponent" export>
  <Jsx>{'return (\n  <>\n    <div>Hello</div>\n  </>\n)'}</Jsx>
</Function>

Less common cases

Inline sources

When a plugin writes a File with copy or a File.Source with inline, Kubb copies or absorbs it instead of printing it.

  • copy on File is an absolute path to copy into the output, through the parser's copy hook if it has one. Its sources count for barrels but are not printed.
  • inline.expression on File.Source is the right-hand side of the declaration.
  • Kubb does not write a file whose sources are all inline. Files that import it get the expression and its imports.
<File.Source name="AddPetStatus200" isTypeOnly isExportable inline={{ expression: 'Pet' }}>
  {`export type AddPetStatus200 = Pet`}
</File.Source>

The parser's inline member (InlineLanguage) runs before barrels. It finds names (replaceIdentifiers) and makes a definition safe to put where a name was (wrap). Only files of a parser with inline, such as parserTs, absorb inline sources.

With the kubb/jsx setup, .tsx files load jsx-runtime and jsx-dev-runtime from kubb/jsx.