tessl/npm-astrojs--mdx

Astro integration that enables MDX support for creating interactive pages and components with Markdown and JSX

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Server-Side Rendering

Name: tessl/npm-astrojs--mdx
Author: tessl

Server-side rendering utilities for MDX components, providing component validation and HTML generation capabilities for server environments.

Capabilities

Component Check Function

Validates whether a component is a valid MDX component that can be rendered.

/**
 * Checks if a component is a valid MDX component for rendering
 * @param Component - Component to check for MDX compatibility
 * @param props - Component properties to pass during validation
 * @param slotted - Destructured slotted content with default children and named slots
 * @returns Promise resolving to boolean indicating if component is valid for rendering
 */
export async function check(
  Component: any,
  props: any,
  { default: children = null, ...slotted } = {}
): Promise<boolean>;

The function performs these validation steps:

Checks if the Component is a function
Processes slot names (converts kebab-case to camelCase)
Attempts to render the component with provided props
Returns true if the result contains AstroJSX markers
Handles MDX-specific errors with enhanced error messages

Usage Examples:

import { check } from "@astrojs/mdx/server.js";

// Check a basic component
const isValid = await check(MyMDXComponent, { title: "Hello" });

// Check with slots (using destructuring pattern)
const isValidWithSlots = await check(
  MyMDXComponent, 
  { title: "Hello" },
  { 
    default: "Main content",
    sidebar: "Sidebar content"
  }
);

// Check returns false for non-MDX components
const isInvalid = await check("not-a-component", {});

Static Markup Rendering Function

Renders an MDX component to static HTML markup for server-side rendering.

/**
 * Renders MDX component to static HTML markup
 * @param this - Render context with result property
 * @param Component - MDX component to render
 * @param props - Component properties (defaults to empty object)
 * @param slotted - Destructured slotted content with default children and named slots
 * @returns Promise resolving to object containing rendered HTML string
 */
export async function renderToStaticMarkup(
  this: any,
  Component: any,
  props = {},
  { default: children = null, ...slotted } = {}
): Promise<{ html: string }>;

The rendering process:

Processes slot names (converts kebab-case to camelCase)
Accesses the current render result context
Uses Astro's JSX renderer to generate HTML
Returns the HTML string wrapped in an object
Provides enhanced error handling for MDX components

Usage Examples:

import { renderToStaticMarkup } from "@astrojs/mdx/server.js";

// Basic rendering
const result = await renderToStaticMarkup(MyMDXComponent, {
  title: "Welcome",
  content: "Hello World"
});
console.log(result.html); // "<div>Welcome</div>..."

// Rendering with slots (note: function uses 'this' context)
const resultWithSlots = await renderToStaticMarkup.call(
  { result: currentRenderResult },
  MyMDXComponent,
  { title: "Welcome" },
  {
    default: "Main content here",
    "hero-section": "Hero content",
    footer: "Footer content"
  }
);

// The function automatically converts slot names:
// "hero-section" becomes "heroSection" in the component

Default Renderer Export

The module exports a default renderer object that implements Astro's server-side rendering interface.

interface NamedSSRLoadedRendererValue {
  /** Renderer identifier */
  name: string;
  /** Component validation function */
  check: typeof check;
  /** Static markup rendering function */
  renderToStaticMarkup: typeof renderToStaticMarkup;
}

/** Default SSR renderer for MDX components */
const renderer: NamedSSRLoadedRendererValue;
export default renderer;

The default renderer provides:

name: "astro:jsx"
check: The component validation function
renderToStaticMarkup: The HTML rendering function

Slot Name Processing

Both check and renderToStaticMarkup automatically process slot names by converting kebab-case to camelCase:

// Internal slot processing
const slotName = (str: string) => str.trim().replace(/[-_]([a-z])/g, (_, w) => w.toUpperCase());

// Examples:
// "hero-section" → "heroSection"
// "main_content" → "mainContent"  
// "sidebar" → "sidebar" (unchanged)

This ensures compatibility between HTML attribute naming conventions and JavaScript property names.

Error Handling

The server utilities provide enhanced error handling for MDX components:

MDX Component Error Enhancement

When an error occurs during rendering of an MDX component (identified by the Symbol.for('mdx-component') marker), the error is enhanced with:

Title: Set to the original error name
Hint: Helpful message indicating MDX runtime errors
Preservation: Existing AstroError instances maintain their original hints

Error Context

All errors maintain their original stack traces while providing additional context specific to MDX component rendering issues.

Integration with Astro

These server utilities are automatically used by Astro when:

Rendering .mdx pages during SSR
Processing MDX components in server contexts
Validating components during the build process
Generating static HTML from MDX content

The utilities work seamlessly with Astro's component system and provide the necessary interface for MDX components to participate in server-side rendering.