Load Isomorphic Code Variant

The loadIsomorphicCodeVariant module provides utilities for loading, processing, and transforming code variants with support for syntax highlighting, TypeScript-to-JavaScript transformation, extra files, and metadata management.

Note

This module is primarily used internally by CodeHighlighter for runtime code loading and processing. Most users won't need to call these functions directly.

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

// Load and process a single variant
const result = await loadIsomorphicCodeVariant(
  'file:///app/components/button/Button.tsx',
  'default',
  {
    fileName: 'Button.tsx',
    url: 'file:///app/components/button/Button.tsx',
  },
  {
    sourceParser: createParseSource(),
    loadSource: myLoadSourceFunction,
    sourceTransformers: [typescriptToJavaScript],
  },
);

// Returns:
// {
//   code: { fileName: 'Button.tsx', source: /* HAST nodes */, transforms: { ... } },
//   dependencies: ['file:///app/components/button/Button.tsx'],
//   externals: {}
// }

The function:

• Loads source code from files or URLs
• Applies syntax highlighting (HAST transformation)
• Generates language transforms (e.g., TypeScript → JavaScript)
• Recursively loads extra files (CSS, utils, etc.)
• Tracks dependencies for caching and hot reloading

Extra files can be specified directly in the variant, or returned automatically by your loadSource function:

// Option 1: Specify extraFiles in the variant
const result = await loadIsomorphicCodeVariant(
  'file:///app/components/button/Button.tsx',
  'default',
  {
    fileName: 'Button.tsx',
    source: buttonSource,
    extraFiles: {
      'Button.module.css': 'file:///app/components/button/Button.module.css',
      '../utils/helpers.ts': 'file:///app/components/utils/helpers.ts',
    },
  },
  options,
);

// Option 2: Return extraFiles from loadSource (automatically loaded)
const loadSource = async (url) => {
  const source = await readFile(url);
  const extraFiles = await findDependencies(url); // e.g., CSS imports, relative imports

  return {
    source,
    extraFiles: {
      'Button.module.css': 'file:///app/components/button/Button.module.css',
      '../utils/helpers.ts': 'file:///app/components/utils/helpers.ts',
    },
  };
};

// Both approaches result in all files loaded and highlighted recursively
// result.code.extraFiles contains processed CSS and helpers

Note

Each extraFiles value is a URL/source string or an object { source?, transforms?, relativeUrl?, metadata?, ... }. When an entry is rewritten relative to the entry source (e.g. in 'flat' mode), relativeUrl is preserved so the original file URL can be reconstructed via new URL(relativeUrl, variant.url); otherwise the key itself resolves against variant.url.

Add shared dependencies (like package.json or global configs) to all variants:

const result = await loadIsomorphicCodeVariant(
  'file:///app/components/button/Button.tsx',
  'default',
  variant,
  {
    ...options,
    globalsCode: [
      { fileName: 'package.json', source: packageJsonContent },
      'file:///app/tsconfig.json',
    ],
  },
);

// Global files are merged with metadata flag for filtering

Convert code objects to HAST for rendering:

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

const code = {
  default: {
    fileName: 'Example.tsx',
    source: 'const x = 1;', // String source
  },
};

const parsed = parseCode(code, parseSource);
// Converts string sources to HAST nodes for rendering

Use sourceEnhancers to modify HAST nodes after parsing. Enhancers receive the parsed HAST root, any comments extracted from the source (via loadServerCodeSource), and the file name:

import type { SourceEnhancer, SourceComments } from '@mui/internal-docs-infra/CodeHighlighter';
import type { HastRoot } from 'hast';

// SourceComments is Record<number, string[]> - line numbers to comment arrays

// Example: Add line numbers based on comment sections
const addSectionMarkers: SourceEnhancer = (root, comments, fileName) => {
  // comments is Record<number, string[]> mapping line numbers to comment arrays
  // Use comments to enhance the HAST tree, e.g., add section markers
  if (comments) {
    for (const [lineNumber, lineComments] of Object.entries(comments)) {
      // Process comments to add markers, highlights, etc.
    }
  }
  return root;
};

// Example: Async enhancer that fetches additional data
const addTypeInfo: SourceEnhancer = async (root, comments, fileName) => {
  const typeData = await fetchTypeInfo(fileName);
  // Modify root with type information
  return root;
};

const result = await loadIsomorphicCodeVariant(
  'file:///app/components/button/Button.tsx',
  'default',
  variant,
  {
    sourceParser: createParseSource(),
    loadSource: myLoadSourceFunction,
    sourceEnhancers: [addSectionMarkers, addTypeInfo], // Run in order
  },
);

Enhancers run sequentially after parsing, each receiving the output of the previous enhancer. They are applied to both main files and extra files.

Convert nested variant structure to flat file paths:

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

const variant = {
  url: 'file:///src/components/button/Button.tsx',
  fileName: 'Button.tsx',
  source: buttonSource,
  extraFiles: {
    '../shared/utils.ts': { source: utilsSource },
    '../../package.json': { source: pkgSource, metadata: true },
  },
};

const flattened = flattenCodeVariant(variant);
// Returns:
// {
//   'src/components/button/Button.tsx': { source: buttonSource },
//   'src/components/shared/utils.ts': { source: utilsSource },
//   'src/package.json': { source: pkgSource, metadata: true }
// }

Determine if you have enough data to render without loading:

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

const { initialData, reason } = maybeCodeInitialData(
  ['typescript', 'javascript'],
  'typescript',
  code,
  undefined,
  true, // needsHighlight
  false, // needsAllFiles
  false, // needsAllVariants
);

if (initialData) {
  // Ready to render immediately
  return <CodeDisplay {...initialData} />;
} else {
  // Need to load more data
  console.log('Missing data:', reason);
}

Use loadCodeFallback to load the minimal data needed for initial render:

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

const fallback = await loadCodeFallback(
  'file:///app/demos/example/index.ts',
  'default', // initialVariant
  existingCode, // may be undefined
  {
    loadCodeMeta,
    loadVariantMeta,
    loadSource,
    sourceParser,
    variants: ['default', 'typescript'],
    fallbackUsesExtraFiles: true,
    fallbackUsesAllVariants: false,
  },
);

// Returns minimal data for initial render:
// {
//   code: { default: { ... } },
//   initialFilename: 'Example.tsx',
//   initialSource: /* HAST nodes */,
//   allFileNames: ['Example.tsx', 'Example.module.css'],
// }

Apply TypeScript-to-JavaScript transforms to rendered code:

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

const jsSource = applyCodeTransform(
  tsSource, // Original TypeScript HAST
  transforms, // From variant.transforms
  'javascript', // Transform key
);

// Returns JavaScript version of the source as HAST

Position metadata files (package.json, configs) relative to source files:

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

const merged = mergeCodeMetadata(
  variant,
  {
    'package.json': { source: pkgJson },
    'tsconfig.json': { source: tsConfig },
  },
  { metadataPrefix: 'src/' },
);

// Positions metadata files at correct depth based on source structure

Analyze variant structure for path resolution:

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

const context = examineCodeVariant(variant);
// Returns:
// {
//   hasUrl: true,
//   hasMetadata: true,
//   maxSourceBackNavigation: 2,
//   urlDirectory: ['src', 'components', 'button'],
//   rootLevel: 'src',
//   pathInwardFromRoot: 'components/button',
//   actualUrl: 'file:///src/components/button/Button.tsx'
// }

1. Resolve Variant - If variant is a string URL, load metadata via loadVariantMeta
2. Load Main File - Load source code via loadSource if not provided
3. Apply Transforms - Generate language variants (TypeScript → JavaScript)
4. Parse Source - Convert strings to HAST nodes via sourceParser
5. Enhance HAST - Run sourceEnhancers sequentially with comments from source
6. Process Extra Files - Recursively load and process dependencies
7. Merge Globals - Add global dependencies with metadata flags
8. Track Dependencies - Return all URLs for caching/hot reloading

When sourceEnhancers are provided, they process the HAST after parsing:

// Enhancement flow
const enhancedRoot = await sourceEnhancers.reduce(async (rootPromise, enhancer) => {
  const root = await rootPromise;
  return enhancer(root, comments, fileName);
}, Promise.resolve(parsedRoot));

Each enhancer receives:

• root - The current HAST root (output of previous enhancer)
• comments - Comments extracted by loadSource (e.g., from parseImportsAndComments)
• fileName - The file name for context

Enhancers can be synchronous or asynchronous and are applied to both main files and extra files.

Extra files support relative paths that are resolved recursively:

Button.tsx
├── Button.module.css (same directory)
├── ../utils/helpers.ts (parent directory)
└── ../../package.json (grandparent, metadata)

The loader:

• Resolves relative paths using URL resolution
• Detects circular dependencies
• Loads files in parallel for performance
• Preserves metadata flags for filtering

When sourceTransformers are provided:

1. Checks file extension (.ts, .tsx, etc.)
2. Transforms source to target language
3. Generates JSON diff delta
4. Stores delta in transforms object

Transforms are applied on-demand during rendering via applyCodeTransform.

Source comments (e.g. // @focus, // @padding-top) are keyed by line number. When a transform is applied, those keys need to track the lines they were attached to. The runtime handles this automatically for the common case:

• Removing lines — replace them with empty strings in the transformer output rather than dropping them. Empty lines collapse automatically at render time, and any comment that was on a surviving line is shifted onto its new line number for you. You do not need to return a comments map for this case.
• Adding lines or completely replacing the file — the auto-shift cannot tell where the original comments belong, so the transformer must return its own comments map alongside each transformed source. The returned map uses the same 0-indexed line scheme as the transformed source string and replaces (rather than augments) the source's original comment map for that transform.

Wiped-line runs are rendered as <span class="collapse" data-lines={n}> inside their parent frame. Demos in this repo style the placeholder via syntax.css: the element animates in at n * var(--docs-infra-syntax-line-height) and transitions to height: 0 on first paint, so the collapse reads as motion rather than an instant jump. Per-count rules cover data-lines 1–25; beyond that the stylesheet falls back to typed attr(), which currently only Chromium implements — other engines skip the entry animation for those runs but still render the final collapsed state correctly.

Because the placeholder animates from a non-zero height to zero, any content below the collapse will move up by that many lines on first paint. To keep that motion off-screen — and avoid a perceived layout shift — wrap the focused region of the demo in @focus / @focus-start / @focus-end markers (see lintJavascriptDemoFocus) that exclude the lines that get wiped (e.g. type User = {} and other type-only lines stripped by transformTypescriptToJavascript). When the wiped lines fall outside the visible-when-collapsed frame, the placeholder lives in a hidden frame and its entry animation never displaces visible code.

Switching to a different transform normally commits the new tree synchronously, which means .collapse placeholders in the outgoing tree are replaced by real .line spans in a single paint — the lines just snap back into place. To play the reverse of the entry animation (expand the placeholder up to its original height before the real lines arrive), set transformDelay on useCode():

const { selectedFile, selectTransform } = useCode(contentProps, {
  // wait 350ms after the user clicks before swapping in the new tree
  transformDelay: 350,
});

While a change is in flight, <Pre> annotates the rendered <pre> with data-transforming to drive consumer CSS animations. The attribute moves through a two-step handshake per window so the new tree (or bridge) has a paint to settle into its start position before the keyframe runs:

• paused start — data-transforming="collapsed" (pre-swap) or data-transforming="expanded" (post-swap). Consumer CSS should place the bridge/added lines at the animation's starting height without running a keyframe.
• active animation — data-transforming="expanding" (pre-swap) or data-transforming="collapsing" (post-swap). The keyframe runs from the start position established by the paused step to the end position.

The four rules in syntax.css (two paused holds + two active keyframes) match the placeholder height to the lines being added or removed, so the swap reads as motion instead of an instant jump. A subsequent click during the pending window cancels the previous timer and re-arms with the new target.

The attribute value reflects the direction of the in-flight animation:

• data-transforming="collapsed" → "expanding" — pre-swap exit window. The OUTGOING tree's .collapse placeholders hold at 0 (the collapsed start), then expand back to their original height (the lines being kept by the new transform are about to reappear).
• data-transforming="expanded" → "collapsing" — post-swap entry window. The INCOMING tree's .collapse placeholders hold at their original height (the expanded start), then collapse down to 0 (the lines just removed by the new transform).

The exact sequence depends on the swap direction:

• null → transform — the new tree commits immediately so the user sees the requested code right away, and the post-swap "expanded" → "collapsing" window animates its placeholders closed.
• transform → null — the pre-swap "collapsed" → "expanding" window plays first (the outgoing placeholders open to reveal the lines about to come back), then the swap commits to the untransformed source.
• transform → transform — both halves run back-to-back: "collapsed" → "expanding" on the outgoing tree for transformDelay ms, the swap commits, then "expanded" → "collapsing" on the incoming tree for another transformDelay ms (total 2 × transformDelay).

Gating the animation on data-transforming (rather than the bare .collapse selector) keeps initial renders and unrelated re-renders silent — only an actual transform swap triggers motion.

The metadataPrefix option positions source files within a directory while keeping metadata files at the project root:

Without metadataPrefix:
├── Button.tsx (source)
├── utils.ts (source)
├── package.json (metadata)
└── tsconfig.json (metadata)

With metadataPrefix: 'src/':
├── src/
│   ├── Button.tsx (source)
│   └── utils.ts (source)
├── package.json (metadata - stays at root)
└── tsconfig.json (metadata - stays at root)

This ensures metadata files remain accessible at the project root while source files are scoped within their directory.

• Runtime loading - When code isn't precomputed at build time
• Client-side rendering - Loading code in browser environments
• Server-side rendering - Processing code in Next.js server components
• Dynamic content - When demos are generated from APIs or databases

When NOT to use:

• Build-time optimization - Use the webpack loader instead
• Static demos - Pass precomputed code directly to CodeHighlighter
• Simple highlighting - Use parseSource directly for basic needs

The loader uses Promise.all to load extra files in parallel:

// Loads all files simultaneously
extraFiles: {
  'styles.css': 'url1',
  'utils.ts': 'url2',
  'types.ts': 'url3',
}
// All three load in parallel, not sequentially

loadSource calls are cached within a single loadIsomorphicCodeVariant execution to prevent duplicate requests for the same file.

The loader tracks loaded files and throws errors on circular dependencies:

// This would throw an error:
// A.tsx imports ../B.tsx
// B.tsx imports ../A.tsx

• output: 'hastJson' - JSON stringified HAST (development)
• output: 'hastCompressed' - Compressed HAST (production, smaller bundles)

Circular dependency detected:

Error: Circular dependency detected: file:///path/to/file.ts

Fix: Restructure imports to remove circular references.

Invalid extraFiles:

Error: Invalid extraFiles from loadSource: key "file:///..." appears to be an absolute path.

Fix: Use relative paths as keys in extraFiles.

Missing loadSource:

Error: "loadSource" function is required when source is not provided

Fix: Provide loadSource in options or include source inline.

Transform not found:

Error: Transform "javascript" not found in transforms

Fix: Ensure sourceTransformers generated the requested transform.

string | undefined

string

VariantCode | string | undefined

LoadVariantOptions | undefined

Promise<{ code: VariantCode; dependencies: string[]; externals: Externals }>

string

string

Code | undefined

LoadFallbackCodeOptions | undefined

Promise<FallbackVariants>

Code

ParseSource

Code

VariantCode

FlattenedFiles

VariantCode

VariantExtraFiles | undefined

MergeMetadataOptions | undefined

VariantCode

VariantCode

PathContext

string[]

string

Code | undefined

string | undefined

boolean | undefined

boolean | undefined

boolean | undefined

| false
| {
    code: Code;
    initialFilename: string | undefined;
    initialSource: VariantSource;
    initialExtraFiles?: VariantExtraFiles;
  }

string | undefined

string[]

Code

boolean | undefined

boolean

Code

SourceEnhancer[]

Promise<Code>

VariantSource

Transforms

string

FallbackNode[] | undefined

VariantSource

VariantSource

Transforms

string

SourceComments | undefined

FallbackNode[] | undefined

VariantSource

SourceComments | undefined

VariantSource

Transforms

string[]

FallbackNode[] | undefined

VariantSource

VariantSource

Transforms

string[]

SourceComments | undefined

FallbackNode[] | undefined

VariantSource

SourceComments | undefined

VariantCode

VariantCode

type FallbackVariants = {
  code: Code;
  initialFilename: string | undefined;
  initialSource: VariantSource;
  initialExtraFiles?: VariantExtraFiles;
  allFileNames: string[];
  processedGlobalsCode?: Code[];
}

type FileWithPath = { source?: VariantSource; metadata?: boolean; path: string }

type FlatFile = { source: string; metadata?: boolean }

type FlattenedFiles = { [filePath: string]: FlatFile }

type PathContext = PathContextWithUrl | PathContextWithoutUrl

• loadPrecomputedCodeHighlighter - Build-time alternative
• parseSource - Syntax highlighting function
• loadServerCodeSource - Server-side source loading
• transformTypescriptToJavascript - TypeScript transformer