Building a simple app

Welcome to this tutorial on how to get started with Evidence.dev, a powerful tool for creating data-driven narratives. In this guide, we’ll walk you through the initial setup process, how to connect to a CSV file, and how to create a simple app to visualize Bitcoin price data. By the end, you'll have a first understanding on how to use Evidence.dev to analyze and present your data.

Step 1: Setting up your project

First, let's set up a new project using Evidence.dev. Open your terminal and run the following commands:

npx degit evidence-dev/template bitcoin-app
cd bitcoin-app
npm install
npm run sources
npm run dev

What these commands do:

1. npx degit evidence-dev/template bitcoin-app: This command clones the Evidence.dev template into a new directory named bitcoin-app.
2. cd bitcoin-app: Navigate into the newly created project directory.
3. npm install: Install all the necessary dependencies for your project.
4. npm run sources: Set up the data sources for your project.
5. npm run dev: Start the development server, allowing you to see your project in action.

Step 2: Connecting to a CSV file

For this tutorial, we will use a CSV file containing Bitcoin price data. The data should be in the following format:

Date,Open,High,Low,Close,Adj Close,Volume
2023-05-15,26931.384766,27646.347656,26766.097656,27192.693359,27192.693359,14413231792
2023-05-16,27171.513672,27299.304688,26878.947266,27036.650391,27036.650391,12732238816
2023-05-17,27035.470703,27465.927734,26600.144531,27398.802734,27398.802734,15140006925
...

Download the csv

Setting up the CSV data source

To connect this CSV file to your Evidence.dev project, follow these steps:

1. Select the CSV Connector: Go to the Settings page in your project and select the CSV connector.
2. Name the Source: Name your CSV data source (e.g., btc_data) and click "Confirm Changes".
3. Add CSV Files: Copy any CSV files you want to query into the sources/[your_csv_source_name]/ directory. For example, place your Bitcoin CSV file in sources/btc_data/btc.csv.

Important notes:

• Your source names and CSV files can only contain letters, numbers, and underscores (e.g., /my_source/my_csv_2024.csv).
• Evidence.dev looks for CSV files stored in the sources/[your_csv_source_name]/ folder in the root of your project.

Querying the CSV file

You can query your CSV file using SQL syntax. For example, to query the Bitcoin price data, you can use:

select * from btc_data.btc

Source options

You can customize the CSV reading behavior using DuckDB source options. Here are some options you might find useful:

• header=true: Reads the first line as the header (fieldnames) of the data.
• delim=",": Uses "," characters as delimiters when reading the CSV.
• Combined Options: header=true,delim="," to use both options.

Ensure there are no spaces in your source options and use double quotes for strings.

Step 3: Creating your first page

Now that your project is set up and connected to the CSV file, let's create your first page to visualize the Bitcoin price data. Create a new file in the pages directory named bitcoin.md and add the following content:

---
title: My first app / Bitcoin
hide_title: true
---

```btc
select
    Date as date,
    Open as open,
    High as high,
    Low as low,
    Close as close,
    CASE WHEN Date = (SELECT MAX(Date) FROM csv.btc) THEN 1 ELSE 0 END AS is_max_date

from csv.btc
```

<BigValue
  title="Close Price on Last Date"
  data={btc.filter(item => item.is_max_date === 1)} 
  value=close
  sparkline=date
/>

<LineChart 
    data={btc}  
    x=date 
    y=close
    chartAreaHeight=600
/>

What this code does:

1. SQL Query: The SQL query within the code fence (btc) selects the columns Date, Open, High, Low, Close, and creates a new column is_max_date to identify the last date in the dataset.
2. BigValue Component: Displays the closing price on the last date in the dataset. The data attribute filters the dataset to only include the row where is_max_date is 1.
3. LineChart Component: Renders a line chart of the closing prices over time, with date on the x-axis and close on the y-axis. The chartAreaHeight attribute sets the height of the chart area.

Conclusion

In this tutorial, we walked through the process of setting up an Evidence.dev project, connecting to a CSV file, and creating a simple visualization for Bitcoin price data. With these steps, you can start exploring and presenting your data in a meaningful way. Experiment with different datasets and visualizations to make the most out of Evidence.dev. Happy coding!

Hope to see you in the next post.