# Kiira By **alemtuzlak** ยท Software & Tools Type-check TypeScript and JavaScript code fences in Markdown and MDX docs against your real project API, in editor, CLI, and CI. - Source: https://github.com/AlemTuzlak/kiira - Repository: https://github.com/AlemTuzlak/kiira - Install: `npx kiira` - Tags: cli, open-source, typescript, documentation, dx, ci, vscode, monorepo - Pricing: free - Upvotes: 0 ## Features - Extracts and type-checks TS/JS/TSX/JSX code fences from .md and .mdx files - Reports errors on the exact Markdown source line, not a generated virtual file - Live squiggles in VS Code via the kiira-vscode extension (debounced, updates on save) - GitHub Actions annotations via AlemTuzlak/kiira@v1 composite action - Monorepo workspace mode: auto-resolves pnpm/npm/yarn packages without tsconfig paths - Per-glob compiler option overrides for multi-framework doc sets (React, Solid, Preact) - Fence grouping: chains multi-fence walkthroughs so later snippets see earlier declarations - --fix flag: rewrites mistagged ts fences to tsx, adds group= tags, writes jsxImportSource overrides --- ## Why it matters Kiira type-checks code fences in Markdown and MDX against your real project API, closing a gap that no standard TypeScript toolchain addresses out of the box. Docs rot silently as APIs evolve, and AI agents that write or update documentation hallucinate function names, option keys, and package subpaths with total confidence. Kiira runs the same TypeScript compiler your source code uses, so an invalid import or a misspelled prop name in a README fails the check immediately, before any reader copies it. ## The big picture Three packages share one engine. The core lives in `kiira-core`: extraction, virtual files, type-checking, and diagnostics. The CLI package (`kiira`) exposes `kiira check` for local runs and CI. The VS Code extension (`kiira-vscode`) adds live squiggles inside Markdown fences as you type, and a GitHub composite action (`AlemTuzlak/kiira@v1`) posts error annotations directly on pull requests. All three surfaces run exactly the same check, so "passes locally" is a genuine guarantee. ## How it works Install with `pnpm add -D kiira`, run `kiira init` to scaffold a `tsconfig.docs.json` and an optional `kiira.config.ts`, then run `kiira check`. Kiira reads your include globs, extracts every code fence tagged `ts`, `tsx`, `js`, or `jsx`, builds virtual TypeScript files, and resolves imports against your real project packages. Errors map back to the original Markdown line number, not to any generated file. The `--fix` flag auto-rewrites mistagged `ts` fences to `tsx`, adds `group=` tags to continuation snippets, and writes per-framework `jsxImportSource` overrides. ## Zoom in Fence metadata gives per-snippet control. Tag a fence `ignore` to skip it, `validate=none` to silence type errors, `fixture=react` to prepend a named wrapper, or `group=quickstart` to chain multiple fences so a later snippet can reference symbols declared in an earlier one. For literate docs where almost every fence builds on the previous one, set `defaultGroup: "file"` in config to implicitly group all fences in a file without tagging each one individually. ## Yes, but Relative imports (`./x`, `../x`) and unused locals are both ignored by default, because doc snippets routinely reference imaginary sibling files and declare symbols they never use. These checks are opt-in via `checkRelativeImports: true` and `checkUnusedSymbols: true` in config. Runtime validation (`validate=runtime`) is a metadata option, but type validation is the default and primary mode. ## The bottom line If your team uses AI agents to write or update docs, Kiira is not optional. It is the only tool that closes the loop between what an agent writes in a Markdown file and what TypeScript actually compiles. Unlike remark-validate-links, which checks URLs only, Kiira validates full TypeScript types against your real project API, catching hallucinated function names and wrong option keys before any reader runs the example. The MIT-licensed package is on npm and the VS Code extension is on the Marketplace; setup takes one `kiira init`. ## FAQ ### What is Kiira? Kiira is an MIT-licensed tool that extracts TypeScript and JavaScript code fences from Markdown and MDX files and type-checks them against your real project API using the TypeScript compiler. It reports errors on the exact source line in three places: a VS Code extension for live editor diagnostics, a CLI (`kiira check`) for local runs, and a GitHub composite action (`AlemTuzlak/kiira@v1`) for CI annotations. The core engine lives in the `kiira-core` package, which handles extraction, virtual file construction, type-checking, and diagnostics. ### How do I install and run Kiira? Install the CLI with `pnpm add -D kiira` (npm and yarn also work). Run `kiira init` to scaffold a `tsconfig.docs.json` and an optional `kiira.config.ts`, then run `kiira check` to validate all files matching your include globs. For the VS Code extension, install `CodeForge.kiira-vscode` from the Marketplace or Open VSX with `ext install CodeForge.kiira-vscode`. For CI, add `AlemTuzlak/kiira@v1` as a step in your GitHub Actions workflow. ### Is Kiira free or open source? Kiira is free and open source under the MIT license. The source is on GitHub at AlemTuzlak/kiira. All packages (`kiira`, `kiira-core`, `kiira-vscode`) are published to npm, and the VS Code extension is also available on Open VSX for editors other than VS Code. ### What is Kiira best for? Kiira is best for teams that use AI agents to write or update documentation, because per the README, agents hallucinate APIs with total confidence, inventing wrong function names, missing exports, and bad package subpaths. It is also well suited to open-source library maintainers who ship code examples in READMEs and want CI to catch examples that break when the API changes. Monorepo projects get particular value from workspace mode, which resolves `@your-scope/*` and third-party imports without hand-written `tsconfig` paths. ### How does Kiira compare to alternatives like remark-validate-links? remark-validate-links checks that hyperlinks in Markdown resolve to real files or anchors; it does not validate TypeScript types or JavaScript semantics inside code fences. Kiira validates full TypeScript types against your real project API, catching hallucinated function names, wrong option keys, invalid imports, and non-copy-pasteable examples. There is no overlap between the two tools: remark-validate-links handles URL integrity, Kiira handles code correctness, and they can be used together. ### What are Kiira's limitations? Relative imports (`./x`, `../x`) and unused locals are both ignored by default, because doc snippets commonly reference imaginary sibling files and declare symbols they never use; both checks require explicit opt-in via `checkRelativeImports: true` and `checkUnusedSymbols: true` in the config. Runtime validation (`validate=runtime`) exists as a metadata option per fence but type-checking is the primary and fully supported mode. Kiira also requires a `tsconfig.docs.json` or an existing `tsconfig.json` to source compiler options; without one, you must create it manually or via `kiira init`. --- [View on Analog](https://analoghq.ai/alemtuzlak/software-tools/kiira)