vike-plugin-typedoc

Headless TypeDoc integration for Vike documentation sites.

Installation

npm install vike-plugin-typedoc

Peer dependencies:

• vike >= 0.4.250
• vike-react >= 0.5 (if you use the React hooks)
• react >= 18 (if you use the React hooks)

What It Does

• Loads TypeDoc JSON files into a cached TypedocContext.
• Builds package and symbol URLs (default /api/:pkg/:symbol).
• Builds API navigation trees.
• Pre-renders markdown fields and auto-links type references.
• Provides Vike data helpers (withApiPackage, withApiExport) and React hooks (useApiPackage, useApiExport).
• Provides a Vike config extension that auto-loads context and prerender URLs.

Quick Start

Add the plugin extension and typedoc config:

import { join } from 'node:path';
import vikePluginTypedoc from 'vike-plugin-typedoc/config';
import vikeReact from 'vike-react/config';
import type { Config } from 'vike/types';

const root = process.cwd();

export default {
  extends: [vikeReact, vikePluginTypedoc],
  prerender: true,
  typedoc: {
    typedocDir: join(root, '.typedoc'),
    packagesDir: join(root, 'packages'),
    basePath: '/api',
  },
} satisfies Config;

The plugin expects one TypeDoc JSON file per package slug in typedocDir (for example .typedoc/devkit.json).

Package and Symbol Pages

Package route data loader:

// pages/api/@pkg/+data.ts
import { withApiPackage } from 'vike-plugin-typedoc/server';
import type { PageContextServer } from 'vike/types';

export function data(pageContext: PageContextServer) {
  return withApiPackage(pageContext, pageContext.routeParams.pkg);
}

Package route component:

// pages/api/@pkg/+Page.tsx
import { useApiPackage } from 'vike-plugin-typedoc/client';

export default function Page() {
  const { apiPackage, packageName } = useApiPackage();
  if (!apiPackage) return <h1>Package not found: {packageName}</h1>;
  return <h1>{packageName}</h1>;
}

Symbol route data loader:

// pages/api/@pkg/@symbol/+data.ts
import { withApiExport } from 'vike-plugin-typedoc/server';
import type { PageContextServer } from 'vike/types';

export function data(pageContext: PageContextServer) {
  const { pkg, symbol } = pageContext.routeParams;
  return withApiExport(pageContext, pkg, symbol);
}

Symbol route component:

// pages/api/@pkg/@symbol/+Page.tsx
import { useApiExport } from 'vike-plugin-typedoc/client';

export default function Page() {
  const { apiExport, packageName } = useApiExport();
  if (!apiExport) return <h1>Symbol not found in {packageName}</h1>;
  return <h1>{apiExport.name}</h1>;
}

typedoc Config Options

Option	Type	Description
typedocDir	string	Directory containing *.json TypeDoc output files.
packageNames	Record<string, string>	Optional slug-to-npm-name overrides.
packagesDir	string	Reads missing package names from <packagesDir>/<slug>/package.json.
exclude	string[]	Package slugs to skip when loading docs.
buildUrl	(packageSlug: string, symbolSlug?: string) => string	Custom URL builder for package and symbol pages.
basePath	string	Prefix used by default URL builder. Defaults to /api.
baseUrl	string	Deployment base URL used when generating HTML links.
remarkPlugins	PluggableList	Extra remark plugins for markdown rendering.
rehypePlugins	PluggableList	Extra rehype plugins for markdown rendering (for example syntax highlighting).

Server and Client Entrypoints

• vike-plugin-typedoc/server:
  • loadTypedocContext()
  • getTypedocContext()
  • withApiPackage()
  • withApiExport()
• vike-plugin-typedoc/client:
  • useApiPackage()
  • useApiExport()

Headless Utilities (Without Vike Hooks)

Root exports are usable even outside Vike page hooks:

import {
  buildApiNavigation,
  buildMarkdownProcessor,
  buildSymbolsMap,
  combineApiDocs,
  createTypedocContext,
  parseTypedocJson,
} from 'vike-plugin-typedoc';

This is useful if you want to parse TypeDoc JSON once and feed another renderer, while reusing the same symbol-linking logic.

License

MIT