MUI Docs Infra

Warning

This is an internal project, and is not intended for public use. No support or stability guarantees are provided.

Sync Types

The server-side function for synchronizing TypeScript type documentation to disk. This function coordinates type loading and markdown generation, updating the types.md file and optionally the parent index page.

Overview

syncTypes is the orchestration function that:

  1. Calls loadServerTypesMeta to load and format TypeScript types
  2. Generates markdown documentation via generateTypesMarkdown
  3. Writes types.md with the latest type documentation
  4. Optionally updates the parent index page with component metadata
  5. Returns the organized data for rendering

This function is separated from the webpack loader to allow reuse in other contexts (e.g., API routes, scripts, or custom build tools).

Note: Type highlighting is handled separately by loadServerTypes, which calls this function and then applies highlightTypes and highlightTypesMeta to convert plain text types to syntax-highlighted HAST.

Usage

Basic Usage

 
import { syncTypes } from '@mui/internal-docs-infra/pipeline/syncTypes';

// Sync the types (updates types.md and returns latest data)
const result = await syncTypes({
  typesMarkdownPath: '/absolute/path/to/types.md',
  rootContext: '/absolute/path/to/project',
  variants: { Default: '@base-ui/react/checkbox' },
  // Optional: watchSourceDirectly
  formattingOptions: {
    shortTypeUnionPrintWidth: 40,
    defaultValueUnionPrintWidth: 40,
  },
  // Optional: transform extracted descriptions
  descriptionReplacements: [{ pattern: '\\n\\nDocumentation:.*$', replacement: '', flags: 'm' }],
});

// Use the results
console.log(result.exports); // Record<string, { type: TypesMeta; additionalTypes: TypesMeta[] }>
console.log(result.additionalTypes); // TypesMeta[] for top-level types
console.log(result.variantOnlyAdditionalTypes); // Record<string, TypesMeta[]> for types-only module variants
console.log(result.allDependencies); // string[] - files to watch

The return type is TypesSourceData, the shared contract consumed by loadServerTypes. See the loadServerTypes overview for details on this shared structure.

Note: The result contains plain text type fields (typeText, defaultText). Use loadServerTypes if you need HighlightedTypesMeta with syntax-highlighted HAST fields (type, shortType, detailedType, default).

TypesMeta Structure

For details on the TypesMeta union type and its variants (component, hook, function, class, raw), see loadServerTypesMeta.

Processing Pipeline

syncTypes coordinates a two-stage pipeline:

1. Load and Format Types

Delegates to loadServerTypesMeta:

const typesMetaResult = await loadServerTypesMeta({
  typesMarkdownPath,
  rootContext,
  variants,
  watchSourceDirectly,
  formattingOptions,
  socketDir,
  externalTypesPattern,
});

This handles TypeScript configuration, worker processing, and type formatting. See loadServerTypesMeta Processing Pipeline for details.

2. Generate and Write Markdown

Generates markdown documentation and writes to disk:

const markdown = await generateTypesMarkdown({
  name: resourceName,
  organized: {
    exports,
    additionalTypes,
    variantOnlyAdditionalTypes,
    variantTypeNames,
    variantTypeNameMaps,
  },
  typeNameMap,
  externalTypes,
  path: relativePath,
});

// Only write if changed
const existingMarkdown = await readFile(typesMarkdownPath, 'utf-8').catch(() => null);
if (existingMarkdown !== markdown) {
  await writeFile(typesMarkdownPath, markdown, 'utf-8');
}

3. Update Parent Index (Optional)

When updateParentIndex is configured, updates the parent directory's index page:

await syncPageIndex({
  pagePath,
  metadata: pageMetadata, // props, dataAttributes, cssVariables, parameters
  baseDir: updateParentIndex.baseDir,
  indexFileName: updateParentIndex.indexFileName,
  // ...
});

Deep dive: For details on the TypeScript processing pipeline (configuration loading, worker architecture, type formatting), see loadServerTypesMeta.

Types

Syncs types for a component/hook/function.

  • Loads and formats types via loadServerTypesMeta
  • Generates markdown documentation
  • Writes markdown to disk
  • Updates parent index page (if configured)

This is separated from the webpack loader to allow reuse in other contexts.

PropertyTypeDescription
typesMarkdownPath
string

Absolute path to the types.md file to generate

rootContext
string

Root context directory (workspace root)

variants
Record<string, string> | undefined

Map of variant name to file path (relative or package path). For single component: { Default: './Component' } For multiple: { CssModules: './css-modules/Component', Tailwind: './tailwind/Component' }

watchSourceDirectly
boolean | undefined

When true, resolves library paths to their source files for watching. Useful during development to watch the original source rather than built files.

formattingOptions
FormatInlineTypeOptions | undefined

Options for formatting types in tables

socketDir
string | undefined

Directory path for socket and lock files used for IPC between workers. Useful for Windows where the default temp directory may not support Unix domain sockets.

performanceLogging
boolean | undefined

Enable performance logging

updateParentIndex
| {
    baseDir?: string;
    onlyUpdateIndexes?: boolean;
    markerDir?: string;
    errorIfOutOfDate?: boolean;
    indexFileName?: string;
  }
| undefined

Options for updating the parent index page with component metadata. When provided, will call syncPageIndex to update the parent directory’s page.mdx with props, dataAttributes, and cssVariables extracted from the component types.

These options are passed through to syncPageIndex.

externalTypesPattern
string | undefined

Optional regex pattern string to filter which external types to include. External types are named union types (like Orientation = 'horizontal' | 'vertical') that are referenced in props but not exported from the component’s module.

When not provided, ALL qualifying named union types (unions of literals) will be collected automatically. This is the recommended behavior for most projects.

When provided, only external types whose names match this pattern will be collected.

ordering
OrderingConfig | undefined

Custom ordering configuration for sorting props, data attributes, exports, etc.

descriptionReplacements
DescriptionReplacement[] | undefined

Pattern/replacement pairs to apply to JSDoc descriptions. Each entry has a pattern (regex string) and replacement string.

Return Type
Promise<TypesSourceData>
SyncTypesOptions
type SyncTypesOptions = {
  /** Absolute path to the types.md file to generate */
  typesMarkdownPath: string;
  /** Root context directory (workspace root) */
  rootContext: string;
  /**
   * Map of variant name to file path (relative or package path).
   * For single component: `{ Default: './Component' }`
   * For multiple: `{ CssModules: './css-modules/Component', Tailwind: './tailwind/Component' }`
   */
  variants?: Record<string, string>;
  /**
   * When true, resolves library paths to their source files for watching.
   * Useful during development to watch the original source rather than built files.
   */
  watchSourceDirectly?: boolean;
  /** Options for formatting types in tables */
  formattingOptions?: FormatInlineTypeOptions;
  /**
   * Directory path for socket and lock files used for IPC between workers.
   * Useful for Windows where the default temp directory may not support Unix domain sockets.
   */
  socketDir?: string;
  /** Enable performance logging */
  performanceLogging?: boolean;
  /**
   * Options for updating the parent index page with component metadata.
   * When provided, will call syncPageIndex to update the parent directory's page.mdx
   * with props, dataAttributes, and cssVariables extracted from the component types.
   *
   * These options are passed through to syncPageIndex.
   */
  updateParentIndex?: {
    baseDir?: string;
    onlyUpdateIndexes?: boolean;
    markerDir?: string;
    errorIfOutOfDate?: boolean;
    indexFileName?: string;
  };
  /**
   * Optional regex pattern string to filter which external types to include.
   * External types are named union types (like `Orientation = 'horizontal' | 'vertical'`)
   * that are referenced in props but not exported from the component's module.
   *
   * When not provided, ALL qualifying named union types (unions of literals) will be
   * collected automatically. This is the recommended behavior for most projects.
   *
   * When provided, only external types whose names match this pattern will be collected.
   * @example undefined // Collect all qualifying external types (recommended)
   * @example '^(Orientation|Alignment|Side)$' // Only include specific types
   */
  externalTypesPattern?: string;
  /** Custom ordering configuration for sorting props, data attributes, exports, etc. */
  ordering?: OrderingConfig;
  /**
   * Pattern/replacement pairs to apply to JSDoc descriptions.
   * Each entry has a `pattern` (regex string) and `replacement` string.
   */
  descriptionReplacements?: DescriptionReplacement[];
}