#Managing Interactive Examples (<Go>)

Interactive examples allow users to preview and edit code directly in the documentation. This guide explains how to manage these examples using the dedicated workspace and the <Go> component.

#Overview

The interactive example system allows you to embed live, runnable Lynx code in your documentation. It consists of:

1. Source Packages: Examples are real npm packages managed in packages/lynx-example-packages/.
2. Build Process: A script bundles these packages into static assets for the website.
3. <Go> Component: A React component that renders the interactive editor and preview in your MDX files.

#1. Using the <Go> Component

To embed an interactive example in your documentation, use the <Go> component.

#Basic Usage

Import Go from @lynx and provide the example ID (which corresponds to the package directory name).

import { Go } from '@lynx';

<Go example="view" />;

#Component Props

#Entry Selection

scripts/lynx-example.js creates one templateFiles item per Lynx bundle. By default, its name is the bundle basename without .lynx.bundle: for example, dist/main.lynx.bundle becomes name: "main". When basenames collide, the generator prefixes enough parent path segments to produce unique suffixes. For example, dist/a/main.lynx.bundle and output/a/main.lynx.bundle become dist/a/main and output/a/main. Generation fails if artifact paths still cannot produce unique names. defaultEntryName selects that logical name exactly; it is not a filename or an array index.

When no entry name is provided, go-web falls back to templateFiles[0]. The generator does not assign special meaning to that position or explicitly sort the entry list. Multi-entry examples should set defaultEntryName so the selected entry does not depend on that fallback. A name that does not exist does not silently fall back to the first entry.

#Advanced Example

<Go
  example="view"
  defaultFile="src/App.tsx"
  defaultEntryName="main"
  highlight={{ 'src/App.tsx': '5-10' }}
/>

#2. Managing Example Packages

All interactive examples are managed as dependencies in the packages/lynx-example-packages/ workspace.

#Directory Structure

packages/lynx-example-packages/
├── package.json          # Manifest listing all example dependencies
├── pnpm-lock.yaml       # Lockfile for examples
└── node_modules/        # Where installed examples reside
    └── @lynx-example/   # Namespace for official examples

#Adding a New Example

To make a new example available to the <Go> component:

1. Publish the Package: Your example must be a valid npm package (e.g., @lynx-example/my-feature).
2. Add Dependency: Add the package to packages/lynx-example-packages/package.json.
3. Install: Run pnpm install in the workspace root to download the new example.
4. Rebuild Assets: The website build process will automatically detect and bundle the new example.

#3. Build Architecture

For those interested in how it works under the hood:

• Script: scripts/lynx-example.js runs during the build.
• Process:
  1. Scans node_modules/@lynx-example/ for packages.
  2. Identifies bundle files (.lynx.bundle, .web.bundle) and source code.
  3. Generates an example-metadata.json for each example.
  4. Copies assets to docs/public/lynx-examples/.
• Runtime: The <Go> component fetches this metadata at runtime to hydrate the editor and preview.