Skip to main content
The evidence upgrade command updates your Evidence project to the latest version of the framework and its dependencies.

​
Usage

evidence upgrade
or with npx: 
npx evidence upgrade

​
What It Does

The upgrade command performs the following actions:
  1. Checks Current Version - Determines your current Evidence version
  2. Fetches Latest Version - Checks npm for the latest @evidence-dev/evidence release
  3. Updates Dependencies - Updates Evidence packages in your package.json
  4. Installs Packages - Runs package manager install to apply updates
  5. Migrates Configuration - Updates config files if needed for breaking changes

​
Upgrade Process

1

Backup Your Project

Before upgrading, commit your changes to git:
git add .
git commit -m "Pre-upgrade backup"
2

Run Upgrade

Execute the upgrade command:
evidence upgrade
3

Review Changes

Check which packages were updated:
git diff package.json
4

Test Your App

Start the development server and verify everything works:
npm run dev
5

Rebuild Sources

Regenerate your data files with the new version:
npm run sources

​
Package Manager Support

The upgrade command works with all major package managers: 
npx evidence upgrade
Uses npm to install updated packages.

​
Version Compatibility

​
Major Version Upgrades

When upgrading across major versions (e.g., v1 → v2), review the changelog for breaking changes. Common breaking changes may include:
  • Component prop renames
  • Query syntax changes
  • Configuration file format updates
  • Deprecated features removed

​
Minor/Patch Upgrades

Minor and patch version upgrades are generally safe and include:
  • New features (minor versions)
  • Bug fixes (patch versions)
  • Performance improvements
  • Security updates

​
Upgrading Specific Packages

To upgrade specific Evidence packages without using the upgrade command: 
npm install @evidence-dev/evidence@latest
npm install @evidence-dev/core-components@latest
npm install @evidence-dev/snowflake@latest

​
Troubleshooting

Make sure you have Evidence installed locally or use npx:
npx evidence upgrade
Delete lock files and node_modules, then reinstall:
rm -rf node_modules package-lock.json
npm install
  1. Clear the Evidence cache: 
    rm -rf .evidence
  2. Rebuild your project: 
    npm run sources
npm run build
Check the changelog for renamed or deprecated props in the new version. The upgrade may include breaking changes.

​
Manual Upgrade Process

If the automatic upgrade fails, you can manually upgrade:
1

Check Latest Version

Find the latest version on npm:
npm show @evidence-dev/evidence version
2

Update package.json

Edit your package.json to use the latest version:
{
  "dependencies": {
    "@evidence-dev/evidence": "^XX.X.X"
  }
}
3

Install Updates

Run your package manager:
npm install
4

Update Datasources

If you use datasource plugins, upgrade them too:
npm install @evidence-dev/snowflake@latest
npm install @evidence-dev/postgres@latest

​
Staying Updated

​
Check Current Version

See your installed Evidence version: 
npm list @evidence-dev/evidence
Or check in your Evidence app’s settings page.

​
Release Notes

Stay informed about updates:

​
Update Frequency

Evidence follows semantic versioning:
  • Patch releases (X.X.1) - Weekly, safe to upgrade immediately
  • Minor releases (X.1.0) - Monthly, new features, backward compatible
  • Major releases (2.0.0) - Rarely, may include breaking changes

​
Best Practices

Test Before Deploying

Always test upgrades in development before deploying to production

Use Version Control

Commit changes before and after upgrading to easily roll back if needed

Read Release Notes

Review the changelog to understand what’s changing

Update Regularly

Stay up to date with security patches and bug fixes

Build docs developers (and LLMs) love

Get started for freeTalk to us