@department-of-veterans-affairs/component-library

VA.gov component library. Includes React and web components.

Usage no npm install needed!

<script type="module">
  import departmentOfVeteransAffairsComponentLibrary from 'https://cdn.skypack.dev/@department-of-veterans-affairs/component-library';
</script>

README

This module contains reusable React components for the VA.gov design system published as an NPM package for use in the vets-website frontend codebase.

Quick start

npm install @department-of-veterans-affairs/component-library

import COMPONENTNAME from '@department-of-veterans-affairs/component-library/COMPONENTNAME'

See design system or Storybook for a full list of available components.

Contributing

The issue tracker is disabled on this repo. To request a new component or a feature enhancement, please open an issue here

Running Storybook locally

From the project root, run the following commands:

  1. yarn install
  2. yarn storybook

Web Components

The Design System team is working on replacing the React components in this library with Web Component versions. This isn't just a React replacement however - part of the goal is to have true components that can be used outside of React in plain HTML pages.

Usage

To use these Web Components in your own project, follow the installation steps. This will allow the components to be used in JSX or HTML.

Development

For now these Web Components live on the web-components branch. In order to add a new component or make changes to an existing one, you must:

  1. Create a new branch off of web-components
  2. Have the PR be based off of web-components (not master - see image below)
  3. Once the PR is merged, create a Github Release with web-components as the base, where the version is wc-vX.Y.Z. with X.Y.Z being the semantic version.

Making a PR

PR into web-components branch

Making a release

Include a list of changes when you create a new release. Each bullet point should be one or two clear sentences. We have been using Keep a changelog informally and have had good success with it.

release off of web-components branch

Publishing Module to NPM

After you've tested and previewed your changes locally it's time to publish a new version of the package to NPM.

Prerequisite: you must be registered with NPM, be a member of the "department-of-veterans-affairs" organization, and have the appropriate organization role to publish an update to the module. Verify that you are logged in correctly by running npm whoami. If you are unable to publish an update, confirm you are a member of the "department-of-veterans-affairs" organization by going to your Profile page on npmjs.com.

1. Submit your PR

Submit a PR that includes all of your code changes. This should include the bump in versions you need, which you can change directly in the package.json files for the modules that are changing. Modules like component-library depend on formation via a peer dependency, so you may need to update that as well. We try to keep the peer dependency loose and only update it for breaking changes.

Please add a clear list of changes to your PR description. We have been using Keep a changelog informally and have had good success with it.

You'll need to choose what type of version update to make:

  • patch - for bug fixes and minor changes
  • minor - for new features that don't break current features or require changes in consuming applications
  • major - for backwards breaking changes

If you are unsure of what to pick, do a major version update on modules that are changing.

2. Merge your PR to master

Once your changes are approved, squash merge them to master. Also, if your change is a breaking change, please prefix your commit message with BREAKING CHANGE:. Also keep in mind that your commit messages will be in a changelog that people use to figure out what has changed between releases, so make sure it accurately describes your changes.

3. Build and publish

  • Checkout the master branch
  • Run yarn build
  • Run npm publish

4. Update consuming apps

The last step is to update the package.json files of consuming apps to use the latest version of @department-of-veterans-affairs/formation (or component-library). For example, if you are working with the vets-website project, open the vets-website's package.json to update the version number of the @department-of-veterans-affairs/formation entry listed in the dependencies section. The version number should match what you just published to NPM.