# typescript-docs-verifier
> Verifies that typescript examples in markdown files actually compile.
Latest version **3.0.2** (published 2026-03-02) · Apache-2.0 license · 0 weekly downloads
## Install
```sh
npm install typescript-docs-verifier
pnpm add typescript-docs-verifier
yarn add typescript-docs-verifier
bun add typescript-docs-verifier
```
Provides the command `typescript-docs-verifier`.
## Health
**Score 55/100 (C)** — status: stable.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
## Facts
| | |
|---|---|
| Version | 3.0.2 |
| Published | 2026-03-02 |
| First published | 2018-09-27 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=20 |
| Dependencies | 3 |
| Unpacked size | 60.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 22 |
| Author | BBC |
| Maintainers | paulyb |
| Keywords | block, blocks, build, check, code, compilation, compile, doc, docs, documentation, markdown, md, ts, typescript, verify |
## Links
- npm: https://www.npmjs.com/package/typescript-docs-verifier
- Repository: https://github.com/bbc/typescript-docs-verifier
- Homepage: https://github.com/bbc/typescript-docs-verifier#readme
- Issues: https://github.com/bbc/typescript-docs-verifier/issues
- npm.io page: https://npm.io/package/typescript-docs-verifier
## Dependencies (3)
- [ora](https://npm.io/package/ora.md) ^5.4.1
- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [yargs](https://npm.io/package/yargs.md) ^17.5.1
## Alternatives
- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads
## Recent versions
- 3.0.2 (latest) — 2026-03-02
- 3.0.0-beta.2 (next) — 2025-06-20
- 3.0.1 — 2025-07-18
- 3.0.0 — 2025-07-18
- 3.0.0-beta.1 — 2025-06-20
- 2.5.3 — 2025-02-14
- 2.5.2 — 2025-02-14
- 2.5.1 — 2025-02-14
- 2.5.0 — 2023-06-16
- 2.4.1 — 2023-06-16
- 2.4.0 — 2022-09-30
- 2.3.1 — 2022-09-17
- 2.3.0 — 2022-09-02
- 2.2.2 — 2022-06-10
- 2.3.0-alpha-1.0 — 2022-05-13
- … 15 more at https://npm.io/package/typescript-docs-verifier/versions
## README
# `typescript-docs-verifier`
_Verifies that typescript examples in markdown files actually compile._
[](https://www.typescriptlang.org/)
[](https://github.com/prettier/prettier)
[](https://github.com/bbc/typescript-docs-verifier)
[](https://www.npmjs.com/package/typescript-docs-verifier)
[](https://www.npmjs.com/package/typescript-docs-verifier)
[](https://www.apache.org/licenses/LICENSE-2.0)
## Why?
Ever copied a TypeScript code example from a README and found that it didn't even compile? This tool can help by verifying that all of your code examples compile correctly. And yes, the TypeScript code samples in this `README` are checked using this tool.
Inspired the by the [tut](https://github.com/tpolecat/tut) documentation compilation tool for scala.
## How it works
The selected markdown files are searched for `TypeScript` code blocks marked like this:
````Markdown
```typescript
// Some TypeScript code here
const write = 'some code';
```
````
These code blocks are extracted and any imports from the current project are replaced with an import of the `main` or `exports` from `package.json` (e.g. `import { compileSnippets } from 'typescript-docs-verifier'` would be replaced with `import { compileSnippets } from './dist/index'` for this project).
Each code snippet is compiled (but not run) and any compilation errors are reported. Code snippets must compile independently from any other code snippets in the file.
The library can also be used to type check `.tsx` files:
````Markdown
```tsx
import React from 'react'
const SomeComponent = () => (
This is a TSX component!
)
```
````
### Ignoring code blocks
Individual code blocks can be ignored by preceding them with a `` comment:
````md
```typescript
// This block won't be compiled by typescript-docs-verifier
```
````
## Script usage
```bash
node_modules/.bin/typescript-docs-verifier [--input-files ] [--project ]
```
- `--input-files` is optional and defaults to `README.md`.
- `--project` is optional and defaults to the `tsconfig.json` file in the package root.
- Any compilation errors will be reported on the console.
- The exit code is 1 if there are any compilation errors and 0 otherwise.
## Library usage
### TypeScript
```typescript
import {
compileSnippets,
SnippetCompilationResult,
} from "typescript-docs-verifier";
const markdownFiles = ["README", "examples.md"]; // defaults to 'README.md' if not provided
const tsconfigPath = "docs-tsconfig.json"; // defaults to the 'tsconfig.json' file in the package root
compileSnippets({ markdownFiles, project: tsconfigPath })
.then((results: SnippetCompilationResult[]) => {
results.forEach((result: SnippetCompilationResult) => {
if (result.error) {
console.log(
`Error compiling example code block ${result.index} in file ${result.file}`
);
console.log(result.error.message);
console.log("Original code:");
console.log(result.snippet);
}
});
})
.catch((error: unknown) => {
console.error("Error compiling TypeScript snippets", error);
});
```
### JavaScript
```javascript
const { compileSnippets } = require("typescript-docs-verifier");
const markdownFiles = ["README.md", "examples.md"]; // defaults to 'README.md' if not provided
const tsconfigPath = "docs-tsconfig.json"; // defaults to the 'tsconfig.json' file in the package root
compileSnippets({ markdownFiles, project: tsconfigPath })
.then((results) => {
results.forEach((result) => {
if (result.error) {
console.log(
`Error compiling example code block ${result.index} in file ${result.file}`
);
console.log(result.error.message);
console.log("Original code:");
console.log(result.snippet);
}
});
})
.catch((error) => {
console.error("Error compiling TypeScript snippets", error);
});
```
## Development
Run the tests:
```sh
npm install
npm test
```
## Contributing
See [these notes](./.github/CONTRIBUTING.md) for information for contributors.
## License
`typescript-docs-verifier` is available to all via the [Apache-2.0](./LICENSE) license.
Copyright © 2017 BBC
---
_Source: https://npm.io/package/typescript-docs-verifier · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._