Skip to main content
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:
1

Build TypeScript

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

Run API Extractor

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

Generate Docs

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

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