primer-library

Primer Library is a collection of themeable components for building web applications.

Prerequisites

This project requires Node.js v24.13.0 or higher.

This project requires sass v1.97.3 or higher.

Installation

To install the project, run the following command:

npm install @reading-room/primer-library

Usage

See component README.md files for detailed usage instructions.

Development

To start the development server, run the following command:

npm run dev

Build

Run after making any changed in the primer library:

npm run build

Storybook

Note: It's not recommended to run Storybook directly from primer-library for development. Instead, run Storybook from a Primer project that consumes primer-library to better simulate real-world usage.

To view the components in Storybook, run the following command:

npm run storybook

To build the Storybook static files, run the following command:

npm run build-storybook

To build the Storybook static files and then deploy the Storybook to Chromatic, run the following command:

npm run chromatic

You can access the Storybook at: https://677d0a81cd25aebe5cd41b42-tchggbvfey.chromatic.com/

Local development across primer-library and primer-utils

When developing components and utilities in primer-library and primer-utils concurrently, sometimes it's necessary to symlink the primer-utils packages to primer-library.

This can be done by creating a link.config.json file in the root of the primer-library project with the following content:

{
  "packages": ["../primer-utils"]
}

Where ../primer-utils is the path (either relative or absolute) to the primer-utils package.

Note: It's not recommended to commit this file to source control since this is for local development with local paths.

Then run the following command to create the symlinks:

npx link

This will create symlinks to the primer-utils package on your local machine, and will handle them as though they were installed in node_modules.

Updating primer-library

Ideally all dependencies should be kept up to date to take advantage of new features and security updates.

Before running npm update, you should run the storybook update script to ensure that the Storybook dependencies are updated correctly and migrated if necessary.

npx storybook@latest upgrade

After running the Storybook upgrade, you can run the following command to update all dependencies to the latest minor version.

npx npm-check-updates --target minor -u

For a major primer-library version release, you should update all dependencies to the latest major version.

npx npm-check-updates -u

This will likely require manual intervention to resolve breaking changes introduced by the updates.

Ensure upgrades are performed across Primer, primer-library and primer-utils at the same time to ensure compatibility.