@civicactions/cmsds-open-data-components

cmsds-open-data-components

This repo acts as an upstream common react library for CMS Open Data sites. This library is powered by Parcel.

Local Development

For local development, we recommend using npm workspaces. Once you have a workspace directory, install this library inside your workspace along any Open Data downstream sites you wish to work on.

In the root folder for this project, run npm run watch to build local code. Ensure the upstream is using the same version number located in package.json of this repo. Start the upstream site locally as well, and it should load local code from this repo as the dependency. Parcel also provides hot rebuilding while watch is running.

Storybook

This project includes Storybook for component development and documentation.

Running Storybook

To start Storybook in development mode:

npm run storybook

This will start the Storybook development server, typically on http://localhost:6006.

Building Storybook

To build a static version of Storybook for deployment:

npm run build-storybook

The built Storybook will be output to the storybook-static directory.

Writing Stories

Stories should be placed alongside components using the naming convention:

• ComponentName.stories.jsx or ComponentName.stories.tsx

Stories use the CSF3 (Component Story Format 3) format. See existing stories in the src/components/ directory for examples.

Storybook Limitations

Storybook integration is ongoing for this project. Some components and page templates may not yet have stories, and certain icons or styles from the CMS.gov design system might not display as intended in Storybook.

Component Inventory

This project includes an automated script that generates a comprehensive inventory of all components, templates, services, hooks, contexts, utilities, and types.

Generating the Inventory

To generate the inventory report:

npm run generate:inventory

This creates COMPONENTS_INVENTORY.md in the root directory with:

• Complete list of all library items
• Public export status
• Storybook story coverage
• Unit test coverage
• Quality metrics and statistics

The inventory is automatically updated on every commit via a pre-commit hook.

For more details, see the Scripts Documentation.

Component Usage Report

This project includes a script that can be run in projects that use cmsds-open-data-components as a dependency to analyze component usage.

Running in Dependent Projects

From a project that has @civicactions/cmsds-open-data-components as a dependency:

npx generate-usage-report

This generates COMPONENT_USAGE_REPORT.md showing:

• Which components from the library are being used
• Where each component is imported in the project
• Summary statistics and category breakdown
• GitHub links to component source code

Generating Sample Report (Library Development)

To generate a sample report using Storybook files in this repository:

npm run generate:usage-report

This creates SAMPLE_COMPONENT_USAGE_REPORT.md demonstrating the report format.

For more details, see the Scripts Documentation.

Publishing new versions

Clear out caches and previous build

Before running a build, it is recommended to clear out the old build and cache files to avoid publishing a stale build.

Run rm -rf dist/ to delete the previous build
Run rm -rf .parcel-cache/ to clear out the parcel build caches

Create a new release

Run npm run build to create a production version of the library before publishing to npm.
Run npm publish to publish to npm

Create an alpha/testing release

When creating an alpha release or any other release intended for testing purposes, add a tag to the publish command. This will prevent the testing release from showing up as the latest release in NPM.

After running npm run build,
Run npm publish --tag <tag name> example (npm publish --tag "alpha")

Testing

Jest tests can be run using: npm run test