MUI Docs Infra

Warning

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

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} />;
}

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

loadServerCodeMeta

Default loadServerCodeMeta function that resolves variant paths from demo files. This function is used to load code metadata for demos, specifically resolving paths for variants defined in the demo files. It reads the demo file, parses it to find createDemo calls with variants, and resolves the paths for those variants. It returns a Code object mapping variant names to their resolved file URLs.

ParameterTypeDescription
urlstring
Return Type
Promise<Code>
CreateLoadCodeMetaOptions
DirectoryEntry
type DirectoryEntry = { name: string; isFile: boolean; isDirectory: boolean };
ResolveModulePathOptions
type ResolveModulePathOptions = { extensions?: string[] };

Related