Installation

Sulmu UI is published as @beyul/sulmu-ui, a private package on GitHub Packages. Installing it takes two things that a public npm package does not need: telling the package manager where the @beyul scope lives, and a token that is allowed to read it.

Requirements

• React and React DOM 18 or newer (peer dependencies).
• A bundler that can import CSS files and ES modules. The package is ESM only.
• A GitHub token with the read:packages scope, from an account that can see the beyul/sulmu-ui repository.

@ark-ui/react and @tanstack/react-table are regular dependencies of the package and are installed with it. The app does not need Panda CSS or any CSS-in-JS runtime.

1. Get a token

1. If you use the GitHub CLI, add the scope to your existing login and export the token:

   gh auth refresh --scopes read:packages

   export NPM_AUTH_TOKEN=$(gh auth token)

2. Otherwise, create a personal access token (classic) on GitHub with the read:packages scope and export it as NPM_AUTH_TOKEN.

3. CI and Docker builds need the same variable, set from a secret.

Never commit the token. The configuration below reads it from the environment.

2. Point the @beyul scope at GitHub Packages

npm

Add this to .npmrc in the app:

@beyul:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_AUTH_TOKEN}

pnpm

pnpm reads .npmrc too. Add this to .npmrc in the app:

@beyul:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_AUTH_TOKEN}

Yarn 3

Yarn 2 and later ignore .npmrc. Add this to .yarnrc.yml:

npmScopes:
  beyul:
    npmRegistryServer: 'https://npm.pkg.github.com'
    npmAlwaysAuth: true
    npmAuthToken: '${NPM_AUTH_TOKEN:-}'

The :- makes the variable optional, so commands that do not touch the registry still run without a token. This is the configuration the Tourism Suite frontend uses.

3. Install the package

npm

npm install @beyul/sulmu-ui

pnpm

pnpm add @beyul/sulmu-ui

Yarn 3

yarn add @beyul/sulmu-ui

In a monorepo, add it to each app that imports it. The Tourism Suite frontend lists it in apps/shell and in each micro frontend that uses it.

What the package contains

Import	What it is
@beyul/sulmu-ui	The components, the icons and their types.
@beyul/sulmu-ui/styles.css	The precompiled stylesheet. Import it once.
@beyul/sulmu-ui/preset	The Panda CSS preset (sulmuPreset), for apps that use Panda themselves.
@beyul/sulmu-ui/tokens/*	The token JSON files, e.g. tokens/color.semantic.json.
@beyul/sulmu-ui/icons/*	The icon SVG files, e.g. icons/edit-2.svg.
@beyul/sulmu-ui/illustrations/*	The error page artwork, e.g. illustrations/error-404.svg.

Troubleshooting

• 401 or 403 from npm.pkg.github.com: the token is missing, has expired, or lacks read:packages. Check echo $NPM_AUTH_TOKEN in the same shell.
• 404 for @beyul/sulmu-ui: the scope is not mapped to GitHub Packages (the request went to the public npm registry), or the token’s account cannot see the repository.
• Jest cannot find the module: the package is ESM only. See Jest setup.

Next: set up the styles, font and dark mode.