Migration Guide - Evidence Docs

Legacy Evidence is a static website generator: Markdown and DuckDB SQL which queries data you package up in a build step. Evidence Studio has a live connection to a database, and an updated set of components that can generate SQL.

How to migrate

The CLI has a evidence migrate command. It converts everything it can mechanically — component syntax, attribute names, input references, connections, source SQL - and prints a warning for items it cannot migrate. The fastest path is to let a coding agent support your migration.

Install the Evidence CLI (version ≥ 0.9.0)
Add the migration skill to your project: Save the file below into your legacy project as .claude/skills/evidence-migrate/SKILL.md, or the equivalent path for your assistant.
Ask your assistant to migrate the project: “Migrate this Evidence project to Studio syntax.” The skill tells it which commands to run and how to work through the warnings.

To run it yourself: evidence migrate --dry-run to preview, evidence migrate to convert in place, then evidence validate for syntax and SQL errors and evidence dev to inspect the result.

The migration skill

---
name: evidence-migrate
description: Migrate a legacy Evidence (Svelte-syntax) project to Core syntax using the CLI. Use when a project contains legacy Evidence markup (<LineChart/>, sources/ directory, ${inputs...} references) or the user asks to migrate/upgrade an Evidence project.
---

# Migrating Legacy Evidence Projects

Legacy Evidence used a syntax and framework based on Markdown, Svelte and SvelteKit. Core is the current version, using Markdoc and a custom file router.

Key differences include:

- Support for one data warehouse only
- SQL written in native dialect not DuckDB
- SQL executes against a backend, not in browser with WASM
- Different component syntax
- Core expresses config not code, JS is not executed

In order to migrate to Core syntax perform the following steps

1. Ensure the latest Evidence CLI is installed: `evidence version` ≥ 0.9.0. If not, install `curl -fsSL https://evidence.studio/install.sh | sh` or `irm https://evidence.studio/install.ps1 | iex`
2. In the Evidence directory, run `evidence migrate` — this will best-effort migrate the contents to Core syntax, and flag any issues or unsupported features
3. `evidence validate` should pick up any syntax errors, and if the connection is configured correctly, SQL errors also
4. `evidence dev` renders the site to visually inspect.
5. Recursively fix errors from the migrate command and validate command on a best-efforts basis. Use `evidence docs` to look up Core component syntax: `evidence docs component <name>` shows a component's attributes, `evidence docs list` lists all components, `evidence docs search <query>` searches the documentation.
6. Render the site for the user to inspect and provide further instruction, it is quite likely that it will require judgement to complete migration as features are not 1-to-1.

What works differently

	Legacy Evidence	Evidence Studio
Component syntax	Svelte: `<LineChart data={orders} x=date y=sales />`	Markdoc: `{% line_chart data="orders" x="date" y="sum(sales)" /%}`
Component data	Renders a query you wrote	Writes its own SQL — aggregations, `date_grain`, comparisons, `filters`, `where`
SQL	DuckDB, in-browser (WASM)	Server-side: ClickHouse, or your warehouse’s dialect via a direct connector
Data prep	`sources/*.sql` queries run at build	Sync data to Evidence on a schedule, or update your data warehouse
SQL files	`queries/*.sql`, interpolated with `${inputs.x.value}`	`/queries/.sql` inlined verbatim — `{{ }}` variables do not* resolve; move input-driven SQL into a SQL block on the page
Variables	`${inputs.category.value}`	`{{category}}`, or `filters=["category"]` — see Variables
Logic	Svelte/JS in pages: `{#each}`, `{#if}`, `{@const}`	`{% repeat %}`, `{% if %}`
Builds	Build required for every data or content change	No build, Queries re-run on page load
Deployment	Configure hosting and a build pipeline	Publish in seconds, from Evidence Studio or linked GitHub repo
Scale	~2M rows	Hundreds of millions of rows
Access control	Build it yourself	SSO, page permissions, row-level access rules, user groups
Self-service	Reports	Reports + Insights + AI Chat

Not supported

Legacy feature	Instead
Templated pages (`[param].md`)	One page driven by an input — a dropdown wired to every component via `filters`
Source SQL queries (`sources/`)	Sync the table, or a view in your database, then use Models
Svelte files and custom Svelte components	Custom components, or `{% custom_echart %}` / `{% html %}`
JS expressions and Svelte blocks in pages	`{% repeat %}`, `{% if %}`, or compute it in SQL
Box plots, Venn diagrams	No equivalent
Drill-through links on maps	No equivalent — maps support tooltips only
Secondary y-axis (`y2=`)	Rebuild as `{% combo_chart %}` with `axis="y2"` on the secondary series
`<ECharts>` config objects	Move the config into the `{% custom_echart %}` body
Horizontal 100% stacked bars	Regular stacked `{% horizontal_bar_chart %}`

Individual attributes without an equivalent are dropped with a warning by evidence migrate; run it with --dry-run to see the full list for your project.

Getting help

Ask in the Slack community, or book a migration call.

⌘I