The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
Docs for development on the custom-viz package
These docs cover building and releasing the @metabase/custom-viz package locally. If you just want to use the package, see the README.
Prerequisites
- Node.js >= 20
- bun >= 1
Development
# Install dependencies
bun install
# Build in watch mode
bun run dev
# Production build
bun run build
Linting & Formatting
# Lint (uses oxlint)
bun run lint
# Format code
bun run format
# Check formatting
bun run format:check
Releasing
Releases are published via the Release Custom Viz Package GitHub Actions workflow (.github/workflows/release-custom-viz.yml).
The workflow never edits package.json. The only thing bumped in the version-bump PR is the version field. The npm dist-tag is derived from the version's pre-release label.
Version → npm dist-tag
Only two version shapes are accepted:
Version in package.json |
npm dist-tag |
|---|---|
X.Y.Z |
latest |
X.Y.Z-canary.N |
canary |
The release script rejects anything else.
Convention:
- On
master, use-canary.Nso the release does not land underlatest. - On
release-x.NN.x, use a cleanX.Y.Z— it lands underlatest.
How to cut a release
Bump
versionin package.json and open a PR against the intended source branch (masterfor a canary;release-x.NN.xfor a stable). The easiest way to bump isnpm versionfrom the package directory:cd enterprise/frontend/src/custom-viz # canary → next canary (e.g. 2.0.0-canary.0 → 2.0.0-canary.1) npm version prerelease --preid=canary --no-git-tag-version # canary → stable patch (e.g. 2.0.0-canary.1 → 2.0.0) # or stable → next patch (e.g. 2.0.0 → 2.0.1). Use minor/major as needed. npm version patch --no-git-tag-version # stable → first canary of next patch (e.g. 2.0.0 → 2.0.1-canary.0) npm version prerelease --preid=canary --no-git-tag-version # stable → first canary of next minor/major (e.g. 2.0.0 → 2.1.0-canary.0 / 3.0.0-canary.0) npm version preminor --preid=canary --no-git-tag-version npm version premajor --preid=canary --no-git-tag-versionPrefer
npm versionover editing the field by hand — it keeps the version in one of the two accepted shapes and picks the right component to bump.--no-git-tag-versionstops npm from making a commit or git tag — the release workflow creates the git tag after the version-bump PR lands. The package is bun-managed (nopackage-lock.json), sonpm versiononly editspackage.json.For a stable release, add a section for the new version to CHANGELOG.md in the same PR. The changelog is maintained by hand. Canary releases don't get changelog sections.
In the same PR, make sure
tested-sdk-version-rangein manifest.clj includes the new version —manifest-testfails when it doesn't. Plugins built with SDK versions outside that range get a soft warning in Metabase. Any npm semver range syntax works (e.g.2.0,2.0 - 2.1,>=2.0.0 <3.0.0); keep the range to versions that were actually tested.(Optional) Preview what the workflow will resolve, from the repo root:
./bin/custom-viz/resolve-release.sh # version=... # npm_tag=... # git_tag=...Land the PR through normal review + CI.
Go to the Release Custom Viz Package workflow and click Run workflow.
Fill in the inputs:
| Input | Description | Default |
|---|---|---|
| branch | Branch to release from. Must be master or release-x.NN.x (e.g. release-x.60.x) |
master |
| dry_run | Skip npm publish and git push --tags. Useful for validating the plan end-to-end. |
false |
- Click Run workflow.
What the workflow does
determine-release— runsbin/custom-viz/resolve-release.shto readversionfrompackage.json, derive the npm dist-tag from its pre-release label, and compute the git tagcustom-viz-v<version>.preflight— fails if the git tag already exists or if the version is already published on npm, then runsbun run check:package-versions.build-and-publish— installs, builds, and runsnpm publish --tag <npm_tag>(skipped whendry_run=true).tag-git— creates and pushes the annotated git tagcustom-viz-v<version>(push skipped whendry_run=true).
npm provenance and required package.json fields
Publishing uses npm trusted publishing from GitHub Actions, which automatically signs and publishes a Sigstore provenance attestation tying the tarball to this repo and the workflow run that built it.
Local publishing (manual)
If you need to publish manually (e.g. for a one-off local build), you need an npm access token with publish access to the @metabase scope. Either set the NPM_TOKEN environment variable or run npm login before publishing.
bun run release