Authentication

@middag-io/react is available from two registries. Choose based on your needs.

npm public registry (recommended)

No authentication needed. Install directly:

npm install @middag-io/react

You get the compiled library (dist-lib/) and TypeScript type definitions. This is sufficient for building plugins.

Imports, type-checking, extends, and compilation all work normally with the npm public package. Your bundler (Vite, webpack) consumes the ESM bundle and produces your plugin's final build.

GitHub Packages (with source)

Includes the full TypeScript source alongside the compiled output. Useful for:

• Navigating into library internals in your IDE
• Reading implementation details of shells, layouts, and blocks
• Contributing to the library

Access requirement

GitHub Packages requires membership in the middag-io organization. A token with read:packages scope alone is not sufficient — you must have read access to the repository.

Setup

1. Create a GitHub Personal Access Token at github.com/settings/tokens
2. Select the read:packages scope (that's all you need)
3. Add to your global ~/.npmrc:

echo "@middag-io:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_TOKEN" >> ~/.npmrc

4. Install normally:

npm install @middag-io/react

Token security

Always store your token in ~/.npmrc (global), never in a project-local .npmrc file. Project files can accidentally be committed to git, exposing your token.

Verify access

npm whoami --registry=https://npm.pkg.github.com

If this prints your GitHub username, you're configured correctly.

The wizard handles this

npx create-middag-ui asks which registry you want during setup and configures everything automatically. You only need this page if you're setting up manually or troubleshooting.

CI / Docker builds

For CI pipelines and Docker builds where the wizard doesn't run:

npm public (simplest)

No configuration needed. npm install works out of the box.

GitHub Packages in CI

Set NODE_AUTH_TOKEN as an environment variable:

# GitHub Actions
- uses: actions/setup-node@v5
  with:
    registry-url: https://npm.pkg.github.com
- run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Dockerfile
ARG GITHUB_TOKEN
RUN echo "@middag-io:registry=https://npm.pkg.github.com" >> ~/.npmrc && \
    echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> ~/.npmrc && \
    npm ci && \
    rm ~/.npmrc

Troubleshooting

401 Unauthorized during npm install

Your token is invalid or missing the read:packages scope.

1. Check your token: npm whoami --registry=https://npm.pkg.github.com
2. If it fails, create a new token at github.com/settings/tokens with read:packages
3. Update ~/.npmrc with the new token

404 Not Found for @middag-io/react

The registry scope line is missing or wrong.

1. Check: grep middag ~/.npmrc
2. Should show: @middag-io:registry=https://npm.pkg.github.com
3. If missing, add it: echo "@middag-io:registry=https://npm.pkg.github.com" >> ~/.npmrc

Switching between registries

To switch from GitHub Packages to npm public:

# Remove the scope redirect from ~/.npmrc
sed -i '' '/@middag-io:registry/d' ~/.npmrc
# Reinstall
npm install @middag-io/react

To switch from npm public to GitHub Packages, follow the Setup steps above.