@typhonjs-typedoc/typedoc-pkg

Provides a zero configuration and self-contained CLI to generate API documentation for Javascript / Typescript projects with TypeDoc from a well configured package.json containing Typescript type declarations. By default, typedoc-pkg will use the types export condition and fallback to types / typings properties in package.json. Alternatively, a specific export condition can be targeted for documentation generation from specific source files.

Installation:

It is recommended to install typedoc-pkg as a developer dependency in package.json as follows:

{
  "devDependencies": {
    "@typhonjs-typedoc/typedoc-pkg": "^0.1.0"
  }
}

Presently the CLI and typedoc-pkg can not be installed or used globally; this will be addressed in a future update.

typedoc-pkg has peer dependencies for Typescript 5.1+ and TypeDoc 0.26.x. It is not necessary to explicitly install either supporting package or provide tsconfig.json / typedoc.json configuration files.

Overview:

typedoc-pkg analyzes a projects package.json automatically configuring documentation generation with TypeDoc. This includes translating the entry point source files used to the actual corresponding package export names in the generated documentation. No explicit configuration of TypeDoc or Typescript is required. There is full support for sub-path exports / sub-path patterns in package.json. Additionally, typedoc-pkg can be configured to generate documentation for an entire mono-repo and all packages within.

There is a lot to unpack regarding how to set up a modern Node package for efficient distribution that includes TS declarations. At this time I'll point to the Typescript handbook description on how to set up package.json exports with the types condition. In time, I will expand the documentation and resources available about typedoc-pkg covering new patterns unlocked from modern use cases. If you have questions please open a discussion in the issue tracker. You may also stop by the TyphonJS Discord server for discussion & support.

A design goal behind typedoc-pkg is to provide flexibility and near-zero configuration, so that you may adapt and use typedoc-pkg for a variety of build and usage scenarios. There are three main ways to configure typedoc-pkg:

• CLI immediate mode.
• CLI w/ configuration file.
• Programmatically.

Example use cases:

The following examples demonstrate essential usage patterns. Each example will take into consideration a hypothetical package that has a primary export and one sub-path export. The resulting package.json exports field looks like this:

{
  "exports": {
    ".": {
      "types": "./src/main/index.d.ts",
      "import": "./src/main/index.js"
    },
    "./sub": {
      "types": "./src/sub/index.d.ts",
      "import": "./src/sub/index.js"
    }
  }
}

Note: Typescript requires the types condition to always be the first entry in a conditional block in exports.

CLI:

You may use the CLI via the command line or define a NPM script that invokes it.

To receive help about the CLI use typedoc-pkg --help. Please use it to learn about additional CLI options available.

Options
  -a, --api-link     Enable Typescript built-in library API linking; provide a colon separated string including 'es' and / or 'dom' / 'worker'.
  -c, --config       Load default 'typedoc-pkg.config.js' or provide a path to custom config.
  -d, --typedoc      Provide a path to custom 'typedoc.json' to load.
  -e, --export       Provide a specific 'package.json' export condition to parse for entry points.  (default types)
  -l, --loglevel     Specify logging level: 'verbose', 'info', 'warn', 'error', or 'off'.  (default info)
  -m, --mono-repo    When set the path must be a directory that will be scanned for all children NPM packages.
  -o, --output       Provide a directory path for generated documentation.  (default docs)
  -p, --path         Path to a file(s) to use as entry points or specific 'package.json' to load. Multiple paths may be separated by colons.
  -t, --tsconfig     Provide a path to custom 'tsconfig.json' to load.
  --dmt-nav-style    [Default Modern Theme] Modify package / module navigation paths to be 'compact', 'flat', or 'full'.  (default full)
  --link-checker     Outputs warnings about unlinked documentation reflections / types during generation.

All examples will demonstrate NPM script usage and uses JSON5 to provide additional comments.

There are two ways to use the CLI. The first is "immediate mode" where you directly supply an input / entry point. It is recommended to use the CLI immediate mode for most standard use cases.

{
  "scripts": {
    // Bare-bones generation
    "docs": "typedoc-pkg",

    // Will link all symbols from ES2023 APIs.
    "docsWithLinks": "typedoc-pkg --api-link es",

    // Will link all symbols from ES2023 & DOM APIs.
    "docsWithLinks2": "typedoc-pkg --api-link dom:es",

    // Generate combined docs for a mono-repo with all packages under `./packages`.
    "docsMono": "typedoc-pkg --path packages --mono-repo --api-link es"
  }
}

An alternate way to configure typedoc-pkg is through defining a configuration file. You may specify the --config or alias -c to load a default config defined as ./typedoc-pkg.config.js or ./typedoc-pkg.config.mjs. You may also provide a specific file path to a config after the --config option.

{
  "scripts": {
    "docs": "typedoc-pkg --config"
  }
}

The config file should be in ESM format and have a default export that provides one or a list of GenerateConfig objects.

/**
 * @type {import('@typhonjs-typedoc/typedoc-pkg').GenerateConfig[]}
 */
const config = [
   // Basic example of API linking configured automatically with the local `package.json`.
   { linkPlugins: ['es'],  },
];

export default config;

Programmatic Usage:

You may directly import generateDocs which is an asynchronous function that can be invoked with top level await.

import { generateDocs } from '@typhonjs-typedoc/typedoc-pkg';

// Generates documentation.
await generateDocs([
  // Basic example of API linking configured automatically with the local `package.json`.
  { linkPlugins: ['es'] },
]);

API documentation

Automatic Assets:

typedoc-pkg automatically searches for assets to add to the generated documentation. Presently, there is support for linking favicon.ico from ./favicon.ico or ./assets/docs/favicon.ico. In the future linking standard markdown files like CHANGELOG.md may be enabled.

Deployment Requirements:

typedoc-pkg utilizes the Default Modern Theme (DMT) which uses ES Module loading for the dynamic functionality on the frontend in browser. This requires at minimum a way to serve / host the docs. You will see a CORS error when loading file:// URLs locally. Several easy options are available for hosting the generated docs. Please see the wiki article: Webserver Required To Serve Generated Docs.

Synergies:

• typedoc-pkg utilizes the Default Modern Theme for TypeDoc. The DMT provides the additional features for typedoc-pkg to map package.json exports / sub-paths to documentation output, but also brings fit and finish to the default TypeDoc theme. There are additional configuration options for the DMT useful for package documentation. One such is dmtLinksService which makes it easy to link common services to the documentation header. It is easiest to configure that via typedocOptions in package.json. You can view this configuration as it used in typedoc-pkg itself here.

  

• typedoc-pkg leverages API linking for all Typescript built-in library declarations covering the entire modern web including ES2023 / JS, DOM, and Web Worker APIs. This is accomplished through @typhonjs-typedoc/ts-lib-docs and enabled when the --api-link CLI option is used.

• typedoc-pkg supports documentation for a variety of Javascript / Typescript projects. For ES Module / JS developers a related CLI package to easily generate Typescript declarations from ES Module source code is available via @typhonjs-build-test/esm-d-ts.

Roadmap:

• Elicit feedback from the larger developer community and improve documentation and ease of use as applicable. Please file an issue or get in touch if typedoc-pkg is not working for your project.