{"id":12224,"library":"typescript-api-extractor","title":"TypeScript API Extractor","description":"typescript-api-extractor is a utility designed to analyze TypeScript source code and generate structured metadata about its exported API. It leverages the TypeScript Compiler API to extract information on functions, React components, interfaces, types, enums, and their associated JSDoc comments. The package is currently in beta (v1.0.0-beta.3 as of the last release), indicating active development with potential for API changes, though it appears to have a consistent release cadence for bug fixes and new features. Its key differentiators include specialized React component analysis, robust JSDoc parsing, intelligent reference resolution for complex types, and the ability to selectively parse files or entire projects, outputting a detailed `ModuleNode` structure for programmatic consumption. This tool is particularly useful for generating documentation, schema definitions, or other forms of API introspection directly from TypeScript codebases.","status":"active","version":"1.0.0-beta.3","language":"javascript","source_language":"en","source_url":"https://github.com/michaldudak/typescript-api-extractor","tags":["javascript","typescript"],"install":[{"cmd":"npm install typescript-api-extractor","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-api-extractor","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-api-extractor","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for its core functionality as it uses the TypeScript Compiler API.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"const { loadConfig } = require('typescript-api-extractor');","symbol":"loadConfig","correct":"import { loadConfig } from 'typescript-api-extractor';"},{"note":"This is a named export. Attempting to import it as a default export will result in `undefined` or a runtime error.","wrong":"import parseFromProgram from 'typescript-api-extractor';","symbol":"parseFromProgram","correct":"import { parseFromProgram } from 'typescript-api-extractor';"},{"note":"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.","wrong":"import { ModuleNode } from 'typescript-api-extractor';","symbol":"ModuleNode","correct":"import type { ModuleNode } from 'typescript-api-extractor';"}],"quickstart":{"code":"import ts from 'typescript';\nimport { loadConfig, parseFromProgram, type ModuleNode } from 'typescript-api-extractor';\n\nasync function extractApi() {\n  // Specify the path to your tsconfig.json file\n  const tsConfigPath = './tsconfig.json';\n\n  // Load TypeScript configuration\n  let config;\n  try {\n    config = loadConfig(tsConfigPath);\n  } catch (error) {\n    console.error(`Failed to load tsconfig from ${tsConfigPath}:`, error);\n    return;\n  }\n\n  // Create a TypeScript program based on the loaded configuration\n  const program = ts.createProgram(config.fileNames, config.options);\n\n  console.log('Starting API extraction...');\n\n  // Parse all files in the project referenced by tsconfig.json\n  for (const file of config.fileNames) {\n    try {\n      const moduleInfo: ModuleNode = parseFromProgram(file, program);\n      console.log(`\\nExtracted API from ${file}:`);\n      // Log a simplified version or specific parts to avoid excessive output\n      console.log(`  Module Name: ${moduleInfo.name}`);\n      console.log(`  Exported Symbols: ${moduleInfo.exports.map(e => e.name).join(', ')}`);\n      // For full details, you would inspect moduleInfo more deeply\n    } catch (error) {\n      console.error(`Failed to parse ${file}:`, error);\n    }\n  }\n  console.log('\\nAPI extraction complete.');\n}\n\nextractApi().catch(console.error);\n","lang":"typescript","description":"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`."},"warnings":[{"fix":"Always pin to a specific version or use caret ranges cautiously. Review release notes carefully when upgrading to new beta versions.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0-beta.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0-beta.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: `tsconfig.json` not found at './tsconfig.json'"},{"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.","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.","error":"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."},{"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.","cause":"You are trying to `require()` this ES Module package from a CommonJS file or environment. `typescript-api-extractor` is an ES Module.","error":"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."}],"ecosystem":"npm"}