> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evidence.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Guide

> Migrate a legacy Evidence project to Evidence Studio

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.

1. **Install the [Evidence CLI](/cli)** (version ≥ 0.9.0)
2. **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.
3. **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

```markdown theme={null}
---
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](/core-concepts/components), `date_grain`, comparisons, `filters`, `where`                |
| **SQL**              | DuckDB, in-browser (WASM)                              | Server-side: ClickHouse, or your warehouse's dialect via a [direct connector](/direct-connectors/snowflake)                  |
| **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](/core-concepts/variables)                                        |
| **Logic**            | Svelte/JS in pages: `{#each}`, `{#if}`, `{@const}`     | [`{% repeat %}`](/components/repeat), [`{% if %}`](/components/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](/features/page-level-access-control), [row-level access rules](/features/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](/core-concepts/models)               |
| Svelte files and custom Svelte components | [Custom components](/core-concepts/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 %}`](/components/combo_chart) with `axis="y2"` on the secondary series |
| `<ECharts>` config objects                | Move the config into the [`{% custom_echart %}`](/components/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](https://slack.evidence.dev), or [book a migration call](https://calendly.com/evidence-studio/evidence-studio-migration).