Environment Variables

Evidence uses environment variables for configuration, credentials, and build customization. Variables can be set in .env files or your shell environment.

Loading Environment Variables

Evidence automatically loads environment variables from .env files with the prefixes:

EVIDENCE_*
VITE_*

Example .env file:

EVIDENCE_DATA_DIR=./custom/data
VITE_EVIDENCE_SPA=true
EVIDENCE_VAR__api_key=your_api_key

Build and Output Directories

EVIDENCE_BUILD_DIR

string

default:"./build"

Output directory for production builds.

Usage:

EVIDENCE_BUILD_DIR=./dist evidence build

Used by: evidence build, svelte.config.js

EVIDENCE_DATA_DIR

string

default:"./static/data"

Directory where parquet data files are stored. Used during builds and by the dev server.

Usage:

EVIDENCE_DATA_DIR=./custom/data evidence sources

Used by: evidence dev, evidence build, evidence sources

EVIDENCE_DATA_URL_PREFIX

string

default:"static/data"

URL prefix for accessing data files in the browser. Should match the path structure of EVIDENCE_DATA_DIR relative to the static directory.

Usage:

EVIDENCE_DATA_URL_PREFIX=custom/data evidence dev

Used by: evidence dev, evidence build, evidence sources

EVIDENCE_PAGES_DIR

string

default:"./pages"

Directory containing Evidence markdown pages.

Used by: Evidence SDK

Source Configuration

EVIDENCE_SOURCE[source][option]

EVIDENCE_SOURCE__[source]__[option]

string

Override any source connection option. Replace [source] with your source name and [option] with the configuration key.

Pattern: EVIDENCE_SOURCE__<SOURCE_NAME>__<OPTION_NAME> Example:

EVIDENCE_SOURCE__my_database__host=production.db.com
EVIDENCE_SOURCE__my_database__port=5432
EVIDENCE_SOURCE__my_database__password=secret123

This overrides options in sources/my_database/connection.yaml. Used by: evidence sources

EVIDENCE_VAR__[name]

string

Variables for query interpolation. Use ${name} in your SQL queries and source configurations.

Pattern: EVIDENCE_VAR__<VARIABLE_NAME> Example: .env file:

EVIDENCE_VAR__region=us-east
EVIDENCE_VAR__api_key=abc123

SQL query (sources/mydb/orders.sql):

SELECT * FROM orders WHERE region = '${region}'

Source config (sources/api/connection.yaml):

options:
  apiKey: ${api_key}

Used by: evidence sources, query execution

Runtime and Build Flags

EVIDENCE_IS_BUILDING

boolean

default:"false"

Set to true automatically during builds to indicate build-time execution.

Automatically set by: evidence build Usage: Internal flag, automatically set. Used by Evidence to differentiate build-time from runtime behavior.

EVIDENCE_STRICT_MODE

boolean

default:"false"

Enable strict mode which fails on warnings and errors. Used by evidence build:strict.

Automatically set by: evidence build:strict Usage:

evidence build:strict

EVIDENCE_DEBUG

boolean

default:"false"

Enable debug logging for Evidence internals (Node.js environment).

Set by: --debug flag on CLI commands Example:

evidence dev --debug
evidence build --debug
evidence sources --debug

Also sets VITE_EVIDENCE_DEBUG and VITE_PUBLIC_EVIDENCE_DEBUG.

VITE_EVIDENCE_DEBUG

boolean

default:"false"

Enable debug logging in Vite build and runtime.

Set by: --debug flag or manually in .env Used by: Evidence SDK, query engine

VITE_PUBLIC_EVIDENCE_DEBUG

boolean

default:"false"

Enable debug logging in browser runtime.

Set by: --debug flag or manually in .env

Deployment and URLs

EVIDENCE_URL_PREFIX

string

default:"_evidence"

URL prefix for Evidence internal routes and assets.

Used by: Evidence SDK routing

VITE_EVIDENCE_SPA

boolean

default:"false"

Build and serve the application in single-page application (SPA) mode with client-side routing.

Usage:

VITE_EVIDENCE_SPA=true evidence build
VITE_EVIDENCE_SPA=true evidence preview

Used by: evidence preview, SvelteKit adapter

Node.js Configuration

NODE_OPTIONS

string

Node.js runtime options. Evidence automatically adds --max-old-space-size=4096 if not already set.

Auto-configured by: All Evidence CLI commands Example manual override:

NODE_OPTIONS="--max-old-space-size=8192" evidence build

Advanced Configuration

EVIDENCE_DISABLE_INCLUDE

boolean

default:"false"

Disable automatic inclusion of Evidence dependencies during the build. Advanced use only.

Used by: Build template script

Debugging Environment Variables

Use the env-debug command to see all Evidence-related environment variables:

evidence env-debug

To include values (⚠️ will show secrets):

evidence env-debug --include-values

Output:

┌─────────┬──────────────────────────┐
│ (index) │          Values          │
├─────────┼──────────────────────────┤
│ EVIDENCE_DATA_DIR │ './static/data' │
│ EVIDENCE_VAR__region │ 'us-east'    │
└─────────┴──────────────────────────┘

Environment Variable Precedence

Shell environment variables (highest priority)
.env file in project root
Default values (lowest priority)

evidence dev - Development server
evidence build - Production builds
evidence sources - Source data generation
Configuration File - Configuration files

Commands

Configuration

Environment Variables

Loading Environment Variables

Build and Output Directories

EVIDENCE_BUILD_DIR

EVIDENCE_DATA_DIR

EVIDENCE_DATA_URL_PREFIX

EVIDENCE_PAGES_DIR

Source Configuration

EVIDENCE_SOURCE[source][option]

EVIDENCE_VAR__[name]

Runtime and Build Flags

EVIDENCE_IS_BUILDING

EVIDENCE_STRICT_MODE

EVIDENCE_DEBUG

VITE_EVIDENCE_DEBUG

VITE_PUBLIC_EVIDENCE_DEBUG

Deployment and URLs

EVIDENCE_URL_PREFIX

VITE_EVIDENCE_SPA

Node.js Configuration

NODE_OPTIONS

Advanced Configuration

EVIDENCE_DISABLE_INCLUDE

Debugging Environment Variables

Environment Variable Precedence

Build docs developers (and LLMs) love

Commands

Configuration

​Loading Environment Variables

​Build and Output Directories

​EVIDENCE_BUILD_DIR

​EVIDENCE_DATA_DIR

​EVIDENCE_DATA_URL_PREFIX

​EVIDENCE_PAGES_DIR

​Source Configuration

​EVIDENCE_SOURCE__[source]__[option]

​EVIDENCE_VAR__[name]

​Runtime and Build Flags

​EVIDENCE_IS_BUILDING

​EVIDENCE_STRICT_MODE

​EVIDENCE_DEBUG

​VITE_EVIDENCE_DEBUG

​VITE_PUBLIC_EVIDENCE_DEBUG

​Deployment and URLs

​EVIDENCE_URL_PREFIX

​VITE_EVIDENCE_SPA

​Node.js Configuration

​NODE_OPTIONS

​Advanced Configuration

​EVIDENCE_DISABLE_INCLUDE

​Debugging Environment Variables

​Environment Variable Precedence

​Related

Build docs developers (and LLMs) love

Loading Environment Variables

Build and Output Directories

EVIDENCE_BUILD_DIR

EVIDENCE_DATA_DIR

EVIDENCE_DATA_URL_PREFIX

EVIDENCE_PAGES_DIR

Source Configuration

EVIDENCE_SOURCE[source][option]

EVIDENCE_VAR__[name]

Runtime and Build Flags

EVIDENCE_IS_BUILDING

EVIDENCE_STRICT_MODE

EVIDENCE_DEBUG

VITE_EVIDENCE_DEBUG

VITE_PUBLIC_EVIDENCE_DEBUG

Deployment and URLs

EVIDENCE_URL_PREFIX

VITE_EVIDENCE_SPA

Node.js Configuration

NODE_OPTIONS

Advanced Configuration

EVIDENCE_DISABLE_INCLUDE

Debugging Environment Variables

Environment Variable Precedence

Related