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.
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.
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.
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
.
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;
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'] },
]);
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.
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.
-
typedoc-pkg
utilizes the Default Modern Theme for TypeDoc. The DMT provides the additional features fortypedoc-pkg
to mappackage.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 isdmtLinksService
which makes it easy to link common services to the documentation header. It is easiest to configure that viatypedocOptions
inpackage.json
. You can view this configuration as it used intypedoc-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.
- 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.