Setup Guide

This guide covers advanced setup scenarios, manual configuration, and troubleshooting.

Most users won’t need this. Run npx mint-tsdocs and you’re done. This guide is for special cases and understanding what happens under the hood.

TypeScript Configuration

Your tsconfig.json must generate declaration files:

tsconfig.json

{
  "compilerOptions": {
    "declaration": true,        // Required - generates .d.ts files
    "declarationMap": true,     // Optional - better IDE support
    "outDir": "./dist",         // Where .d.ts files go
    // ... other options
  }
}

Without declaration: true, API Extractor has nothing to extract.

API Extractor Configuration

When you run mint-tsdocs generate, it creates docs/.tsdocs/api-extractor.json automatically. For manual setup:

.tsdocs/api-extractor.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
  "apiReport": {
    "enabled": false
  },
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "<projectFolder>/.tsdocs/<unscopedPackageName>.api.json"
  },
  "dtsRollup": {
    "enabled": false
  }
}

Key settings:

mainEntryPointFilePath - Your main .d.ts file
docModel.enabled: true - Required for generating .api.json
Tokens like <projectFolder> are replaced automatically

Mintlify Configuration

If you don’t have Mintlify set up:

# Let mint-tsdocs do it automatically
mint-tsdocs init  # Will offer to run 'mint new' for you

# Or initialize Mintlify manually first
npx mint new

Your docs/docs.json should exist. mint-tsdocs will add navigation automatically.

Gitignore

Add to .gitignore:

.gitignore

# mint-tsdocs cache directory
docs/.tsdocs/

# Build output (optional - depends on your setup)
dist/
lib/

Do commit your generated docs in docs/reference/ - they’re part of your documentation site!

Package.json Scripts

Add convenience scripts:

package.json

{
  "scripts": {
    "build": "tsc",
    "docs": "mint-tsdocs",
    "docs:init": "mint-tsdocs init",
    "docs:dev": "cd docs && mintlify dev"
  }
}

Monorepo Setup

For workspaces with multiple packages:

Option 1: Per-Package Docs

# Initialize each package separately
cd packages/core
mint-tsdocs init

cd ../utils
mint-tsdocs init

Each package gets its own config, generates to its own output folder.

Option 2: Centralized Docs

Create a single docs folder at the root:

packages/core/mint-tsdocs.config.json

{
  "entryPoint": "./lib/index.d.ts",
  "outputFolder": "../../docs/reference/core",
  "docsJson": "../../docs/docs.json",
  "tabName": "API",
  "groupName": "Core"
}

packages/utils/mint-tsdocs.config.json

{
  "entryPoint": "./lib/index.d.ts",
  "outputFolder": "../../docs/reference/utils",
  "docsJson": "../../docs/docs.json",
  "tabName": "API",
  "groupName": "Utils"
}

Root package.json:

{
  "scripts": {
    "docs": "npm run docs -ws",
    "docs:init": "npm run docs:init -ws"
  }
}

Verification

Check your setup is working:

Build TypeScript

npm run build
ls dist/*.d.ts  # Should show .d.ts files

Run API Extractor

npx api-extractor run --local --config docs/.tsdocs/api-extractor.json
ls docs/.tsdocs/*.api.json  # Should show .api.json file

Generate Docs

mint-tsdocs generate
ls docs/reference/  # Should show .mdx files

Check Navigation

cat docs/docs.json  # Should include your API pages

Troubleshooting

No .d.ts files generated

Problem: TypeScript build succeeds but no declaration files. Solution: Add "declaration": true to tsconfig.json compilerOptions.

API Extractor can’t find entry point

Problem: Error like “Unable to load file: dist/index.d.ts” Solutions:

Verify TypeScript build succeeded: ls dist/index.d.ts
Check entryPoint in config matches your outDir
Ensure path is relative to project root

No .api.json generated

Problem: API Extractor runs but no .api.json file appears. Solutions:

Check docModel.enabled: true in api-extractor.json
Verify output path in apiJsonFilePath
Look for errors in API Extractor output

No MDX files generated

Problem: Command succeeds but docs folder is empty. Solutions:

Verify .api.json exists in docs/.tsdocs/
Check outputFolder path in config
Run with --verbose to see what’s happening
Ensure your entry point exports something public

docs.json not updated

Problem: MDX files generated but navigation unchanged. Solutions:

Verify docsJson path is correct
Check docs.json is valid JSON (no syntax errors)
Ensure file has write permissions
Look for errors in verbose output

TypeScript errors in generated docs

Problem: Mintlify shows type errors when rendering components. Solutions:

Check your TypeScript is properly compiled
Verify complex types are exported (not internal)
Use @public JSDoc tag for intended public API
Check for circular dependencies

Advanced Configuration

See Configuration Reference for all available options:

Custom templates
TSDoc tag definitions
API Extractor message levels
Bundled packages
Project folder URLs

Getting Help

Still stuck?

GitHub Issues

Report bugs or ask questions

Architecture Docs

Understand how it all works

Concepts

Guides

OpenDocs Specification

Architecture

TypeScript Configuration

API Extractor Configuration

Mintlify Configuration

Gitignore

Package.json Scripts

Monorepo Setup

Option 1: Per-Package Docs

Option 2: Centralized Docs

Verification

Troubleshooting

No .d.ts files generated

API Extractor can’t find entry point

No .api.json generated

No MDX files generated

docs.json not updated

TypeScript errors in generated docs

Advanced Configuration

Getting Help

GitHub Issues

Architecture Docs

​TypeScript Configuration

​API Extractor Configuration

​Mintlify Configuration

​Gitignore

​Package.json Scripts

​Monorepo Setup

​Option 1: Per-Package Docs

​Option 2: Centralized Docs

​Verification

​Troubleshooting

​No .d.ts files generated

​API Extractor can’t find entry point

​No .api.json generated

​No MDX files generated

​docs.json not updated

​TypeScript errors in generated docs

​Advanced Configuration

​Getting Help

GitHub Issues

Architecture Docs

TypeScript Configuration

API Extractor Configuration

Mintlify Configuration

Gitignore

Package.json Scripts

Monorepo Setup

Option 1: Per-Package Docs

Option 2: Centralized Docs

Verification

Troubleshooting

No .d.ts files generated

API Extractor can’t find entry point

No .api.json generated

No MDX files generated

docs.json not updated

TypeScript errors in generated docs

Advanced Configuration

Getting Help