How to Build Data Reports with Evidence.dev

Evidence.dev is an open-source framework that lets analysts build published data reports by writing SQL queries inside Markdown files. Instead of configuring a drag-and-drop BI tool, you define your queries in code, and Evidence renders them as a live, deployable website with charts and tables. This guide covers installation, connecting a data source, writing your first report, and deploying it for your team.

What Evidence.dev Is and Who It Is For

Evidence works best for analysts and ops teams who know SQL but find tools like Tableau or Looker Studio slow to configure and hard to maintain. Rather than building dashboards in a GUI, you write .md files that contain SQL blocks. Evidence runs those queries against your data source and renders the results as charts, tables, and narrative text on a published website.

The framework requires Node.js 18 or newer and a working knowledge of SQL. No drag-and-drop, no visual query builder. The output is a static website you can host on Netlify, Vercel, or GitHub Pages.

The core advantage over tools like Metabase or Looker Studio is version control: because every report is a plain Markdown file, your team can manage it with Git, review changes in pull requests, and roll back if something breaks. According to the Evidence team, reports built with the framework load in under 100 milliseconds because all queries are pre-computed at build time and the resulting site is fully static, with no database round trips at view time.

Step 1: Install Evidence

Evidence is installed via a Node.js template. Open your terminal and run:

npm create evidence@latest

This command scaffolds a new project directory with sample reports, components, and a configuration file. After the project is created, navigate into the directory and install dependencies:

cd my-evidence-app
npm install

System requirements: Node.js 18, 20, or 22; npm 7 or higher; Git.

If you prefer VS Code, install the official Evidence VS Code extension. It handles dependency installation automatically and opens a live preview at localhost:3000 when you click "Start Evidence" from the command palette.

Step 2: Connect Your Data Source

Evidence supports DuckDB, PostgreSQL, MySQL, BigQuery, Snowflake, Redshift, SQLite, and flat files including CSV and Parquet. You configure connections in the sources/ folder.

For a quick start with a CSV file, create a folder under sources/ named after your source (for example, sources/sales/), then place your CSV file inside it. Evidence uses DuckDB under the hood, so you can query CSV files directly without loading them into a database first.

If your file is sources/sales/monthly_revenue.csv, you can query it in any report as:

select * from sales.monthly_revenue

For a PostgreSQL connection, add a file at sources/my_db/connection.yaml:

name: my_db
type: postgres
host: your-db-host
database: your-database
port: 5432

Evidence will prompt for credentials on first run and store them securely in your local environment. For production, set credentials as environment variables prefixed with the source name.

Run npm run sources to test your connection and cache query results locally. This step matters: Evidence pre-computes all source data so reports load from static files at view time, not live database queries.

Step 3: Write Your First Report

Reports in Evidence are Markdown files stored in the pages/ folder. Each file becomes a URL path on your published site.

Create a new file at pages/revenue.md. Open with a brief summary, then add a SQL block and a chart component:

# Monthly Revenue Report

This report shows revenue by month for the current fiscal year.

\`\`\`sql monthly_rev
  select
    date_trunc('month', sale_date) as month,
    sum(amount) as revenue
  from sales.monthly_revenue
  where sale_date >= '2025-01-01'
  group by 1
  order by 1
\`\`\`

<LineChart
  data={monthly_rev}
  x="month"
  y="revenue"
  title="Revenue by Month"
/>

<DataTable data={monthly_rev} />

The SQL block named monthly_rev runs against your connected source and makes the result available as a variable you can pass to any chart or table component. Evidence ships with over 40 chart types and components including <BarChart>, <ScatterPlot>, <BigValue>, and <DataTable>.

Key rules: SQL blocks are named by the word after the opening triple backtick. Component props like data={my_query_name} reference the SQL block by name. You can have multiple SQL blocks on one page; each becomes its own variable.

Step 4: Preview Locally

Start the development server:

npm run dev

Your browser opens at localhost:3000. Evidence hot-reloads when you save a file, so changes appear within seconds. If your SQL has errors, Evidence highlights them in the browser with the exact line and column number.

During local development, Evidence uses cached source data from the npm run sources step. You do not need a live database connection open in your terminal while writing reports.

Step 5: Add Filters and Interactivity

Evidence supports page-level filters using input components. To add a date range selector to the revenue report:

<DateRange name="date_range" />

Then reference the values inside your SQL block using Evidence's template syntax:

  select
    date_trunc('month', sale_date) as month,
    sum(amount) as revenue
  from sales.monthly_revenue
  where sale_date between '${inputs.date_range.start}' and '${inputs.date_range.end}'
  group by 1
  order by 1

Evidence re-runs the SQL client-side using DuckDB-WASM when a filter changes, with no server round-trip. Other filter components include <Dropdown>, <TextInput>, <Checkbox>, and <ButtonGroup>.

Step 6: Deploy Your Reports

Evidence builds a static site that you can host on any web server. To generate the build output:

npm run build

The output goes into the build/ directory.

For Netlify: connect your Evidence project's Git repo to Netlify. Set the build command to npm run sources && npm run build and the publish directory to build. Netlify rebuilds automatically on every Git push.

For Vercel: use the same approach, setting the framework to "Other" during project setup and using the same build command.

For GitHub Pages: use the official Evidence GitHub Action available in the Evidence documentation. It handles the build and deployment on push to your default branch.

For teams that need report data to refresh on a schedule, configure a scheduled CI/CD pipeline. The npm run sources step re-runs your source queries and refreshes cached data before the build runs.

If the configuration overhead of this setup is a blocker, VSLZ handles query generation and chart rendering from a file upload with no configuration needed.

Step 7: Manage Reports with Git

Because Evidence files are plain Markdown and SQL, every report lives in your Git history. Use branches to develop new reports, open pull requests for team review, and merge to your main branch to publish.

A practical workflow for teams: create a branch for a new report or change, write and preview locally with npm run dev, open a pull request so teammates can review the SQL and Markdown, then merge to main for CI/CD to build and deploy. This gives you a full audit trail of every report change and catches SQL errors before they reach stakeholders.

Practical Summary

Evidence.dev is a strong choice for analytics teams who want version-controlled, code-driven reports without paying for a heavyweight BI platform. Setup takes under 30 minutes for a CSV-based project. A database-connected project with Netlify deployment typically runs two to three hours end to end.

The main limitation is that Evidence is not a no-code tool. You need SQL for queries and comfort with the command line for setup and deployment. If your team has those skills, Evidence gives you more control, reproducibility, and transparency than most drag-and-drop alternatives at zero licensing cost.