Evidence VS Code

The official VS Code extension for Evidence projects.
Evidence is a Markdown-based business intelligence tool. Connect to your database, write SQL queries, and include charts, tables, and dynamic text - all from Markdown. To get started, visit the docs.
This extension provides language support, Evidence project and dev server shortcut commands, markdown Preview and autocomplete for the Evidence Markdown files.

Features
- Syntax highlighting for:
- Markdown
- SQL Query Blocks
- Components (Svelte syntax highlighting)
- JavaScript expressions
- Autocomplete suggestions for inserting:
- Components (Charts, Tables, Text Components)
- SQL Query Blocks
- Templating (Loops, Conditionals)
- Evidence commands to:
- Create new project
- Install dependencies
- Start and stop dev server
- Update to the latest version
- Open app settings file
- View extension settings
- Clear app data and queries cache
- Build app for deployment to production
- Preview Evidence markdown documents
Requirements
Evidence dev server and this extension require Node.js version 16.14
or higher. You can download and install the latest version from nodejs.org.
This extension also depends on Svelte for VS Code that provides syntax highlighting and rich intellisense for Svelte components in VS Code. Svelte for VS Code will be installed automatically when you install Evidence extension.
Installation
You can install Evidence extension from the VS Code Marketplace, or by searching for Evidence
in the VS Code Extensions tab.

Getting Started
To get started with Evidence BI application development using VS Code desktop version, follow these steps:
- Create new project folder and open it in VS Code from the command line:
mkdir evidence-app
cd evidence-app
code .
- Find and use new
Evidence: New Evidence Project
command shortcut in VS Code View -> Command Palette..
menu to create new Evidence project using the built-in extension /template app project.

- Use
Evidence:
VS Code commands described below to install dependencies, start and stop dev server, and preview Evidence BI app content.
Running Evidence app in GitHub Codespaces
You can use Evidence VS Code extension with GitHub Codespaces.
- Open Evidence template project github repository in a browser.
- Click the green
Use this template
button, and select Open in a codespace
.
- Install Evidence extension in the Codespace when prompted.
- Use new Evidence status bar and commands to run and Preview
template
Evidence app.

Commands
Evidence extension provides a number of custom VS Code shortcut commands for Evidence projects. You can access them from View -> Command Palette...
menu (ctrl/cmd+shift+p
) by typing Evidence
in the command search box:

Command |
Title |
Description |
newProject |
New Evidence Project |
Create new Evidence project in the open workspace, or the selected folder in VS Code File Explorer. |
createProjectFromTemplate |
Create Project from Template |
Create new Evidence app project from template. |
openSettings |
Open Settings File |
Open Evidence app settings file in VS Code JSON editor. |
installDependencies |
Install Dependencies |
Install Evidence app NodeJS modules. |
updateDependencies |
Update to Latest Version |
Update all Evidence app NodeJS libraries to the latest version. |
startServer |
Start Dev Server |
Start Evidence app dev server. |
stopServer |
Stop Dev Server |
Stop Evidence app dev server. |
preview |
Preview |
Preview Evidence app using built-in VS Code Simpler Browser. |
clearCache |
Clear Cache |
Clear Evidence application data and queries cache. |
build |
Build |
Build Evidence app for deployment to production. |
buildStrict |
Build Strict |
Build Evidence app for deployment to production in a strict mode. |
showOutput |
Show Output |
Show Evidence extension output in Output view. |
viewSettings |
View Settings |
View Evidence extension settings in the built-in VS Code Settings editor. New Evidence extension settings will be released in the upcoming v1.1.0 . |
Settings
Create User or Workspace Settings to change default Evidence VS Code extension Settings.
Open Evidence extension Settings in VS Code by navigating to File -> Preferences -> Settings
(cmd/ctrl+,
) and searching for Evidence
in the Settings search box.

VS Code Settings JSON
You can also reconfigure Evidence extension settings in vscode/settings.json
workspace configuration file. The .vscode/settings.json
file is a JSON
file that stores your VS Code Settings. It contains settings that apply globally to all workspaces open in VS Code, or to a specific workspace.
Edit your settings in ./vscode/settings.json
by opening the Command Palette...
with cmd/ctrl+shift+p
, searching for and selecting Preferences: Open Workspace Settings (JSON)
command.

Evidence Settings
All Evidence extension settings start with evidence.
prefix. You can overwrite default Evidence extension settings in the open workspace directly by opening and changing /.vscode/settings.json
in your project.
The following Evidence project workspace /.vscode/settings.json
example sets different default Evidence dev server port, overwrites new dev server autoStart
setting, and uses a modified local copy of the built-in Evidence /template
project with file://
Uri to create new Evidence projects.
{
"evidence.defaultPort": 5000,
"evidence.autoStart": "false",
"evidence.templateProjectUrl: "file://E:/projects/evidence.dev/template"
}
Evidence extension v1.1.0
now has two new settings to allow overwriting default Evidence dev server port when running it locally in VS Code desktop IDE, or opening an Evidence project github repository in Codespaces.
Setting |
Type |
Default Value |
Name |
Description |
evidence.defaultPort |
number |
3000 |
Default Port |
Default Evidence app dev server port. |
evidence.autoStart |
boolean |
true |
Auto Start |
Automatically start Evidence app dev server when opening a project. |
evidence.templateProjectUrl |
Url string |
/template |
Template Project Url |
Evidence template project GitHub Url or local file:// path to the project template folder to use when creating new Evidence projects. Defaults to the built-in Evidence extension /template project that ships with this extenstion for faster New Evidence Project scaffolding. |
You can request new Evidence extension settings to enhance this extension user experience in VS Code by submitting a feature request or pull request.
Limitations
Our first version of Evidence VS Code extension with new interactive commands has the following limitations:
- New commands only work in workspaces that have
/pages
and other Evidence BI application files at the root of the open project (#25)
- Open Evidence markdown documents do not display Outline (#33)
- Preview and Start/Stop Dev Server commands do not perform dynamic free port lookup yet.
(#31) You can change the default Evidence app dev server port from
3000
to another unoccupied port using new evidence.defaultPort
extension configuration settings added in (#52)
- Preview of the open Evidence markdown document for the templated pages doesn't properly rewrite template page Urls (#30)
We plan to address these shortcomings in the upcoming releases.
Dev Build
To build the latest version of Evidence VS Code extension from source:
- Clone this github repository and run the following commands from the command line:
$ git clone https://github.com/evidence-dev/evidence-vscode
$ cd evidence-vscode
$ npm install
$ npm run compile
$ code .
- Press
F5
to start debugging Evidence VS Code extension.
- Open any Evidence project folder in the new
Extension Host Window
to try updated extension commands and features.
Note: Disable Evidence extension installed from marketpace to see your code changes reflected in the running host extension window during debug.
See the official Debugging extension documentation for more information about developing extensions in VS Code.
Support
If you run into any issues setting up the extension, please reach out: