Don't worry if this is your first time using any of the tools referenced in this walkthrough - we will guide you through all the steps. If you need help, send us a message on Slack. We're here for you!
You will need an IDE (integrated development environment) or text editor to work with Evidence. We like VSCode (Visual Studio Code) because of its layout, integrated console/terminal, and extension library.
VSCode has an extensive documentation site which you can find at this link: https://code.visualstudio.com/docs
The rest of this walkthrough will be done through a terminal. You can either use your own terminal, or open one directly in your IDE.
If you are using VSCode, the shortcut to open a new terminal is
There are several ways to install both Node.js and npm and it can be quite confusing to search through the alternatives. Our recommendation is to use nvm (Node Version Manager) - this is a package you download that will help you install Node.js and npm, and makes it easier to manage/change versions.
When installing packages, if you are ever presented with an option to download a "stable" or "supported" version vs. a "current" version, you should choose the stable version because it has been released for some time and the package creator has worked through a lot of the issues/bugs with it. Current or newest versions often contain features that are still in development or haven't been fully vetted.
Below are the versions of Node.js and npm you will need to install Evidence:
Node Version 14.17.6
14.17.6 is the most recent stable version of Node as at the time this was written. Should this page ever be out of date, check the Node.js website to see ther version number listed as LTS (long-term support).
Check which version you have with
NPM Version 7 or greater
Check which version you have with
Run the following commands in your terminal to install nvm. This will download and run an install script from the nvm GitHub repo:
Run the command below to check that nvm was successfully installed (if the command runs and returns a version number, it's been installed):
This will print a list to your console of all available Node.js versions. If you're switching versions, you should find the largest version number listed as LTS (Long-term support). Typically there will be a stable version and a "current" version listed. The current version is in development now and may not work with Evidence.
Take the version number you found in the previous step and include it in the command below. This will install Node.js and npm at the same time:
If you are unsure which version of Node.js or npm you have, you can run the following commands in your terminal:
-v means version. You can use this command to check versions of any package you have installed. If your npm version number is under 6, you can update npm with the following command:
Nvm makes it easy to switch between different versions.
Switch between versions using the command below. When you switch Node.js versions, it will automatically change your npm version to match.
Once you have the right Node.js and npm versions installed, you're ready to create your Evidence project!
Help us improve the docs
If any of the steps above are out of date, you can check out the npm website for current details: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
npx degit is a command to download the code from a github repository. This is going to download our template project and place it into a directory called 'my-project'.
my-project is the name of the directory that will be created on your computer. You can change this name to whatever you'd like.
After this step, you will have the files you need (they will be in the
my-project folder that was created). The next step is to install any required packages or dependencies in those files.
You will need to run an installation on your new directory using the
install command in npm. This will identify and download any dependencies from the files in the Evidence package.
For example, Evidence utilizes other npm packages and will require specific versions of those packages - npm handles all of this for you.
The command will work on whichever directory you are in when you run it, so navigate to your new directory:
cd means change directory - we are telling the terminal to go into the my-project directory.
Now that we are in our project, we can run the installation step:
npm will add all dependencies to the
node_modules folder in your project.
The Evidence VS Code extension enables syntax highlighting and basic autocomplete. You can install the extension in 2 ways:
In VS Code, search for "Evidence" in the Extensions menu and click to install
Install from the the VS Code Marketplace webpage
See VS Code Extension for more information about the extension.
The VS Code extension is not required to build an Evidence project, but it makes the experience of writing your project smoother.
That's it for installation - now you can start your server and use Evidence.
Since you are working with Evidence in development mode, you'll be using a development server which runs on your local computer. This server watches for changes in your markdown documents, and quickly translates them into updated pages in your project.
Use the command below in your terminal to start the dev server:
To stop the dev server, use
When the dev server is running, you will be able to see your pages in your browser at localhost:3000
If you have not tried web development before,
localhost:3000 may look foreign to you. This is your URL for local web development and tells your browser where to send requests. You can think of it in the same way as a normal URL like
localhost:3000 in your browser tells your browser to send a request to the local server which is using port 3000. If your development server is running, it will receive that request and send back the files needed to display your webpage.
On your Evidence page, if you click the Querying Data link, you'll see the name of the page appended to the URL, just as you would see on a normal website:
You may need to run your Evidence project on a different port (for example, if you have other programs running and port 3000 is already occupied). If you need to run your Evidence project on a different port than 3000, follow the steps below:
- Open the
package.jsonfile in the root of your project. This file provides a list of instructions for your project, including which scripts to use to run various commands, as well as which versions of packages are needed to run the project
- Under scripts, look at the dev line. This is the script your project will use in the background when you run the
npm run devcommand in your terminal. By default, this script uses port 3000
svelte-kit dev, where
XXXXis the port number you'd like to use. This will override the port used when running the dev server
The new dev line should look like this:
Example (using port 8080):
We've run the following four commands in our terminal, and we should have a working Evidence site visible in our web browser at
Now that you're all set up, you can keep working through the getting started guide. The next step is to take a look at the files in your new project.
If you need help with any of this, reach out to us on Slack.