TypeScript API Extractor

Common errors

• Error: `tsconfig.json` not found at './tsconfig.json'

  cause The `loadConfig` function was called with an incorrect or non-existent path to the `tsconfig.json` file, or the file does not have read permissions.
  fix Verify the path to your `tsconfig.json` is correct and accessible from where the script is run. Use an absolute path or a relative path correctly pointing to the file. Ensure the file exists and is readable.

• SyntaxError: Named export 'parseFromProgram' not found. The requested module 'typescript-api-extractor' is a CommonJS module, which may not support all module.exports as named exports.

  cause Attempting to use ES module `import` syntax (`import { parseFromProgram } from 'typescript-api-extractor';`) in a CommonJS context or when the environment is incorrectly configured to treat the package as CommonJS, or a bundler isn't transpiling correctly.
  fix Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`), or compile your TypeScript with an ES Module target. If sticking to CommonJS, you might need to use `const { parseFromProgram } = await import('typescript-api-extractor');` (dynamic import) or verify the package's CommonJS output (if any) and adjust your `require` statement accordingly, though ESM is the primary target.

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/typescript-api-extractor/dist/index.js from ... is not supported. Instead change the require of index.js in ... to a dynamic import() which is available in all CommonJS modules.

  cause You are trying to `require()` this ES Module package from a CommonJS file or environment. `typescript-api-extractor` is an ES Module.
  fix Migrate your consuming code to use ES Module `import` syntax or change your CommonJS `require()` call to a dynamic `import()`: `const { loadConfig } = await import('typescript-api-extractor');` within an `async` function.

Warnings

• gotcha The package is currently in beta (v1.0.0-beta.3). While functional, the API may undergo changes in future minor or major releases before a stable v1.0.0 is reached. Users should anticipate potential breaking changes.
  Fix: Always pin to a specific version or use caret ranges cautiously. Review release notes carefully when upgrading to new beta versions.
• breaking Older versions of `typescript-api-extractor` (prior to v1.0.0-beta.3) may not correctly recognize `memo`'d components when used with TypeScript 6, leading to incomplete or incorrect API extraction for such components.
  Fix: Upgrade to `typescript-api-extractor@1.0.0-beta.3` or newer to ensure compatibility and correct recognition of `memo`'d components with TypeScript 6.
• gotcha The package requires Node.js version 22 or newer. Running on older Node.js versions will result in an `Unsupported Engine` error or runtime failures.
  Fix: Ensure your development and build environments use Node.js v22 or higher. Use a Node Version Manager (e.g., `nvm` or `volta`) to manage Node.js versions.

Install

• npm install typescript-api-extractor npm
• yarn add typescript-api-extractor yarn
• pnpm add typescript-api-extractor pnpm

Imports

• loadConfig
  wrong:

  const { loadConfig } = require('typescript-api-extractor');

  correct:

  import { loadConfig } from 'typescript-api-extractor';

  The package is primarily designed for ESM usage, as indicated by the Node.js engine requirement and usage examples. CommonJS `require` might lead to issues or require specific bundler configurations.
• parseFromProgram
  wrong:

  import parseFromProgram from 'typescript-api-extractor';

  correct:

  import { parseFromProgram } from 'typescript-api-extractor';

  This is a named export. Attempting to import it as a default export will result in `undefined` or a runtime error.
• ModuleNode
  wrong:

  import { ModuleNode } from 'typescript-api-extractor';

  correct:

  import type { ModuleNode } from 'typescript-api-extractor';

  While `import { ModuleNode } from 'typescript-api-extractor';` might technically work at runtime, `ModuleNode` is primarily a type definition. Using `import type` is a best practice for type-only imports, improving clarity and enabling bundler optimizations like tree-shaking for types.

Quickstart

Demonstrates how to load a `tsconfig.json`, create a TypeScript `Program` instance, and then iterate through all project files to extract and log their API definitions using `parseFromProgram`.

import ts from 'typescript';
import { loadConfig, parseFromProgram, type ModuleNode } from 'typescript-api-extractor';

async function extractApi() {
  // Specify the path to your tsconfig.json file
  const tsConfigPath = './tsconfig.json';

  // Load TypeScript configuration
  let config;
  try {
    config = loadConfig(tsConfigPath);
  } catch (error) {
    console.error(`Failed to load tsconfig from ${tsConfigPath}:`, error);
    return;
  }

  // Create a TypeScript program based on the loaded configuration
  const program = ts.createProgram(config.fileNames, config.options);

  console.log('Starting API extraction...');

  // Parse all files in the project referenced by tsconfig.json
  for (const file of config.fileNames) {
    try {
      const moduleInfo: ModuleNode = parseFromProgram(file, program);
      console.log(`\nExtracted API from ${file}:`);
      // Log a simplified version or specific parts to avoid excessive output
      console.log(`  Module Name: ${moduleInfo.name}`);
      console.log(`  Exported Symbols: ${moduleInfo.exports.map(e => e.name).join(', ')}`);
      // For full details, you would inspect moduleInfo more deeply
    } catch (error) {
      console.error(`Failed to parse ${file}:`, error);
    }
  }
  console.log('\nAPI extraction complete.');
}

extractApi().catch(console.error);