Lynx Go Web

The <Go> component for embedding live Lynx examples on the web — with code browsing, web preview, and QR code for on-device testing. Initially built for lynxjs.org, now extracted for everyone to embed their Lynx apps.

The <Go> with Examples gallery showcases examples from @lynx-example, @vue-lynx-example, and more.

Usage

import { GoConfigProvider, Go } from '@lynx-js/go-web';

const config = {
  exampleBasePath: '/lynx-examples',
};

<GoConfigProvider config={config}>
  <Go example="hello-world" defaultFile="src/App.tsx" />
</GoConfigProvider>

With rspress

import { GoConfigProvider, Go } from '@lynx-js/go-web';
import { rspressAdapter } from '@lynx-js/go-web/adapters/rspress';

const config = {
  exampleBasePath: '/lynx-examples',
  ...rspressAdapter,
};

<GoConfigProvider config={config}>
  <Go example="hello-world" />
</GoConfigProvider>

SSG (Static Site Generation)

go-web ships a built-in SSG component and a pure generation function so that pre-rendered pages include a meaningful code preview instead of an empty placeholder.

Option A: React component (rspress / SSR frameworks)

Use ExamplePreviewSSG as the SSGComponent in your GoConfig. It reads example files from disk at render time during SSG.

import { GoConfigProvider, Go } from '@lynx-js/go-web';
import { rspressAdapter } from '@lynx-js/go-web/adapters/rspress';
import { ExamplePreviewSSG } from '@lynx-js/go-web/ssg';
import path from 'path';

const config = {
  exampleBasePath: '/lynx-examples',
  ...rspressAdapter,
  SSGComponent: ExamplePreviewSSG,
  ssgExampleRoot: path.join(__dirname, '../docs/public/lynx-examples'),
};

<GoConfigProvider config={config}>
  <Go example="hello-world" defaultFile="src/App.tsx" />
</GoConfigProvider>

Option B: Pure function (build-time injection)

Use generateSSGHTML() in your build config to pre-render example previews as static HTML strings at build time, then inject them as environment variables.

// rsbuild.config.ts
import { generateSSGHTML } from '@lynx-js/go-web/ssg';

const html = generateSSGHTML({
  exampleRoot: path.resolve(__dirname, 'public/lynx-examples'),
  example: 'hello-world',
  defaultFile: 'src/App.tsx',
  lang: 'en',
});

The ./ssg export uses Node.js fs/path and must not be bundled into browser code.

Iframe Embed (no React required)

For non-React sites (Hugo, Jekyll, plain HTML, etc.), use the iframe embed API. The host page only loads a tiny JS file — React runs inside the iframe.

<div id="demo" style="height: 500px;"></div>
<script type="module">
  import { mount } from 'https://go.lynxjs.org/embed.js';

  const embed = mount('#demo', {
    example: 'hello-world',
    defaultFile: 'src/App.tsx',
  });

  // Switch example dynamically:
  // embed.update({ example: 'css' });

  // Clean up:
  // embed.destroy();
</script>

Options:

Option	Type	Description
example	string	Required. Example folder name
defaultFile	string	Initial file to display (default: 'src/App.tsx')
defaultTab	'preview' | 'web' | 'qrcode'	Default preview tab
exampleBasePath	string	Base path or full URL for example data
img	string	Static preview image URL
defaultEntryFile	string	Default entry file for web preview
highlight	string	Line highlight spec, e.g. '{1,3-5}'
entry	string | string[]	Filter entry files in tree

Development

pnpm dev

This starts the standalone example app at localhost:5969.

Lynx examples

The @lynx-example/* packages are fetched directly from the npm registry at build time — no need to declare them as dependencies. The prepare script handles discovery, download, and metadata generation automatically.

# Local dev: uses cached examples if available (instant)
pnpm prepare

# Force re-fetch latest from npm registry
pnpm prepare:clean

CI always runs prepare:clean to ensure examples are up-to-date.

CI

All three checks must pass on every PR:

• Type Check — pnpm typecheck at the repo root
• Build Example App — standalone Rsbuild example
• Build Rspress Example — rspress integration example

License

Apache-2.0