Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

5.4 KB
Raw Blame

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.N so the release does not land under latest.
  • On release-x.NN.x, use a clean X.Y.Z — it lands under latest.

How to cut a release

  1. Bump version in package.json and open a PR against the intended source branch (master for a canary; release-x.NN.x for a stable). The easiest way to bump is npm version from 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-version
    

    Prefer npm version over 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-version stops 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 (no package-lock.json), so npm version only edits package.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-range in manifest.clj includes the new version — manifest-test fails 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.

  2. (Optional) Preview what the workflow will resolve, from the repo root:

    ./bin/custom-viz/resolve-release.sh
    # version=...
    # npm_tag=...
    # git_tag=...
    
  3. Land the PR through normal review + CI.

  4. Go to the Release Custom Viz Package workflow and click Run workflow.

  5. 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
  1. Click Run workflow.

What the workflow does

  1. determine-release — runs bin/custom-viz/resolve-release.sh to read version from package.json, derive the npm dist-tag from its pre-release label, and compute the git tag custom-viz-v<version>.
  2. preflight — fails if the git tag already exists or if the version is already published on npm, then runs bun run check:package-versions.
  3. build-and-publish — installs, builds, and runs npm publish --tag <npm_tag> (skipped when dry_run=true).
  4. tag-git — creates and pushes the annotated git tag custom-viz-v<version> (push skipped when dry_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