Migrate from TypeDoc

Ardo 6 removes the TypeDoc integration. Source API documentation uses native TypeScript for checked declarations and OXC for Markdown extraction. This affects the typedoc option, TypeDocConfig, ardo/typedoc, ardo/typedoc/components, and the TypeDoc flags of the retired create-ardo starter.

Install the native tools

Install the supported compiler and parser in your documentation project:

pnpm add -D typescript@7.1.0-dev.20261011.1 oxc-parser@^0.155.0

This compiler is a pinned TypeScript 7.1 nightly, and it also typechecks your project. TypeScript 7.0's native API lacks what Ardo needs. General documentation sites do not need these optional packages. Remove direct TypeDoc dependencies and plugins that were used only by this integration.

Update the Ardo configuration

Remove typedoc from the old Vite plugin configuration. Put api in ardo.config.ts and supply an explicit TypeScript configuration:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: {
    entryPoints: ["./src/index.ts"],
    tsconfig: "./tsconfig.api.json",
    out: "api-reference",
    title: "API Reference",
  },
})

A configuration containing typedoc, including typedoc: false, now throws a migration error. To disable generation, remove the option. api: true uses src/index.ts and tsconfig.json; an explicit project boundary is useful when the documentation app and library source share a directory:

{
  "extends": "./tsconfig.json",
  "files": ["src/index.ts"],
  "include": []
}

Include required ambient declarations in files as well. Ardo applies checked declaration emission and retained comments in memory without rewriting your configuration or writing declaration files to disk. Compiler errors fail the initial build. Development errors retain the last successful pages and appear in the Vite overlay; fixing them resumes generation.

Map existing customization

The extractor honors @internal comments and omits private/protected member expansion. Use your public entry points to select documented exports. Review existing TypeDoc-specific exclusions and grouping requirements rather than assuming the native renderer reproduces them. Generated page organization and some paths differ, so check links to individual API pages after regeneration.

For several packages, configure an array of projects with distinct output directories, as shown in Multiple packages. The docs application keeps the same setup and package boundary.

Update Programmatic Hosts and Setup

Replace generateApiDocs from ardo/typedoc with the one-shot native API:

import { generateNativeDocs } from "ardo/api"

await generateNativeDocs(
  { entryPoints: ["./src/index.ts"], tsconfig: "./tsconfig.api.json" },
  "./app/routes"
)

For a custom watcher, reuse NativeApiProject, pass absolute changed, created, and deleted file paths to extract or generate, and close the project on shutdown. The normal Vite integration owns this lifecycle for you.

Ardo 6 retires create-ardo. Use Agent Instructions and API Documentation for the native tools, source configuration, and a documented API example. Apply the migration above to customized Vite configuration rather than replacing it.

Verify the migration

Run your project's typecheck and build, inspect generated API pages and links, and check a source or JSDoc edit in development. Keep handwritten content outside the generated directory. Existing Ardo-generated pages are updated in place and obsolete pages are removed; unmarked handwritten directories are protected.

The native compiler can reject code accepted by JavaScript TypeScript, and the current extractor does not cover every TypeDoc feature. Namespace pages, original-source links, full TSDoc semantics, and arbitrary mapped/conditional member expansion remain limits documented in the native guide. Unsupported expansion retains the type expression and reports diagnostics. Review those diagnostics for your own API. To defer this breaking change, keep your previous Ardo version and configuration.