Options reference

Options at a glance

| Option | Type | Default | Description | | --- | --- | --- | --- | | include | string[] | required | Glob patterns for the Markdown files to check. | | exclude | string[] | [] | Glob patterns to exclude from include. | | tsconfig | string | auto | Path to the tsconfig used to compile snippets. Auto-resolves tsconfig.docs.json, then tsconfig.json. | | engine | "auto" \| "classic" \| "native" | "auto" | Which TypeScript engine type-checks snippets. "auto" uses TypeScript 7's native compiler when your project has it, else the bundled one. | | packageMode | "workspace" \| "packed" | "workspace" | How package imports are resolved. | | defaultValidate | "type" \| "runtime" \| "none" | "type" | Default validation level for fences. | | defaultGroup | "none" \| "file" | "none" | Implicitly group every checkable fence in a file so later fences see earlier declarations. | | checkUnusedSymbols | boolean | false | Report unused symbols (TS6133). | | checkRelativeImports | boolean | false | Report unresolved relative imports. | | overrides | Override[] | [] | Per-glob compiler option overrides. | | externalPackages | Record<string, string> | {} | Doc-only packages to install into a hidden, isolated cache so fences that import them type-check. | | fixtures | Record<string, Fixture> | {} | Named prepend/wrap code applied to fences. | | defaultFixture | string | — | Fixture applied to every fence by default. | | languages | string[] | ["ts","tsx","js","jsx"] | Fence languages Kiira checks. |

include (required)

Glob patterns for the Markdown files Kiira checks. This is the only required option.

include: ["docs/**/*.{md,mdx}", "README.md"]

Kiira checks both .md and .mdx files out of the box — .mdx is parsed MDX-aware, so fences nested inside JSX components (<Tabs>, <Callout>, …) and files with ESM import/export are extracted correctly. A bare glob like "docs/**/*" only ever picks up .md/.mdx; other files are ignored.

--entry on the CLI overrides include for a single run.

exclude

Glob patterns removed from the set matched by include. Defaults to [].

exclude: ["docs/api/**", "**/*.generated.md"]

tsconfig

Path to the TypeScript config used when compiling your snippets. When omitted, Kiira auto-resolves tsconfig.docs.json first (so you can use docs-specific settings) and falls back to tsconfig.json.

tsconfig: "tsconfig.docs.json"

engine

Which TypeScript engine type-checks your snippets:

• "auto" (default) — use the TypeScript 7 native compiler (the Go port) when your project has typescript@>=7 installed; otherwise fall back to Kiira's bundled TypeScript. A missing or older TypeScript never breaks a check.
• "classic" — always use Kiira's bundled TypeScript, in-process. Pin this if you want checks to stay independent of the TypeScript version installed in your project.
• "native" — always use the project's TypeScript 7 native compiler. Errors if the project has no typescript@>=7.

engine: "auto"

The diagnostics are the same either way. Two things to know about "native":

• It loads TypeScript from your project (Kiira bundles a v5 for the classic path), so typescript@>=7 must be installed alongside Kiira.
• The native compiler runs as a subprocess, which adds start-up overhead per check. For the small snippets in docs the classic in-process engine is usually faster, so "auto" only switches to native when your project is already on TypeScript 7.
• Editor code-fixes (the VS Code lightbulb) always use the bundled TypeScript — the native compiler has no code-fix API yet. Diagnostics are unaffected.

packageMode

How Kiira resolves package imports referenced in your snippets:

• "workspace" (default) — discovers your monorepo's workspaces and resolves package names to their source. See Monorepos.
• "packed" — resolves against the packed/published form of the package.

packageMode: "workspace"

defaultValidate

The default validation level applied to every fence (override per-fence with the validate= token):

• "type" (default) — full TypeScript type-checking.
• "runtime" — runtime-oriented validation.
• "none" — skip validation for that fence.

defaultValidate: "type"

defaultGroup

How fences in a single file are grouped when you haven't tagged them with group=:

• "none" (default) — each fence is its own isolated module (the original behavior).
• "file" — every checkable fence in a file shares one implicit group, concatenated in document order, so a later fence sees declarations from earlier ones.

defaultGroup: "file"

"file" is built for literate docs — pages where one fence sets up imports and values and later fences build on them — collapsing the TS2304 Cannot find name noise without hand-tagging every fence. An explicit group= on a fence always wins, and group=none detaches a single fence (handy when two fences in the same file each redeclare the same name). You can also set defaultGroup per-glob via overrides.

checkUnusedSymbols

When true, Kiira reports unused symbols (TypeScript's TS6133). Defaults to false because docs snippets frequently declare imports or variables for illustration without using them.

checkUnusedSymbols: false

checkRelativeImports

When true, Kiira reports unresolved relative imports (e.g. ./utils). Defaults to false, because relative paths in docs often point at files that don't exist in the docs project. Bare package imports (e.g. your-lib) are always checked regardless of this setting.

checkRelativeImports: false

overrides

Per-glob compiler option overrides — for example, setting a different jsxImportSource for docs that target another framework. Kiira runs a separate TypeScript program per distinct option set. See Per-glob overrides.

overrides: [
  {
    include: ["docs/solid/**/*.mdx"],
    jsxImportSource: "solid-js",
  },
]

externalPackages

Packages your docs import but your project does not depend on — a competitor library shown in a comparison, or a third-party tool shown in an integration example. Without them installed, those imports fail to resolve and the fence reports TS2307: Cannot find module.

externalPackages is a Record<string, string> of package name → version range. Kiira installs them into a hidden, isolated cache (node_modules/.kiira) purely for type-checking — your real package.json and node_modules are never touched.

externalPackages: {
  langchain: "^0.3.0",
  zod: "^3",
}

• The install runs on kiira check with your project's package manager (detected from the lockfile), and re-installs only when the list changes — otherwise it's a no-op.
• The install runs with --ignore-scripts: Kiira only needs types on disk to type-check, so dependency build/postinstall scripts are never executed. This keeps doc-only packages from running install-time code, and avoids package managers that gate build scripts (e.g. pnpm) failing the install.
• Declarations on overrides (overrides[].externalPackages) are merged into the same install and resolve globally (one version per package name).
• Remove the cache any time with rm -rf node_modules/.kiira.

fixtures

Named blocks of code that Kiira can prepend to (or wrap around) a fence before compiling it — useful for providing shared imports or setup so individual snippets stay focused. Reference a fixture per-fence with the fixture= token.

fixtures: {
  setup: {
    type: "prepend", content: `import { createApp } from "your-lib"\nconst app = createApp()`,
  },
}

defaultFixture

The name of a fixture applied to every fence by default (still overridable per-fence):

defaultFixture: "setup"

languages

The fence languages Kiira checks. Defaults to all four:

languages: ["ts", "tsx", "js", "jsx"]

Narrow this if you only want to check, say, TypeScript fences.