{"id":12230,"library":"typescript-docs-verifier","title":"TypeScript Documentation Verifier","description":"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.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/bbc/typescript-docs-verifier","tags":["javascript","block","blocks","build","check","code","compilation","compile","doc","typescript"],"install":[{"cmd":"npm install typescript-docs-verifier","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-docs-verifier","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-docs-verifier","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for TypeScript compilation. Version >=4.7.2 is specified for compatibility with modern language features and module resolution, including proper support for `package.json` `exports` fields.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"const { compileSnippets } = require('typescript-docs-verifier')","symbol":"compileSnippets","correct":"import { compileSnippets } from 'typescript-docs-verifier'"},{"note":"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.","symbol":"SnippetCompilationResult","correct":"import { SnippetCompilationResult } from 'typescript-docs-verifier'"}],"quickstart":{"code":"import { compileSnippets, SnippetCompilationResult } from 'typescript-docs-verifier';\n\nconst markdownFiles = ['README.md', 'docs/examples.md']; // Specify markdown files to check\nconst tsconfigPath = 'tsconfig.docs.json'; // Path to a tsconfig.json file for compilation context\n\ncompileSnippets({ markdownFiles, project: tsconfigPath })\n  .then((results: SnippetCompilationResult[]) => {\n    let hasErrors = false;\n    results.forEach((result: SnippetCompilationResult) => {\n      if (result.error) {\n        hasErrors = true;\n        console.error(\n          `\\nError compiling example code block ${result.index} in file ${result.file}:`\n        );\n        console.error(result.error.message);\n        console.error('Original code:');\n        console.error(result.snippet);\n      }\n    });\n    if (hasErrors) {\n      process.exit(1);\n    } else {\n      console.log('All TypeScript snippets compiled successfully!');\n    }\n  })\n  .catch((error: unknown) => {\n    console.error('An unexpected error occurred during snippet compilation:', error);\n    process.exit(1);\n  });\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.1.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error compiling example code block X in file Y: ... (TypeScript error message, e.g., 'TS2304: Cannot find name 'myVariable'.')"},{"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.","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`.","error":"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."},{"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.","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`.","error":"TS2307: Cannot find module 'typescript-docs-verifier' or its corresponding type declarations."}],"ecosystem":"npm"}