Reference Code that runs

Annotated source

A fence marked run is shown as code and is also a module the page imports. The component that replaces pre gets that module as a prop and decides what running means: render a component, call an export, print a result.

The block is a real module in the Vite graph, not a string that is evaluated:

```svelte run
<script>
	let count = $state(0);
</script>

<button onclick={() => count++}>clicked {count}</button>
```

TypeScript is compiled, a Svelte block is compiled by vite-plugin-svelte, and its styles are scoped as in any component. Imports in the block resolve as they would in the document, so ./Button.svelte is a file beside it, and aliases and #lib/… work. The server renders it with the page, and a content security policy has nothing to object to.

On the atlas: code fence.

  • A block can't see the document's <script>. It is a module of its own, as a file would be, so share values by importing them in both, or let your component pass props to what the block exports.

See the code that runs playground example.

mdsvex hands over the module and nothing else, so a document with a block that runs needs a pre replacement, from a components module or a template. This one renders a Svelte block as a component and calls the default export of a script block, each above its code:

src/lib/markdown/Pre.svelte
<script>
	let { lang, module, load, children } = $props();

	let loaded = $state();
	const ran = $derived(module ?? loaded);
	const Demo = $derived(lang === 'svelte' ? ran?.default : undefined);
	const result = $derived(
		lang !== 'svelte' && typeof ran?.default === 'function'
			? ran.default()
			: undefined
	);
</script>

{#if Demo}
	<div class="demo"><Demo /></div>
{:else if result !== undefined}
	<output class="demo">{String(result)}</output>
{:else if load}
	<button onclick={async () => (loaded = await load())}>run</button>
{/if}
{@render children()}
src/lib/markdown.js
export { default as pre } from './markdown/Pre.svelte';
```ts run
import { format } from './dates';

export default () => format(new Date(2026, 0, 1));
```

module is the namespace of the block, so module.default is its default export and its named exports are beside it. A block without the flag gets no module, so the same component serves every fence.

  • Without a pre replacement the build fails at the fence.

Layout around a demo is a job for a directive: the pre inside it renders the demo, and the directive's component puts a frame, a title or tabs around it.

:::Example[A counter]

```svelte run
<button>…</button>
```

:::

js, ts, jsx, tsx and svelte blocks run, as do javascript and typescript. The language picks the extension of the module, which is how Vite knows what to do with it.

  • run on a block in any other language, or on one with no language, fails the build:
You write
```py run
print(1)
```

Its compile throws

Error A py block can not run, only js, ts, jsx, tsx and svelte blocks are modules (fence at /example.svx:1)

A block that touches window when it loads can't render on the server, and a heavy demo below the fold is better fetched late. run=client leaves the module out of the page and hands the component a function that imports it:

```js run=client
export default () => window.innerWidth;
```

The component gets load in place of module. Call it from an event handler or an effect, and it resolves to the same namespace module would hold. The block becomes a chunk of its own in a build.

With src= a block shows a file, and with run as well the page imports that file. The component gets src and module both.

```svelte src=./Counter.svelte run
```

The module is the whole file, also when a slice shows only some of its lines.

The id of a block's module is a hash of its language and code. In dev, an edit to one block changes only that block's import, so the page updates and every other block keeps the module it has: its top-level code doesn't run again and nothing it fetched is fetched again. Two blocks with the same code share one module.

An error in a block, at build time or in the browser, points at its line of the document.

These fail the build, each at the fence:

  • no component replaces pre;
  • the language is not one that runs;
  • the block is also live code, with the eval flag or an [!eval] marker, since braces mean different things in each;
  • run= has a value other than client.
  • A block that is live and runs:
You write
```js run eval
export default {a}
```

Its compile throws

Error A block is live with eval or runs with run, not both, its {...} groups mean different things in each (fence at /example.svx:1)

  • A value other than client:
You write
```js run=server
export default 1
```

Its compile throws

Error run= takes client, which imports the block when it is asked for, a bare run imports it with the document (fence at /example.svx:1)

compile() emits the import, but it has no bundler to serve the module from, so by default a block that runs throws a RunError. Say how the block is imported with snippets:

const { code, snippets } = compile(source, {
	filename: 'guide.md',
	snippets: true
});

true imports each block as a sibling of filename, ./guide.md.snippet-<hash>.<extension>, the id the Vite plugin uses. A function gets the snippet and returns the specifier. Either way the result has snippets, one for each module, with its hash, lang, extension, code and the line of the document the code starts on, for your bundler's resolve and load hooks to serve. snippets: false runs no block: the flag is taken out of the meta and the fence is only shown.

A block with src= imports its file, so it needs no snippets.

  • A RunError has a code (run_module, run_pre, run_lang, run_eval or run_value) and a line and column:
You write
```svelte run
<button>…</button>
```

Its compile throws

Error A block that runs is imported as a module, which compile() can not serve, pass snippets: true and serve the snippets of the result, or snippets: false to run no block (fence at /example.svx:1)

The editor shows a block that runs as code, and reports one the build would reject at its fence. It doesn't check the code as a module yet.

mdsvex, markdown with Svelte in it. MIT licence.