TypeDoc

Common errors

• Error: TypeDoc requires Node.js version >= 18.

  cause The current Node.js version running TypeDoc is older than the minimum required version 18.
  fix Upgrade your Node.js environment to version 18 or newer. Use `node -v` to check your current version and `nvm install 18 && nvm use 18` or similar tools to manage Node.js versions.

• Error: Could not find tsconfig.json

  cause TypeDoc attempts to locate a `tsconfig.json` file in the current directory or specified path, but failed to find it.
  fix Ensure a `tsconfig.json` file exists in your project root or specify its exact path using the `--tsconfig <path/to/tsconfig.json>` option.

• Error: No entry points found. Ensure that your tsconfig.json specifies the files to include, or add an 'entryPointStrategy' option.

  cause TypeDoc was unable to automatically determine which TypeScript files to process for documentation generation, often due to an empty `include` array in `tsconfig.json` or an incorrect `entryPointStrategy` for multi-package projects.
  fix Specify the files or directories to document using `--entryPoints <path/to/files>` (e.g., `src/index.ts`) or configure `entryPointStrategy` in your TypeDoc options (e.g., `typedoc --entryPointStrategy packages`).

• TypeError: Cannot read properties of undefined (reading 'getSymbolAtLocation') [or similar internal TypeScript API errors]

  cause This often indicates an incompatibility between the installed `typescript` package version and the `typedoc` package version, or a corrupted `node_modules` installation.
  fix Check that your project's `typescript` peer dependency aligns with TypeDoc's requirements. Try deleting `node_modules` and `package-lock.json` (or `pnpm-lock.yaml`), then reinstalling dependencies with `npm install` or `pnpm install`.

Warnings

• breaking TypeDoc requires Node.js version 18 or greater. Attempting to run TypeDoc with older Node.js versions will result in an error and prevent documentation generation.
  Fix: Upgrade your Node.js environment to version 18 or newer using tools like `nvm` or by installing a recent Node.js LTS version.
• gotcha TypeDoc has a specific peer dependency on `typescript` versions. Using an incompatible TypeScript version in your project (outside the `5.0.x` through `6.0.x` range for TypeDoc 0.28.x) can lead to parsing errors, incorrect type resolution, or unexpected documentation output.
  Fix: Ensure your project's `typescript` version matches one of the ranges specified in TypeDoc's `peerDependencies` (e.g., `^5.0.0`, `^5.4.0`). Update your `typescript` package if necessary.
• gotcha The `basePath` option (introduced prior to 0.28.13) was updated in version 0.28.13 to affect relative link resolution within the generated documentation. If you only intend to change the rendered base path for source links without altering link resolution, use the `displayBasePath` option instead.
  Fix: Review your `basePath` usage; if internal links are resolving unexpectedly after upgrading, consider if `displayBasePath` is the more appropriate option for your use case.
• gotcha For monorepos or projects with multiple distinct entry points, TypeDoc's automatic entry point discovery might be insufficient. Incorrect `entryPointStrategy` or missing explicit `--entryPoints` can lead to 'No entry points found' errors or incomplete documentation.
  Fix: Explicitly define entry points using `--entryPoints <path/to/files>` or configure `entryPointStrategy` (e.g., `packages`, `expand`) in your TypeDoc configuration or CLI arguments, especially for complex project structures.

Install

• npm install typedoc npm
• yarn add typedoc yarn
• pnpm add typedoc pnpm

Imports

• typedoc
  wrong:

  import { typedoc } from 'typedoc'

  correct:

  npx typedoc [options]

  TypeDoc is primarily a command-line interface (CLI) tool. The `typedoc` executable is the main entry point for most users, typically invoked via `npx` or a `package.json` script.
• Application

  import { Application } from 'typedoc'

  Used for programmatic documentation generation within a Node.js application, allowing for custom workflows and integrations with build systems. This requires manual setup of options.
• TSConfigReader

  import { TSConfigReader } from 'typedoc'

  A utility class for the programmatic API (`Application`) to automatically load TypeDoc options from a `tsconfig.json` file, mimicking CLI behavior.

Quickstart

Demonstrates how to install TypeDoc, configure a basic TypeScript project, and generate API documentation using a package script with command-line options.

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "My example application.",
  "devDependencies": {
    "typedoc": "^0.28.0",
    "typescript": "^5.0.0"
  },
  "scripts": {
    "docs": "typedoc --out docs --entryPoints src --name \"My App API Docs\" --tsconfig tsconfig.json"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*.ts"]
}

// src/index.ts
/**
 * Represents a product available in the store.
 */
export interface Product {
  /** The unique identifier of the product. */
  id: string;
  /** The name of the product. */
  name: string;
  /** The price of the product in USD. */
  price: number;
  /** A brief description of the product. */
  description?: string;
}

/**
 * Fetches a list of all available products.
 * @returns An array of `Product` objects.
 */
export function getProducts(): Product[] {
  return [
    { id: 'prod1', name: 'Laptop', price: 1200, description: 'High-performance laptop.' },
    { id: 'prod2', name: 'Mouse', price: 25 }
  ];
}

// To run:
// 1. Create the above package.json, tsconfig.json, and src/index.ts files in your project root.
// 2. Open your terminal and navigate to the project root.
// 3. Run: `npm install`
// 4. Run: `npm run docs`
// This will generate HTML documentation in the 'docs' directory.