---
title: The runtime
description: The code that draws a dashboard is injected on every request and never stored, so every dashboard always runs the current runtime.
updated: 2026-09-21
---

The **runtime** is the client-side code that reads the data island, fills the
`data-dash` slots, draws the charts, and applies filters.

It is not in your published file.

## What is stored, and what is served

What the compiler stores is an empty marker:

```html
<script data-dashies-runtime></script>
```

What a viewer receives is that element filled with the current runtime bytes. The
substitution happens on the serve path, on **every request**, and the result is
never written back to storage.

So the stored file and the served file differ by exactly one script body, and the
stored file is the smaller, stabler one.

## Why it works this way

Three reasons, in order of how often they matter.

**Every dashboard always runs the current runtime.** A dashboard published a year
ago gets today's rendering fixes, today's accessibility improvements, and today's
performance work, without being republished and without its numbers being
recomputed. If the runtime had been inlined at authoring time, every dashboard
would be frozen at whatever version existed on the day it was written, and fixing
a chart bug would mean republishing every dashboard that ever used that chart.

**Authoring does not need a copy of the runtime.** Your AI tool writes markup and
a spec. It never fetches, bundles, or versions the runtime at all, so there is no
way for it to ship a stale copy.

**Refresh stays trivially safe.** The scheduler rewrites one JSON block. It never
has to reason about whether the code around that block still matches the data
inside it, because the code is not there.

## What this does not mean

It does **not** mean a dashboard phones home for its code on the viewer's
network. The runtime is inserted server-side into the same response, so a viewer
receives one document with everything in it. There is no extra request and no
external script.

It also does not mean your file is rewritten. The marker is a single valueless
attribute, and a dashboard that does not carry it streams through completely
untouched. That is how dashboards published before serve-time injection existed,
which have the runtime inlined the old way, keep working unchanged.

## The contract between them

The island and the runtime agree through a versioned contract. The island
declares its `version`, and the runtime branches on it: a version 1 island is
re-summed in JavaScript, a version 2 island runs real SQL in DuckDB-WASM, a
version 3 island is looked up cell by cell, and a version 4 island is normalized
into one or more of those.

Adding an optional field, a new format name, or a new attribute is
backwards-compatible and changes nothing. Renaming a field or changing a default
would be breaking, and would bump the version, and the runtime would branch on
it. This is why an old dashboard cannot be broken by a runtime update: the new
runtime still contains the path its island version needs.

## What the runtime is allowed to do

It fills matched slots and appends one stylesheet to the document head. It does
not replace the page body, which is what keeps anything the server injects into
it intact.

It keeps active filter state in the URL hash, which is why a filtered view is a
shareable link that survives a reload, and it stores nothing: no cookies, no
`localStorage`, no IndexedDB. It cannot, because
[the dashboard file](/concepts/dashboard-file) is sandboxed onto an opaque
origin.

The one exception to "makes no network calls" is a Parquet-backed dataset, which
is range-read from a separate host. See [The data island](/concepts/data-island).

## Next

[Spec vs hand-authored](/concepts/spec-vs-hand-authored) covers who writes the
markup those slots live in.