TypeScript Documentation Verifier

3.0.2 · active · verified Sun Apr 19

typescript-docs-verifier is a utility that systematically verifies TypeScript code examples embedded within Markdown files (such as READMEs or documentation pages) to ensure they compile without errors. It addresses the common problem of outdated or incorrect code samples in documentation by extracting `typescript` and `tsx` code blocks, replacing project-specific imports for accurate compilation context, and reporting any TypeScript compilation failures. The current stable version is 3.0.2. While there isn't a strict release cadence, major version updates indicate significant development. Key differentiators include its focus solely on compilation correctness, support for ignoring specific code blocks, and its ability to integrate into build processes. It requires Node.js version 20 or higher and TypeScript version 4.7.2 or higher as a peer dependency.

Common errors

```
Error compiling example code block X in file Y: ... (TypeScript error message, e.g., 'TS2304: Cannot find name 'myVariable'.')
```
cause A TypeScript code block within a Markdown file contains valid TypeScript compilation errors, such as syntax errors, type mismatches, or references to undeclared variables or types.

fix Carefully review the reported TypeScript error message and the corresponding code snippet in your Markdown file. Correct the TypeScript code to resolve the compilation issue, ensuring each snippet is self-contained and syntactically correct.
```
The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("{{pkg-name}}")' call instead.
```
cause Attempting to import `typescript-docs-verifier` using `require()` from a CommonJS module in a project where the library's primary entry point is configured as an ECMAScript Module (ESM) via `package.json` `exports`.

fix Update your project's module system to use ESM `import` statements if possible. Alternatively, ensure your `tsconfig.json`'s `moduleResolution` is appropriately configured (e.g., `Node16` or `NodeNext`) and that your `package.json`'s `type` field or `exports` map correctly specifies CommonJS entry points if CJS compatibility is intended.
```
TS2307: Cannot find module 'typescript-docs-verifier' or its corresponding type declarations.
```
cause The `typescript-docs-verifier` package is either not installed in the project, or TypeScript cannot resolve the module's path or type declarations due to incorrect `moduleResolution` settings in `tsconfig.json`, or issues with `package.json` `exports`.

fix First, ensure the package is correctly installed (`npm install typescript-docs-verifier`). For TypeScript projects, verify that your `tsconfig.json`'s `moduleResolution` compiler option is set to a modern value like `Node16` or `NodeNext` to correctly interpret `package.json` `exports` fields for module lookup.

Warnings

breaking Upgrading from `1.x` to `3.x` major versions introduces breaking changes, primarily due to updated Node.js and TypeScript ecosystem requirements. The package now explicitly requires `Node.js >=20` and `TypeScript >=4.7.2`.
Fix: Ensure your development and build environments are updated to Node.js v20 or newer and TypeScript v4.7.2 or newer. Review your `tsconfig.json`'s `moduleResolution` (e.g., `Node16` or `NodeNext`) and adjust module import statements to use ESM `import` syntax where appropriate.
gotcha Each TypeScript code block in Markdown files is compiled in isolation. This means that declarations (variables, types, functions) from one snippet are not carried over or accessible to subsequent snippets within the same Markdown file.
Fix: Design your Markdown code examples to be entirely self-contained within each `typescript` or `tsx` code block. If common setup is required, it must be repeated in each relevant snippet or refactored into external files that are properly imported within the snippets.
gotcha Both the command-line interface and library usage of `typescript-docs-verifier` default to locating `tsconfig.json` in the current working directory's root if the `--project` flag or `project` option is not explicitly provided. This default might not point to the `tsconfig` configured for your documentation examples.
Fix: Always explicitly specify the path to the desired `tsconfig.json` file using `--project <path/to/tsconfig.json>` in the CLI or the `project: '<path/to/tsconfig.json>'` option when using the library programmatically. Consider creating a dedicated `tsconfig.json` for documentation compilation (e.g., `tsconfig.docs.json`).
breaking Version 1.1.3 of the package included unspecified security fixes. Users still on older 1.x versions prior to 1.1.3 are exposed to potential vulnerabilities.
Fix: If your project is on the `1.x` release line, immediately upgrade to at least `typescript-docs-verifier@1.1.3`. For optimal security and features, migrate to the latest `3.x` series.

Install

npm install typescript-docs-verifier npm
yarn add typescript-docs-verifier yarn
pnpm add typescript-docs-verifier pnpm

Imports

compileSnippets
wrong:
```
const { compileSnippets } = require('typescript-docs-verifier')
```
correct:
```
import { compileSnippets } from 'typescript-docs-verifier'
```
While CommonJS `require` may technically still function due to the package's `package.json` `exports` configuration, modern Node.js environments (v20+) and TypeScript projects (v4.7.2+) are best served by ECMAScript Module (ESM) `import` statements for consistency and future compatibility.
SnippetCompilationResult
```
import { SnippetCompilationResult } from 'typescript-docs-verifier'
```
This type definition is crucial for robustly handling the structured results and potential errors returned by the `compileSnippets` function, enabling type-safe processing of compilation outcomes.

Quickstart

This code snippet demonstrates programmatic usage of the `typescript-docs-verifier` library. It processes and compiles TypeScript code blocks within specified Markdown files using a dedicated `tsconfig.json`, reporting any compilation errors encountered.

import { compileSnippets, SnippetCompilationResult } from 'typescript-docs-verifier';

const markdownFiles = ['README.md', 'docs/examples.md']; // Specify markdown files to check
const tsconfigPath = 'tsconfig.docs.json'; // Path to a tsconfig.json file for compilation context

compileSnippets({ markdownFiles, project: tsconfigPath })
  .then((results: SnippetCompilationResult[]) => {
    let hasErrors = false;
    results.forEach((result: SnippetCompilationResult) => {
      if (result.error) {
        hasErrors = true;
        console.error(
          `\nError compiling example code block ${result.index} in file ${result.file}:`
        );
        console.error(result.error.message);
        console.error('Original code:');
        console.error(result.snippet);
      }
    });
    if (hasErrors) {
      process.exit(1);
    } else {
      console.log('All TypeScript snippets compiled successfully!');
    }
  })
  .catch((error: unknown) => {
    console.error('An unexpected error occurred during snippet compilation:', error);
    process.exit(1);
  });

view raw JSON →