Skip to main content

​
Quickstart

Get Evidence up and running in under 5 minutes. This guide will walk you through creating a new Evidence project, starting the development server, and creating your first interactive page.
1

Create a new Evidence project

The fastest way to start is using the VSCode extension, but you can also use the command line:
npx degit evidence-dev/template my-project
cd my-project
npm install
This creates a new Evidence project with:
  • Demo data (a DuckDB database called needful_things)
  • Example pages in the pages directory
  • Pre-configured data sources
2

Run your data sources

Evidence transforms your SQL queries into a unified data cache. Run the sources command to build this cache:
npm run sources
This step executes all your source queries and creates .parquet files that Evidence uses to power your pages.
3

Start the development server

Launch the Evidence development server:
npm run dev
Your browser should automatically open to http://localhost:3000. You’ll see the Evidence welcome page with the template app.
The development server supports hot module replacement (HMR). Save any markdown file and see your changes instantly in the browser - no restart required.
4

Create your first page

Navigate to the pages directory and create a new file called my-first-page.md:
# My first Evidence page

## Query your data

```sql orders_summary
select 
    count(*) as total_orders,
    sum(sales) as total_sales,
    avg(sales) as avg_order_value
from needful_things.orders
```

## Display results

We've had <Value data={orders_summary} column="total_orders"/> orders totaling 
<Value data={orders_summary} column="total_sales" fmt="usd"/>.

## Visualize with a chart

```sql orders_by_month
select 
    date_trunc('month', order_datetime) as month,
    count(*) as orders,
    sum(sales) as sales
from needful_things.orders
group by month
order by month desc
limit 12
```

<BarChart 
    data={orders_by_month}
    x="month" 
    y="sales"
    title="Sales by Month"
/>
Save the file and navigate to http://localhost:3000/my-first-page to see your new page.
5

Add a data table

Let’s display the top 10 customers. Add this to your page:
## Top customers

```sql top_customers
select 
    customer_name,
    count(*) as order_count,
    sum(sales) as total_spent
from needful_things.orders
group by customer_name
order by total_spent desc
limit 10
```

<DataTable data={top_customers}/>
The DataTable component automatically formats your data with sorting, filtering, and pagination.

​
Understanding Evidence syntax

Evidence uses Evidence-flavored Markdown which extends standard markdown with:

​
SQL code fences

Queries are written in code fences with a unique name: 
```sql query_name
select * from table
```
The query results become available to all components on the page as {query_name}.

​
Components

Components use angle brackets like HTML: 
<ComponentName 
    data={query_name}
    prop1="value"
    prop2={variable}
/>

​
Inline values

Display query results inline: 
Total revenue: <Value data={sales} column="revenue" fmt="usd"/>

​
Loops and conditionals

Use Svelte-style syntax for control flow: 
{#each customers as customer}
- {customer.name}
{/each}

{#if revenue > 1000000}
We hit our target!
{:else}
Keep pushing!
{/if}

​
Next steps

Connect your data

Replace the demo data with your own database or data warehouse

Explore components

Browse the full library of charts, tables, and UI components

Deploy your app

Learn how to deploy your Evidence app to production

View examples

Explore the Needful Things demo app on GitHub

​
CLI commands reference

Here are the most common Evidence CLI commands:
CommandDescription
npm run devStart the development server on port 3000
npm run sourcesBuild source queries and create data cache
npm run buildCreate a production build in the build directory
npm run previewPreview the production build locally
npx evidence sources --changedOnly rebuild changed source queries
npx evidence sources --strictFail if any source query fails
Add the --debug flag to any command for verbose logging: npm run dev -- --debug

​
Troubleshooting

If you see a warning about missing source manifest, run npm run sources to generate the data cache.
The Evidence dev server runs on port 3000 by default. If this port is already in use, you can specify a different port:
npx vite dev --port 3001
Make sure you’ve saved your file (Ctrl+S or Cmd+S). If changes still don’t appear, try refreshing your browser or restarting the dev server.
Ensure your query name in the code fence matches the name you’re using in components. Query names are case-sensitive.
Need help? Join the Evidence Slack community where the team and community members are ready to help.

Build docs developers (and LLMs) love

Get started for freeTalk to us