# @microsoft/tsdoc-config

> A loader for the tsdoc.json file

Latest version **0.18.1** (published 2026-02-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @microsoft/tsdoc-config
pnpm add @microsoft/tsdoc-config
yarn add @microsoft/tsdoc-config
bun add @microsoft/tsdoc-config
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high maintenance score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.18.1 |
| Published | 2026-02-25 |
| First published | 2019-11-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 103.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4965 |
| Maintainers | microsoft1es, microsoft-oss-releases, odspnpm |
| Keywords | TypeScript, documentation, doc, comments, JSDoc, parser, standard |

## Links

- npm: https://www.npmjs.com/package/@microsoft/tsdoc-config
- Repository: https://github.com/microsoft/tsdoc
- Homepage: https://tsdoc.org/
- Issues: https://github.com/microsoft/tsdoc/issues
- npm.io page: https://npm.io/package/@microsoft/tsdoc-config

## Dependencies (4)

- [ajv](https://npm.io/package/ajv.md) ~8.18.0
- [jju](https://npm.io/package/jju.md) ~1.4.0
- [resolve](https://npm.io/package/resolve.md) ~1.22.2
- [@microsoft/tsdoc](https://npm.io/package/@microsoft/tsdoc.md) 0.16.0

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 0.18.1 (latest) — 2026-02-25
- 0.18.0 — 2025-11-11
- 0.17.1 — 2024-11-23
- 0.17.0 — 2024-05-28
- 0.16.2 — 2022-09-14
- 0.16.1 — 2022-04-09
- 0.16.0 — 2022-04-07
- 0.15.2 — 2021-04-20
- 0.15.1 — 2021-04-19
- 0.15.0 — 2021-04-16
- 0.14.0 — 2021-01-22
- 0.13.9 — 2020-12-03
- 0.13.8 — 2020-12-03
- 0.13.7 — 2020-11-30
- 0.13.6 — 2020-09-04
- … 8 more at https://npm.io/package/@microsoft/tsdoc-config/versions

## README

# @microsoft/tsdoc-config

**TSDoc** is a proposal to standardize the doc comments used in [TypeScript](http://www.typescriptlang.org/)
source files.  The main package [`@microsoft/tsdoc`](https://www.npmjs.com/package/@microsoft/tsdoc) implements
the TSDoc parser.  The `@microsoft/tsdoc-config` package is an optional add-on for loading the **tsdoc.json**
file format that enables users to define custom TSDoc tags.  (This functionality was moved to its own package
because it requires external dependencies such as NodeJS and `ajv`, whereas the main package is fully self-contained.)

For more information about TSDoc, please visit the project website:

https://tsdoc.org


## Creating config files

The **tsdoc.json** file is optional.  When used, it is expected to be found in the same folder as
the **tsconfig.json** file for a project.  The loader looks for it by walking upwards in the directory tree
until it finds a folder containing **tsconfig.json** or **package.json**, and then it attempts to load
**tsdoc.json** from that location.

The **tsdoc.json** file conforms to the [tsdoc.schema.json](
https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json) JSON schema.  It defines tags using
similar fields as the
[TSDocTagDefinition](https://github.com/microsoft/tsdoc/blob/main/tsdoc/src/configuration/TSDocTagDefinition.ts)
API used by `TSDocParser` from `@microsoft/tsdoc`.

Here's a simple example:

**tsdoc.json**
```js
{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "tagDefinitions": [
    {
      "tagName": "@myTag",
      "syntaxKind": "modifier"
    }
  ]
}
```

If you want to define custom tags in one place and share them across multiple projects, the `extends` field specifies
a list of paths that will be mixed in with the current file:

**tsdoc.json**
```js
{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": [
    "my-package/dist/tsdoc-base.json",
    "./path/to/local/file/tsdoc-local.json"
  ]
}
```

> NOTE: The `extends` paths are resolved using NodeJS module resolution, so local paths must begin with `./` to avoid
> being interpreted as an NPM package name.


## API Usage

The code sample below illustrates how to invoke the `@microsoft/tsdoc-config` API to load a
**tsdoc.json** file:

```ts
import * as path from 'path';
import { TSDocParser, TSDocConfiguration } from '@microsoft/tsdoc';
import { TSDocConfigFile } from '@microsoft/tsdoc-config';

// Sample source file to be parsed
const mySourceFile: string = 'my-project/src/example.ts';

// Load the nearest config file, for example `my-project/tsdoc.json`
const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.dirname(mySourceFile));
if (tsdocConfigFile.hasErrors) {
  // Report any errors
  console.log(tsdocConfigFile.getErrorSummary());
}

// Use the TSDocConfigFile to configure the parser
const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
tsdocConfigFile.configureParser(tsdocConfiguration);
const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration);
```

---
_Source: https://npm.io/package/@microsoft/tsdoc-config · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._