Tips and Tricks

Patterns that pay off in real projects. None are required. They’re what we reach for once the basics are in place.

• Monorepos

  One compodocx run per project, each writing to its own version folder under a shared /documentation. Each project keeps its own version-switcher and theme. A static index page at the root links to each project’s latest label.

• Watch + serve

  --watch --serve gives instant feedback while authoring. The dev server reuses production routing, so what you see locally matches what ships.

• Diff in CI on every PR

  Generate a JSON snapshot per build (--exportFormat json), commit it under snapshots/, and run compodocx diff prev.json next.json in CI. Exit code 2 fails the build on breaking changes. Pipe the JSON output to your bot for PR comments.

• LLM context for code review

  --exportFormat llm-md emits an LLM-context markdown bundle. Pipe it into llm, claude, or any tool that accepts a markdown corpus. Sized and structured for direct consumption, with signatures capped to keep the prompt small.

• Migrating from compodoc

  compodocx migrate templates ports a folder of Handlebars overrides to JS partials in one shot. Run compodocx migrate inspect first to see what will change.

• Keep your doc tsconfig narrow

  Exclude test files, storybook entries, dev-only fixtures. Heavy generic types render slower. A smaller surface keeps cold builds fast and keeps the rendered docs focused on what consumers actually use.

• Public API filtering

  --publicApiOnly restricts output to the symbols matching your public API allow-list. Useful when you ship internal helpers in the same package and don’t want them on the docs page.

• Preserve comments through the build

  Some bundlers strip JSDoc by default. Set "removeComments": false in your doc tsconfig if you see empty descriptions in the rendered output.