typescript-plugin-extensions.md

TypeScript plugin extensions

Import public types from @uttori/wiki. The package exports JavaScript for execution and generated .d.ts files for TypeScript. JSDoc on source interfaces, fields, and methods is preserved in those declarations.

Extend documents

Augment UttoriWikiDocumentExtensions in a module that your application includes. The initial import makes this an augmentation of the existing package instead of a replacement module declaration.

import type { UttoriWikiDocumentExtended } from '@uttori/wiki';

declare module '@uttori/wiki' {
  interface UttoriWikiDocumentExtensions {
    /** External catalog identifier; absent on documents created before import. */
    catalogId?: string;
  }
}

export function catalogLink(document: UttoriWikiDocumentExtended): string | undefined {
  if (document.catalogId) {
    return `/catalog/${encodeURIComponent(document.catalogId)}`;
  }
  return undefined;
}

UttoriWikiDocumentExtended combines the core document fields with the extension interface. Built-in category fields are already declared by the category plugin. Use optional fields for values that may be absent from existing documents, and include custom fields in the wiki's allowedDocumentKeys when saving them through edit forms.

A plugin can place its augmentation in its main TypeScript module or import a separate augmentation module from its entry point. Consumers then receive the extension when they import the plugin. Avoid importing private dist/ paths or declaration files as runtime modules.

Type plugin configuration

Use UttoriContextWithPluginConfig to describe the configuration a plugin receives:

import type { UttoriContextWithPluginConfig } from '@uttori/wiki';

interface CatalogConfig {
  /** URL prefix used when linking imported catalog entries. */
  baseUrl: string;
}

type CatalogContext = UttoriContextWithPluginConfig<'catalog', CatalogConfig>;

export function catalogUrl(context: CatalogContext, id: string): string {
  return `${context.config.catalog.baseUrl}/${encodeURIComponent(id)}`;
}

A custom plugin must apply and validate its own defaults before calling helpers that require them. For built-in plugins, the context helper marks fields supplied by defaultConfig() as required while preserving their declared value types. Optional settings without defaults remain optional.

Verify extensions

npm run test:types compiles a consumer fixture against the package exports. It checks built-in plugin constructors, document augmentation, custom context fields, and declaration dependencies with skipLibCheck disabled. Add consumer examples there when changing the public type contract.