evidence

Evidence treats business intelligence the same way modern software teams treat application code: as text files in version control. Instead of clicking through a GUI to build dashboards, you write SQL queries inside fenced code blocks in markdown files, and Evidence compiles those queries and the surrounding prose into a fast, interactive static website.

The workflow is deliberately developer-native. You write .md files that mix SQL statements, Svelte-based chart components, and narrative text. Evidence’s preprocessing layer parses those files, extracts every named query, resolves query-to-query references (including circular-reference detection), and produces a SvelteKit application. At build time — or via a live dev server — DuckDB-WASM executes the queries client-side so the deployed site requires no backend database connection.

Evidence ships with a rich component library covering charts (line, bar, scatter, area, funnel, heatmap, bubble maps), data grids, KPI cards, and layout primitives, all built on Apache ECharts and styled with Tailwind CSS. Templated pages let a single markdown file generate hundreds of pages — one per customer, product, or region — by iterating over a query result set.

The project is structured as a pnpm monorepo with clear separation between the CLI/build tooling, the preprocessing layer, the universal SQL engine, the component library, and a growing set of datasource connectors. It supports PostgreSQL, MySQL, BigQuery, Snowflake, Redshift, DuckDB, MotherDuck, SQLite, Databricks, Trino, MS SQL, and CSV files out of the box, with a plugin interface for adding more.

What You Get

• SQL-in-markdown authoring: embed named SQL queries directly in .md files alongside prose, and reference their results in chart components on the same page
• DuckDB-WASM client-side execution: queries run in the browser via WebAssembly, so deployed reports need no live backend database
• Templated pages: generate hundreds of per-entity pages (per customer, per product) from a single markdown template iterating over a query result
• Rich component library: 30+ built-in chart types (line, bar, scatter, area, heatmap, funnel, bubble map, Sankey) plus data grids, KPI cards, and layout components, all built on Apache ECharts
• 15+ datasource connectors: PostgreSQL, MySQL, BigQuery, Snowflake, Redshift, DuckDB, MotherDuck, SQLite, Databricks, Trino, MSSQL, CSV, and a JavaScript source plugin interface
• VSCode extension with live preview, syntax highlighting, and a project scaffold command so the full development loop runs inside your editor
• Static site output deployable to Netlify, Vercel, GitHub Pages, or any CDN — no server-side runtime required after build
• Query referencing: one named query can reference another using ${queryName} interpolation, with circular-reference detection at compile time

Common Use Cases

• Internal analytics portals: engineering or data teams build self-hosted dashboards that pull from their production warehouse and deploy as a static site behind SSO
• Customer-facing reporting: SaaS companies generate per-customer report pages from a single templated markdown file, deploying a personalized analytics site for each account
• dbt project documentation and metrics: teams co-locate Evidence reports next to their dbt models, turning model outputs into live charts that update every time dbt runs
• Exploratory data notebooks: analysts write SQL alongside explanatory prose to produce shareable, version-controlled data stories that can be reviewed in a PR
• Operational reporting: ops teams schedule Evidence builds to regenerate dashboards on a cron, pushing fresh static files to a CDN without maintaining a BI server
• Executive scorecards: finance and strategy teams author KPI card layouts in markdown, connecting to Snowflake or BigQuery and deploying to an internal static host

Under The Hood

Architecture Evidence is structured as a layered pipeline inside a pnpm monorepo where each stage has a clearly bounded responsibility. User-authored markdown pages flow through a remark-based preprocessor that extracts named SQL queries, resolves cross-query references, detects circular dependencies at compile time, and transforms the markdown into SvelteKit route files. The CLI layer manages a project template that lives in .evidence/template/, syncing user files into it and delegating to the SvelteKit build system for both dev-server HMR and static site generation. A plugin architecture governs datasource connectors and component sets, so the core engine stays database-agnostic. Query execution at build time is handed to whichever connector is configured; at runtime in the browser, DuckDB-WASM handles all query execution from Parquet files cached in the static output, eliminating any live server dependency. The design is firmly in the “compile-time as much as possible” school: data is serialized to Parquet at build time, and the deployed site is fully static.

Tech Stack The frontend runtime is Svelte 4 on top of SvelteKit 2, compiled to a static adapter output. Charts are rendered by Apache ECharts 5 with an echarts-stat statistical extension, and maps use deck.gl. Styling uses Tailwind CSS 3 with a custom Evidence theme package that ships a pre-built CSS output. The query object model borrows @uwdata/mosaic-sql for SQL AST construction and tagged template literals. Client-side query execution uses DuckDB-WASM from @duckdb/duckdb-wasm. The datasource connectors are individual npm packages (postgres, mysql, bigquery, snowflake, redshift, sqlite, databricks, trino, mssql, duckdb, motherduck, csv) that each implement a standard interface defined in @evidence-dev/db-commons. Build tooling is Vite 5 with Parcel used for TypeScript type bundling in some packages. The monorepo is managed with pnpm workspaces and Changesets for versioned releases.

Code Quality The codebase mixes CommonJS and ESM across packages in a way that reflects its evolution — the preprocessing layer uses .cjs files while the SDK and component packages use ESM. Test coverage exists across the critical preprocessing path (query extraction, frontmatter parsing, referential query resolution, circular reference detection) and component utilities (formatting, data completion, column summaries), using Vitest for unit tests and Playwright for end-to-end tests across six distinct e2e scenarios covering dev server startup, HMR, base-path configuration, SPA mode, and packaging. The Query class in the SDK is well-structured with JSDoc types but without strict TypeScript. Linting is enforced via ESLint with a Svelte plugin and Prettier for formatting. CI runs lint, unit tests, and e2e tests via GitHub Actions with separate lint-format and test workflow files.

What Makes It Unique The core innovation is treating a BI report as a version-controlled text artifact rather than a GUI-produced configuration blob. Most BI tools store dashboard state in a proprietary database that is opaque to code review, diffing, or collaborative editing in a standard IDE. Evidence inverts this: SQL is the source of truth, markdown is the layout, and the output is a deployable static website that can be hosted on any CDN without a running database. The DuckDB-WASM client-side execution layer means reports remain interactive even after deployment without a backend — users can filter and explore in the browser against the pre-built Parquet files. The templated page system, which generates one route per row in a query result, is a particularly novel capability that no mainstream BI tool offers without custom engineering.

Self-Hosting

Evidence is released under the MIT license, which grants broad freedoms: you can use it commercially, modify the source, redistribute it, and embed it in proprietary systems without any obligation to open-source your own work. There are no copyleft clauses, no contributor license agreements that restrict your usage, and no license keys or telemetry checks in the open-source build path — though the CLI does include opt-in anonymous telemetry via @evidence-dev/telemetry that can be disabled.

Running Evidence yourself means operating a build pipeline rather than a live server. The primary operational burden is scheduling Evidence to rebuild and redeploy your static site whenever your data changes — typically via a cron job, a dbt Cloud job trigger, or a CI pipeline. The deployed artifact is a static website: there is no application server to keep alive, no database connection pool to manage, and no in-process query engine to scale. Your actual data warehouse or database is accessed only at build time, not at serve time. This is architecturally simpler than running Metabase or Superset, but it means freshness is bounded by how frequently you rebuild.

The managed alternative is Evidence Cloud (evidence.studio), which adds a hosted build runner, scheduled refreshes, access control, and a collaborative editing environment. The open-source version has no built-in authentication layer — protecting the deployed site requires your hosting provider’s auth (Netlify Identity, Cloudflare Access, etc.) or deploying behind a reverse proxy. For teams that need SSO, row-level security, or sub-minute data freshness, the managed offering or a custom self-hosted setup with an external auth gateway will be required.