MUI Docs Infra

Load Server Code Meta

The loadServerCodeMeta utility parses demo files to extract variant information and resolves file paths for code metadata. It reads demo index files, finds createDemo factory calls, and builds a Code object mapping variant names to their file URLs.

Note

This function is primarily used internally by CodeHighlighter when rendering demos on the server. Most users won't need to call it directly.

Basic Usage

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

// Load metadata from a demo index file
const code = await loadServerCodeMeta('file:///app/components/button/demos/basic/index.ts');

// Returns: { Default: 'file:///app/components/button/demos/basic/Component.tsx' }

The function:

  • Reads the demo index file
  • Finds the createDemo() or createDemoWithVariants() call
  • Resolves variant file paths to absolute URLs
  • Returns a Code object ready for use with CodeHighlighter

Common Patterns

Single Variant Demo

For demos with a single component:

// Demo file: app/components/button/demos/basic/index.ts
// export const DemoButtonBasic = createDemo(import.meta.url, Button);

const code = await loadServerCodeMeta('file:///app/components/button/demos/basic/index.ts');

// Returns:
// {
//   Default: 'file:///app/components/button/demos/basic/Button.tsx'
// }

Multiple Variants Demo

For demos with multiple styling approaches:

// Demo file: app/components/button/demos/styled/index.ts
// export const DemoButtonStyled = createDemoWithVariants(
//   import.meta.url,
//   { CssModules, Tailwind }
// );

const code = await loadServerCodeMeta('file:///app/components/button/demos/styled/index.ts');

// Returns:
// {
//   CssModules: 'file:///app/components/button/demos/styled/css-modules/Button.tsx',
//   Tailwind: 'file:///app/components/button/demos/styled/tailwind/Button.tsx'
// }

Named Exports

When variants use named exports instead of default exports:

// Demo file: app/components/form/demos/validation/index.ts
// export const DemoFormValidation = createDemoWithVariants(
//   import.meta.url,
//   { Basic: BasicForm, Advanced: AdvancedForm }
// );

const code = await loadServerCodeMeta('file:///app/components/form/demos/validation/index.ts');

// Returns:
// {
//   Basic: {
//     url: 'file:///app/components/form/demos/validation/BasicForm.tsx',
//     fileName: 'BasicForm.tsx',
//     namedExport: 'BasicForm'
//   },
//   Advanced: {
//     url: 'file:///app/components/form/demos/validation/AdvancedForm.tsx',
//     fileName: 'AdvancedForm.tsx',
//     namedExport: 'AdvancedForm'
//   }
// }

Advanced Usage

Custom Implementation

Create a custom loadCodeMeta function using the factory:

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

const customLoadCodeMeta = createLoadServerCodeMeta({
  // Configuration options (currently none available)
});

const code = await customLoadCodeMeta('file:///path/to/demo/index.ts');

Integration with CodeHighlighter

Using with server-side rendering:

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

async function DemoPage() {
  const code = await loadServerCodeMeta('file:///app/demos/example/index.ts');

  return <CodeHighlighter code={code} loadCodeMeta={loadServerCodeMeta} />;
}

API Reference

loadServerCodeMeta

function loadServerCodeMeta(url: string): Promise<Code>;

Loads code metadata from a demo index file.

Parameters:

ParameterTypeDescription
urlstringFile URL to the demo index file (with file://)

Returns: Promise resolving to a Code object mapping variant names to file URLs or metadata.

Throws: Error if file cannot be read or parsed.

createLoadServerCodeMeta

function createLoadServerCodeMeta(options?: CreateLoadCodeMetaOptions): LoadCodeMeta;

Factory function that creates a custom loadCodeMeta function.

Parameters:

ParameterTypeDescription
optionsCreateLoadCodeMetaOptions?Configuration (currently empty)

Returns: A LoadCodeMeta function.

Type Definitions

type LoadCodeMeta = (url: string) => Promise<Code>;

type Code = {
  [variantName: string]:
    | string
    | {
        url: string;
        fileName: string;
        namedExport: string;
      };
};

interface CreateLoadCodeMetaOptions {
  // No options currently available
}

How It Works

  1. Read Demo File: Reads the demo index file from the filesystem using readFile
  2. Parse Factory Call: Uses parseCreateFactoryCall to find createDemo() or createDemoWithVariants() calls
  3. Extract Variants: Extracts the variants object and any named export mappings
  4. Resolve Paths: Uses resolveVariantPathsWithFs to convert relative imports to absolute file URLs
  5. Build Code Object: Creates the final Code object with variant metadata

The function handles:

  • Single and multiple variant demos
  • Named exports vs default exports
  • File path resolution with filesystem lookups
  • URL formatting with file:// protocol

When to Use

  • Server-side rendering - When rendering CodeHighlighter on the server
  • Build-time processing - When pre-loading demo metadata during build
  • Custom demo systems - When building custom demo infrastructure

When NOT to use:

  • Client-side rendering - Use client-side loaders instead (filesystem access unavailable)
  • Pre-computed demos - Use the webpack loader for build-time optimization
  • Static demos - Pass code directly to CodeHighlighter if you already have it

Types

No types to display

See Types

Related