Versioning

Palette ties metrics and profiles to versions of your app. A version is a unique identifier tied to a build of your app.

We recommend using the current git hash as your version because it is unique and deterministic. This is the default behavior of Palette's CLI and Webpack plugin. The Webpack and Vite plugins automatically inject version into your app.

Overriding Versions

There are a few scenarios in which you should override the version:

1. git is not available in the environment you are uploading releases from (this is sometimes the case in CI)
2. You are using the CLI to upload assets instead of a Palette bundler plugin
3. You want to use version that isn't the default (ie. current git hash)

init({
  // ...
  version: "...",
});

And make sure to set the version:

CLI

palette upload --version "v1.2.3" .

Webpack

new PalettePlugin({
  // ...
  version: "...",
});

Vite

palette({
  // ...
  version: "...",
});

Providing git information

Sometimes git is not available in the environment you're uploading source maps from, especially in CI. In this cases, you can provide the necessary information in two ways:

1. Plugin Options

CLI

PALETTE_GIT_COMMIT_MESSAGE="..." PALETTE_GIT_COMMIT_HASH="..." PALETTE_GIT_BRANCH="..." PALETTE_ASSET_KEY="..." npx @palette.dev/cli upload .

Webpack

new PalettePlugin({
  // ...
  git: {
    branch: "<branch>",
    hash: "<commit hash>",
    message: "<commit message>",
  },
});

Vite

palette({
  // ...
  git: {
    branch: "<branch>",
    hash: "<commit hash>",
    message: "<commit message>",
  },
});

2. Via environment variables.

• PALETTE_GIT_COMMIT_MESSAGE: The commit message of the current commit.
• PALETTE_GIT_COMMIT_HASH: The commit hash of the current commit.
• PALETTE_GIT_BRANCH: The branch name of the current commit.

Example Usage

PALETTE_GIT_COMMIT_MESSAGE="..." PALETTE_GIT_COMMIT_HASH="..." PALETTE_GIT_BRANCH="..." PALETTE_ASSET_KEY="..." npx @palette.dev/cli upload .

Releases

When a version is marked as a release, it indicates that the version was deployed to production. Releases are used to compare metrics and profiles between versions. Releases are show in Metrics as Release Markers, which are helpful for identifying if a regression occured after a release.

By default, Palette will mark a version as a relase if the current git branch is main or master. You can override this behavior with the release option:

CLI

palette upload --release .

Webpack

new PalettePlugin({
  // ...
  release: true,
});

Vite

palette({
  // ...
  release: true,
});