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, e.g. 'hello-world'
defaultFile	string	Initial file to display (default: 'src/App.tsx')
mode	'linked' | 'preview' | 'source'	Overall layout mode (default: 'linked'). 'linked' shows code + preview together; 'preview' shows preview only; 'source' shows code only.
defaultTab	'preview' | 'web' | 'qrcode'	Default preview tab
exampleBasePath	string	Base path or full URL for example data, e.g. '/lynx-examples'
img	string	Static preview image URL
defaultEntryFile	string	Default entry bundle file path (relative to the example folder), e.g. 'dist/main.lynx.bundle'. Must match example-metadata.json (templateFiles[].file). Prefix match is supported (e.g. 'dist/main').
defaultEntryName	string	Default entry name (from templateFiles[].name), e.g. 'main'. Convenience alternative to defaultEntryFile and only used when defaultEntryFile is not provided.
highlight	string | Record<string, string>	Line highlight spec, e.g. '{1,3-5}'. When passing a map, the key is the file path and the value is that file’s highlight spec.
entry	string | string[]	Filter entry files in tree, useful for example with multiple entries, e.g. 'src/basic'
schema	string	URL schema template for Lynx Explorer QR code. Use {{{url}}} as placeholder for the resolved entry URL, e.g. {{{url}}}?bar_color=000000&back_button_style=dark

Viewport Mode (Web Preview)

These options control how lynx-view renders inside the web preview panel.

Web preview bundle resolution is driven by example-metadata.json (templateFiles[].webFile) for the selected entry; it is not inferred from the Lynx bundle filename automatically.

Option	Type	Default	Description
webPreview	boolean	true	Enable/disable the web preview tab even if templateFiles[].webFile exists
webPreviewMode	'fit' | 'responsive' | 'auto'	'responsive'	Viewport rendering mode
designWidth	number	375	Design canvas width in pixels. Used in fit mode.
designHeight	number	812	Design canvas height in pixels. Used in fit mode.
fitThresholdScale	number	1.0	Width enter threshold for webPreviewMode='auto'. Exit back to responsive uses a built-in hysteresis band.
fitMinScale	number	0.5	Height enter threshold for webPreviewMode='auto'. Exit back to responsive uses a built-in hysteresis band.
fit	'contain' | 'cover' | 'auto'	'cover'	Fit strategy inside the fit path. auto uses built-in heuristics, including hysteresis-aware mode transitions.

Mode behavior:

Mode	Behavior
'responsive'	lynx-view fills the container. browserConfig uses measured container dimensions.
'fit'	lynx-view is fixed at designWidth × designHeight. CSS transform: scale fits it into the container. browserConfig uses design dimensions.
'auto'	Switches based on container size. Behaves like fit for small/narrow containers and responsive for wide ones, with a built-in hysteresis band to reduce resize flicker.

Auto switching logic:

const ratioW = containerWidth / designWidth;
const ratioH = containerHeight / designHeight;

// Enter condition only:
// - containerWidth < designWidth * fitThresholdScale
// - containerHeight < designHeight * fitMinScale
const shouldUseFit = ratioW < fitThresholdScale || ratioH < fitMinScale;

Exit back to responsive uses slightly larger internal thresholds, so auto does not switch back and forth on every tiny resize near the boundary.

Transition behavior:

• fit → fit on container resize: smooth transform transition
• fit ↔ responsive mode switch: hard cut, no transition

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 that 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