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.
npm install typescript-docs-verifierVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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`).
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.
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.
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.
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.