Install the Private Beta

Maelstrom beta packages are private and hosted on GitHub Packages. Your GitHub account needs read access to the Maelstrom repository before your token can download them.

Before you start

• Accept your invitation to the Maelstrom repository.
• Ask the Maelstrom team for the release tag, version, or preview PR you should test.

Configure GitHub Packages

1. Create a classic personal access token. Open GitHub token settings, select read:packages, and generate the token. GitHub Packages does not support fine-grained personal access tokens for npm authentication.

   If the Maelstrom organization uses SAML SSO, authorize the token for the organization after creating it.

2. Expose the token to your package manager. Set it in your current shell. Store the value in your password manager or CI secret store, not in the project.

   printf 'GitHub Packages token: '
   read -rs GH_PACKAGES_TOKEN
   printf '\n'
   export GH_PACKAGES_TOKEN

3. Route Maelstrom packages to GitHub. Add the package-manager configuration beside your package.json. You can commit it because it contains an environment variable reference, not the token.

   npm, Bun, pnpm

   .npmrc

   @maelstrom-co:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${GH_PACKAGES_TOKEN}

   Yarn

   .yarnrc.yml

   npmScopes:
     maelstrom-co:
       npmRegistryServer: https://npm.pkg.github.com
       npmAlwaysAuth: true
       npmAuthToken: ${GH_PACKAGES_TOKEN}

4. Install the requested package. Use the alpha tag for the current beta release, or replace it with the exact version supplied by the Maelstrom team.

   npm

   npm install @maelstrom-co/react@alpha

   bun

   bun add @maelstrom-co/react@alpha

   pnpm

   pnpm add @maelstrom-co/react@alpha

   Yarn

   yarn add @maelstrom-co/react@alpha

Install a PR preview

The preview bot posts an exact version and a pr-<number> tag on labeled pull requests. Prefer the exact version when reporting bugs so every tester runs the same build. Use the PR tag when you want subsequent installs to follow the newest preview from that pull request.

npm

npm install @maelstrom-co/react@0.0.0-pr.123.456.1
npm install @maelstrom-co/react@pr-123

bun

bun add @maelstrom-co/react@0.0.0-pr.123.456.1
bun add @maelstrom-co/react@pr-123

pnpm

pnpm add @maelstrom-co/react@0.0.0-pr.123.456.1
pnpm add @maelstrom-co/react@pr-123

Yarn

yarn add @maelstrom-co/react@0.0.0-pr.123.456.1
yarn add @maelstrom-co/react@pr-123

Configure GitHub Actions

Add the classic token as a repository secret named GH_PACKAGES_TOKEN. Configure npm before installing dependencies:

.github/workflows/ci.yml

permissions:
  contents: read

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-node@v7
    with:
      node-version: 24
      registry-url: https://npm.pkg.github.com
      scope: '@maelstrom-co'
  - run: npm ci
    env:
      NODE_AUTH_TOKEN: ${{ secrets.GH_PACKAGES_TOKEN }}

Caution

Do not commit the token, paste it into .npmrc, or expose it through a NEXT_PUBLIC_, VITE_, or other client-side environment variable.

Verify registry access

Ask the configured registry for the current beta version:

npm view @maelstrom-co/react@alpha version

An E401 response means the token is missing or invalid. An E404 response usually means the GitHub account that owns the token cannot access the repository, the SSO authorization is missing, or the requested version does not exist.

Verify the installed version

Check the version installed in your local project:

npm list @maelstrom-co/react --depth=0

Remove access

Delete the token from GitHub token settings when the beta ends. Remove the corresponding CI secret from every repository where you stored it.

Next steps

• Quick Start - build the smallest working Maelstrom chart
• Installation - choose packages and review peer dependencies