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.

$3

To start Storybook in development mode:
``bash
npm run storybook
`

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

$3

To build a static version of Storybook for deployment:
`bash
npm run build-storybook
`

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

$3

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.

$3

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.

$3

To generate the inventory report:
`bash
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.

$3

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

`bash
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

$3

To generate a sample report using Storybook files in this repository:
`bash
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

$3

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

$3

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

$3

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 ` example (npm publish --tag "alpha")

Testing

Jest tests can be run using:
`npm run test``