How to Build Reports with Evidence.dev

Evidence is an open source framework that lets you build interactive data reports by combining SQL queries with Markdown files. You write source queries in SQL, add chart and table components to Markdown pages, and Evidence renders everything as a static website. The result is a shareable report that lives in version control, deploys in one command, and requires no live database connection once built.

What Evidence Is and Why Teams Use It

Evidence was designed as a code-first alternative to drag-and-drop BI tools. Instead of clicking through a dashboard builder, you write a .md file with SQL queries embedded in it. Those queries run against your data source, and Evidence renders the results as charts, tables, or summary values directly in the page.

The practical benefit is version control. Your reports live in Git alongside your dbt models or SQL pipelines. You can review them before shipping, roll back a change that broke a chart, and deploy the whole thing the same way you deploy code. As of 2026, Evidence is ranked among the six strongest open source BI options alongside Metabase, Apache Superset, and Lightdash, according to comparisons published by Basedash and Holistics.

The tradeoff is that Evidence is not a low-code tool. You write SQL, navigate a file editor, and run npm commands. Non-technical stakeholders can consume your reports once deployed, but they cannot build them. If that matches your team structure, the setup is worth it.

Prerequisites

Before you start, confirm you have:

• Node.js version 18.13, 20, or 22 (check with node -v)
• npm version 7 or higher (check with npm -v)
• A SQL data source: PostgreSQL, Snowflake, BigQuery, DuckDB, MySQL, SQLite, or a CSV file

If you're on an older Node version, update using the official installer at nodejs.org or use nvm to switch versions without touching your global install.

Step 1: Create a New Evidence Project

Run the official template using npx:

npx degit evidence-dev/template my-report
cd my-report
npm install
npm run dev

Your browser will open to localhost:3000 automatically. You'll land on a demo report built on a sample DuckDB dataset called needful_things. This is your local development server. Every file you change hot-reloads in the browser instantly, no restart needed.

The key folders in your project:

my-report/
├── sources/          # data source config and SQL queries
├── src/
│   └── pages/        # your report pages (.md files)
└── package.json

Step 2: Connect Your Data Source

Navigate to localhost:3000/settings in your browser. This is Evidence's data source configuration panel.

Click "Add data source" and select your database type. Evidence supports DuckDB, PostgreSQL, MySQL, BigQuery, Snowflake, Redshift, SQLite, CSV files, and additional sources via community plugins. Enter your connection details and credentials. Evidence saves non-secret config to a connection.yaml file and credentials to a connection.options.yaml file (base64 encoded), both inside the relevant sources/ subfolder.

If you're connecting a CSV file, Evidence routes it through DuckDB internally, so no separate database installation is required.

Your source folder structure will look like this:

sources/
└── my_database/
    ├── connection.yaml
    ├── connection.options.yaml
    └── orders.sql

Step 3: Write Source Queries

Source queries are .sql files inside your data source folder. They run directly against your database using that database's SQL dialect, and the results are stored in Evidence's internal DuckDB data cache.

Create a file at sources/my_database/monthly_revenue.sql:

select
  date_trunc('month', order_date) as month,
  sum(revenue) as total_revenue,
  count(*) as order_count
from orders
where order_date >= '2024-01-01'
group by 1
order by 1

Save the file. The dev server will re-run the query automatically if it's running. You can also trigger it manually:

npm run sources

Running sources populates the data cache. After this step, your pages can query my_database.monthly_revenue using DuckDB SQL, regardless of whether the underlying database is still reachable.

Step 4: Build a Report Page

Pages are .md files inside src/pages/. Create src/pages/revenue.md.

First, write a Markdown query. This is a SQL code block with a name, written in DuckDB dialect, that queries your data cache. Components on the page reference the query by name.

## Monthly Revenue

\`\`\`revenue_summary
select * from my_database.monthly_revenue
\`\`\`

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

<DataTable data={revenue_summary}/>

Save the file and navigate to localhost:3000/revenue. You'll see a line chart and a data table rendered from your query results.

The component syntax is JSX-style, but you don't need to know React or Svelte. Evidence pre-builds all components. You pass the query name and column names as props.

Step 5: Add Charts and Filters

Evidence ships with a full library of built-in components:

Charts: LineChart, BarChart, AreaChart, ScatterPlot, Histogram, FunnelChart, SankeyDiagram, Heatmap, CalendarHeatmap, Sparkline

Data display: DataTable, Value (single number), BigValue (large KPI block), Delta (change indicator with arrow)

Maps: AreaMap, BubbleMap, PointMap, USMap

Inputs: Dropdown, DateInput, DateRange, Slider, TextInput, ButtonGroup

A bar chart broken down by product category takes two additions to your page:

\`\`\`category_breakdown
select category, sum(revenue) as revenue
from my_database.monthly_revenue
group by category
order by revenue desc
\`\`\`

<BarChart data={category_breakdown} x="category" y="revenue"/>

Dropdown filters connect an input component to a SQL WHERE clause in your Markdown query. When a user selects a value, the query re-runs against the cache and the charts update. No round-trip to the database is required.

Step 6: Deploy Your Report

Build the static output:

npm run build

This runs your source queries, executes all Markdown queries, and renders every page to HTML. The output lands in a build/ folder.

You can deploy to Vercel with one command from the project root:

npx vercel deploy --prod

Evidence also supports Netlify, Cloudflare Pages, GitHub Pages, AWS Amplify, Azure Static Apps, Firebase, and Hugging Face Spaces. Once built, the static output needs no live database connection. The report loads fast and stays available even if your database goes down.

For reports that need to refresh on a schedule, connect Evidence's build step to a cron job in your CI/CD pipeline or use Vercel's scheduled deployments. A daily 6am rebuild costs nothing on Vercel's hobby tier for most report sizes.

When Evidence Makes Sense

Evidence is worth the setup time when you have a recurring report that analysts update manually today, when the data lives in a warehouse you already query with SQL, and when the audience is internal. The one-time cost of writing the Markdown page and source queries is paid back quickly on any report that runs more than once a month.

It is not the right tool for real-time dashboards, for teams without anyone comfortable writing SQL, or for customer-facing reports that need access controls beyond basic password protection.

Summary

Evidence turns SQL queries into version-controlled, deployable data reports in about 20 minutes of setup. Connect a data source, write source queries in SQL, build pages in Markdown using pre-built chart and table components, and deploy as a static site. For teams already working with SQL pipelines, it slots naturally into the existing workflow without adding a new BI platform to maintain.