HashiCorp React Components
This project is a monorepo containing a library of react components that are shared between multiple HashiCorp web properties. It also includes a component playground that uses swingset to create a space where component authors and contributors can experiment with and quickly iterate on component design and functionality.
- Getting Started: Run
npm ito install dependencies.
- Running the Playground: Run
npm start- it will start a dev server which can be viewed at
- Running Tests:: Run
npm tto execute the tests. To run watch mode on tests,
npm run test:watch- this is helpful during development.
packages directory contains all the individual components. Let's talk about some of the most important files:
index.jsx: primary export of the component itself
index.test.js: tests for the component, run using jest
docs.mdx: documentation for the component, see swingset docs for more details on the format
props.js: information about the component's props, see swingset docs for more details on the format
Adding package dependencies
We use npm workspaces to manage dependencies for all packages. With this in mind, all new dependencies should be added from the project root, using the
--workspace argument. For example, to add the
classnames package to our
button component, you would run:
npm i classnames --workspace=@hashicorp/react-button
Note: with this in mind, package folders, such as
packages/button, should not contain
package-lock.jsonfiles. If you accidentally install a dependency from within a package folder, please ensure you 1) remove the
package-lock.jsonfile, and 2) re-run
npm ifrom the project root to ensure the root
package-lock.jsonis up to date.
A few of the elements in our playground rely on environment variables in order to function correctly. We have a
react-components .env.local stored in 1Password if you'd like to quickly get started. Details on each environment variable:
- Used in
package.jsons from each of our projects
- Used in
- Used in
UsageDetailsto build links out to our SourceGraph instance
- Used in
Adding a changeset
Run the following command and follow the prompt:
To make any adjustments to your changeset, just edit the file!
The release process is handled mostly automatically via the changesets GitHub action. When changeset files get merged to
main, a Pull Request is opened which will, upon merge, release all pending changesets and remove the changeset files. We should not need to publish manually with this flow. See the
changesets/action(https://github.com/changesets/action) repo for more information.
If you want to test your changes before merging, you can add a
release:canary label to your pull request. If any changeset files are found, a release will be created and tagged with
canary. You can then install the canary version elsewhere:
npm install @hashicorp/react-package@canary
Prereleases are also handled through a process integrated into
changesets. The full flow is outlined in this document. To enter a prerelease mode for the
canary tag, we would do something like this:
npx changeset pre enter canary GITHUB_TOKEN=<your token> npx changeset version GITHUB_TOKEN=<your token> npx changeset publish
To continue publishing preleases, use the
npx changeset command like normal and use the
publish commands as appropriate.
Batch Release Notes
Upon publishing new versions of any package(s), corresponding GitHub release(s) should be published as well with information about the changes, migration notes and links to the PR where changes occurred.
When publishing one or two packages, you can manually create the releases in the GitHub interface. However, if you released a big batch of updates that affects many packages in a similar way (think dependency updates), this process for publishing releases can be automated via this helpful script.
First, create a new personal access token (select
repo scope) and add it to your local
.env file or just paste it directly into the script. This is how you'll authenticate to create the GitHub release. Note, you'll also need to Enable SSO on the token since this is a Hashicorp repo
Next, you'll want to head to the script file:
scripts/create-batch-release-notes and add in your release notes body.
const RELEASE_BODY = `Add the release notes here`
This content will be published in the body of all the releases related to the recently published packages, so please ensure it's providing the correct info.
Executing the script
Now you can run the script while passing in the
sha of the publish commit as a command-line argument. (This is the commit that updates all the version numbers. See this example)
When you're ready, navigate to your terminal in the root of this project and run:
node scripts/create-batch-release-notes.js <YOUR_PUBLISH_SHA>
If all goes well, you should now see these releases published in GitHub. If you have issues, check that the access token has SSO-Enabled.