Rocket
On this page

Demos#

js demo code blocks create live previews in Markdown Pages. Use them for component examples, interactive states, and small behavior samples that should render next to their source code.

Basic demo#

```js demo
import { html } from 'lit';

export const simpleButton = () => html`<button type="button">Click me</button>`;
```

Rocket renders the demo inside <rocket-preview> and displays the source code:

import { html } from 'lit';

export const simpleButton = () => html`<button type="button">Click me</button>`;

Demo exports must be named exports, must be functions, and should have unique names within the Page.

Shared demo setup#

All demos on a Markdown Page are bundled into that Page's browser module. Put shared imports or setup code in js client when several demos need the same values:

```js client
import { html } from 'lit';
```

```js demo
export const primaryButton = () => html`<button type="button">Primary</button>`;
```

```js demo
export const secondaryButton = () => html`<button type="button">Secondary</button>`;
```

The demo function receives an options object. wrapperRef points at the preview element:

```js demo
export const measuredDemo = ({ wrapperRef }) => {
  wrapperRef.dataset.ready = 'true';
  return html`<p>Ready</p>`;
};
```

Component documentation#

Use demos on component Pages when readers need to compare live states with source code:

```js client
import { html } from 'lit';
```

```js demo
export const primaryAction = () => html` <acme-button href="/setup">Read setup</acme-button> `;
```

For components rendered inside demos, use a Loading Strategy that defines the element in the browser, such as client or hydrate:*. Server-only components are best shown directly in Markdown when their rendered HTML is the complete experience.

Standalone Demo URLs#

Every named demo export on a Markdown Page also gets a generated Standalone Demo URL:

<page path>/_demo/<demo export name>/

For this Page, Rocket generates:

/reference/demos/_demo/simpleButton/

Standalone Demo URLs are public, stable child paths. They require the trailing slash. Query-string forms such as ?standaloneDemo=simpleButton are not the public URL contract.

Static and server-rendered Pages#

Static Markdown Pages write physical Standalone Demo documents during rocket build.

Server-rendered Markdown Pages use the same URL shape, but the deployment adapter routes those requests to the Page Runtime.

In both cases, the Standalone Demo document renders only the live demo. It does not include the parent Page's source panel, navigation, or surrounding docs layout.

Collisions#

Standalone Demo URLs occupy real route paths. If a configured Page collides with a generated demo path, the build fails.

Avoid configuring Pages under a Page's reserved _demo segment unless you are intentionally checking for a collision.

Tips#