CatalystInstallation
Install, configure, and start building with Catalyst primitives.
Prerequisites
- React 18.0+
- TypeScript 5.0+ (recommended)
- Tailwind CSS 3.0+
- Package manager: npm, yarn, or pnpm
Registry Configuration
Catalyst packages are hosted on Azure DevOps. Configure authentication for your operating system.
- Add a
.npmrcfile in your project root (same directory aspackage.json):
registry=https://pkgs.dev.azure.com/pmiorg/_packaging/DSM/npm/registry/
always-auth=true- Authenticate with
vsts-npm-auth:
vsts-npm-auth -config .npmrcYou only need to re-run this when npm returns a 401 Unauthorized error.
If vsts-npm-auth isn't working, follow the macOS & Linux instructions below to authenticate with a Personal Access Token instead.
Install Primitives
Catalyst primitives ship as individual packages under @pmi/catalyst-[name]. Install only what you need.
# Individual primitives
npm i @pmi/catalyst-button
npm i @pmi/catalyst-card
npm i @pmi/catalyst-switch
# Multiple at once
npm i @pmi/catalyst-button @pmi/catalyst-card @pmi/catalyst-inputNew to Catalyst primitives? Follow the Your First Primitive guide for a complete step-by-step walkthrough — from install to a fully styled, accessible component.
Verify Your Setup
Run your package manager to confirm authentication is working:
npm installNever commit .npmrc files containing authentication tokens to version control. Add them to your .gitignore.
Tailwind configuration
Make sure your app's Tailwind config consumes Tailwind presets exported by the Catalyst packages you install. There is no single @pmi/catalyst-tailwind package — primitive packages are published individually (for example @pmi/catalyst-theme, @pmi/catalyst-accordion) and some of them export Tailwind presets you can compose.
Each Catalyst primitive has its own documentation page describing whether it exports a Tailwind preset and how to configure it.
tailwindThemePreset from @pmi/catalyst-theme must be included in your Tailwind config's presets array. It provides the core theme configuration — design tokens, colour palette, typography, and spacing — that all other Catalyst primitives depend on. Without it, primitives will not render with the correct visual styles.
- Install the primitive packages that include the presets you need:
# @pmi/catalyst-theme is required — install other packages as needed
npm install @pmi/catalyst-theme @pmi/catalyst-accordion --save-dev- Reference and compose the presets in your root
tailwind.config.ts:
import { tailwindThemePreset } from '@pmi/catalyst-theme'; // required
import { tailwindAccordionPreset } from '@pmi/catalyst-accordion';
export default {
content: [
'./src/**/*.{js,ts,jsx,tsx,mdx}',
'./packages/**/src/**/*.{js,ts,jsx,tsx,mdx}',
],
presets: [
tailwindThemePreset, // always include this first — core Catalyst theme
tailwindAccordionPreset, // add other primitive presets as needed
],
theme: {
extend: {
// app-level overrides
},
},
};Notes
tailwindThemePresetshould always be listed first in thepresetsarray so that primitive-specific presets can safely extend it.- Common exported preset names include
tailwindPreset,tailwindThemePreset,tailwindWwwSharedPresets, or similar — check the package README orpackage.jsonexports for exact names. - This per-package preset approach keeps ownership of tokens and utilities close to the primitive implementation while letting apps compose shared presets centrally.
- In monorepos, ensure
contentglobs include consuming packages so Tailwind can tree-shake correctly.
Design tokens (CDN link)
Catalyst primitives use CSS custom properties (CSS variables) for theming and visual consistency. These variables are maintained centrally in a single stylesheet hosted on a CDN. You must include this stylesheet in the <head> of every consuming project's HTML — without it, Catalyst primitives will not render correctly as the required CSS variables will be unavailable at runtime.
<!-- Add to the <head> of your HTML -->
<link href="https://cdn.pmi.org/dsm/styles/v1/20240730-190848-9947574e-7a96-4613-b139-dd1336d5eb83.min.css" rel="stylesheet">Troubleshooting
Primitives not rendering correctly
- Confirm Tailwind CSS is properly configured
- Verify that primitive-specific Tailwind presets are imported if required
- Check React and TypeScript version compatibility
Authentication errors
- Windows: Run
vsts-npm-auth -config .npmrcto refresh your token - macOS/Linux: Confirm your PAT is Base64-encoded, has Packaging read & write scopes, and hasn't expired
- Verify
.npmrcexists in both your project directory and~/ - Confirm the registry URL matches
https://pkgs.dev.azure.com/pmiorg/_packaging/DSM/npm/registry/
TypeScript errors
- Update to the latest primitive package version
- Confirm TypeScript 5.0+
- Check import paths are correct