pantheon-ai/typescript-advanced

Comprehensive TypeScript guidance covering compiler configuration, advanced types, utility types, type guards, strict mode workflows, and documentation patterns; use when configuring tsconfig, designing complex generics, making illegal states unrepresentable, fixing type errors, or writing testable and maintainable type-safe APIs.

Overall
score

99%

Review — 99%

Does it follow best practices?

Validation — 10 / 11 Passed

Validation for skill structure

TypeDoc Configuration and Setup

Name: pantheon-ai/typescript-advanced
Author: pantheon-ai

TypeDoc generates API documentation from TypeScript source code and JSDoc comments. It produces clean, searchable HTML or Markdown documentation.

Installation

npm install --save-dev typedoc

# Optional plugins
npm install --save-dev typedoc-plugin-markdown
npm install --save-dev typedoc-plugin-missing-exports

Basic Configuration

Create typedoc.json in your project root:

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeInternal": true,
  "readme": "README.md",
  "plugin": []
}

Configuration Options

Entry Points

Single entry point:

{
  "entryPoints": ["src/index.ts"]
}

Multiple entry points:

{
  "entryPoints": [
    "src/index.ts",
    "src/auth/index.ts",
    "src/database/index.ts"
  ]
}

Glob patterns:

{
  "entryPointStrategy": "expand",
  "entryPoints": ["src/**/*.ts"]
}

Output Configuration

{
  "out": "docs/api",
  "theme": "default",
  "name": "My Project API",
  "includeVersion": true,
  "disableSources": false,
  "sourceLinkTemplate": "https://github.com/user/repo/blob/{gitRevision}/{path}#L{line}"
}

Visibility Control

{
  "excludePrivate": true,        // Exclude private members
  "excludeProtected": false,     // Include protected members
  "excludeInternal": true,       // Exclude @internal tagged items
  "excludeExternals": true,      // Exclude external modules
  "excludeNotDocumented": false  // Include items without docs
}

Module Organization

{
  "categorizeByGroup": true,     // Group by @group tags
  "defaultCategory": "Other",    // Default category name
  "categoryOrder": [             // Category display order
    "Core",
    "Authentication",
    "Database",
    "*"
  ]
}

Using @group and @category Tags

Organize documentation with JSDoc tags:

/**
 * @group Authentication
 */
export class AuthService { }

/**
 * @group Database
 */
export class UserRepository { }

/**
 * @category Utilities
 */
export function formatDate(date: Date): string { }

Markdown Output

For Markdown output (useful for static site generators):

{
  "plugin": ["typedoc-plugin-markdown"],
  "out": "docs/api",
  "theme": "markdown",
  "entryDocument": "index.md",
  "hideInPageTOC": false
}

Package.json Scripts

{
  "scripts": {
    "docs": "typedoc",
    "docs:watch": "typedoc --watch",
    "docs:serve": "typedoc && npx http-server docs/api"
  }
}

Advanced Configuration

Custom Theme

{
  "theme": "./custom-theme",
  "customCss": "./docs/custom.css"
}

Navigation Configuration

{
  "navigation": {
    "includeCategories": true,
    "includeGroups": true,
    "includeFolders": false
  },
  "navigationLinks": {
    "GitHub": "https://github.com/user/repo",
    "NPM": "https://www.npmjs.com/package/my-package"
  }
}

Search Configuration

{
  "searchInComments": true,
  "searchInDocuments": true,
  "searchGroupBoosts": {
    "Core": 2.0,
    "Authentication": 1.5
  }
}

Monorepo Configuration

For monorepo setups with multiple packages:

{
  "entryPoints": [
    "packages/core/src/index.ts",
    "packages/auth/src/index.ts",
    "packages/database/src/index.ts"
  ],
  "entryPointStrategy": "packages"
}

Validation Configuration

{
  "validation": {
    "notExported": true,     // Warn about non-exported types
    "invalidLink": true,     // Warn about invalid @link references
    "notDocumented": false   // Warn about undocumented items
  },
  "requiredToBeDocumented": [
    "Class",
    "Function",
    "Method"
  ]
}

CI/CD Integration

GitHub Actions

name: Generate Docs

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run docs
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/api

GitLab CI

pages:
  stage: deploy
  script:
    - npm ci
    - npm run docs
    - mv docs/api public
  artifacts:
    paths:
      - public
  only:
    - main

Performance Optimization

For large codebases:

{
  "excludeNotDocumented": true,
  "excludePrivate": true,
  "excludeInternal": true,
  "cacheBust": true,
  "cleanOutputDir": true
}

Complete Example Configuration

{
  "$schema": "https://typedoc.org/schema.json",
  "name": "My Project API Documentation",
  "entryPoints": ["src/index.ts"],
  "entryPointStrategy": "resolve",
  "out": "docs/api",
  "theme": "default",
  "readme": "README.md",
  "includeVersion": true,
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeInternal": true,
  "excludeNotDocumented": false,
  "categorizeByGroup": true,
  "defaultCategory": "Other",
  "categoryOrder": [
    "Core",
    "Authentication",
    "Database",
    "*"
  ],
  "searchInComments": true,
  "validation": {
    "notExported": true,
    "invalidLink": true,
    "notDocumented": false
  },
  "navigation": {
    "includeCategories": true,
    "includeGroups": true
  },
  "navigationLinks": {
    "GitHub": "https://github.com/user/repo",
    "NPM": "https://www.npmjs.com/package/my-package"
  },
  "plugin": ["typedoc-plugin-missing-exports"],
  "sourceLinkTemplate": "https://github.com/user/repo/blob/{gitRevision}/{path}#L{line}"
}

Troubleshooting

Issue: Types not appearing

Check excludePrivate, excludeInternal settings
Ensure types are exported from entry point
Use --logLevel Verbose for debugging

Issue: Slow generation

Enable excludeNotDocumented
Reduce entry points
Use --skipErrorChecking for quicker builds

Issue: Broken links

Enable validation.invalidLink
Use @link instead of markdown links for type references
Check that linked symbols are exported

References

Install with Tessl CLI

npx tessl i pantheon-ai/typescript-advanced

references

compiler-module-resolution.md

compiler-performance.md

compiler-strict-mode.md

compiler-tsconfig.md

docs-adr-templates.md

docs-framework-docs.md

docs-jsdoc-patterns.md

docs-typedoc-config.md

guards-assertion-functions.md

guards-basic.md

guards-branded-types.md

guards-discriminated-unions.md

guards-exhaustiveness.md

guards-generic.md

guards-inference-infer.md

guards-inference-return.md

patterns-advanced-generics.md

patterns-api-client.md

patterns-branded-types.md

patterns-builder.md

patterns-deep-readonly.md

patterns-dependency-injection.md

patterns-event-emitter.md

patterns-form-validation.md

patterns-plugin-system.md

patterns-recursive-types.md

patterns-state-machine.md

patterns-type-safe-module.md

practices-illegal-states.md

practices-module-patterns.md

practices-runtime-validation.md

practices-type-first.md

types-conditional.md

types-generics.md

types-index-signatures.md

types-mapped.md

types-narrowing.md

types-template-literals.md

types-type-assertions.md

types-unions-intersections.md

utilities-custom-mapped-types.md

utilities-extract-exclude.md

utilities-key-remapping.md

utilities-nonnullable-awaited.md

utilities-partial-required.md

utilities-pick-omit.md

utilities-readonly-record.md

utilities-returntype-parameters.md

SKILL.md

tile.json