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 i
to install dependencies. -
Running the Playground: Run
npm start
- it will start a dev server which can be viewed athttp://localhost:3000
. -
Running Tests:: Run
npm t
to execute the tests. To run watch mode on tests,npm run test:watch
- this is helpful during development.
The 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
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 containpackage-lock.json
files. If you accidentally install a dependency from within a package folder, please ensure you 1) remove thepackage-lock.json
file, and 2) re-runnpm i
from the project root to ensure the rootpackage-lock.json
is 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:
-
GITHUB_API_TOKEN
- Used in
UsageDetails
to fetchpackage.json
s from each of our projects
- Used in
-
SOURCEGRAPH_URL
- Used in
UsageDetails
to build links out to our SourceGraph instance
- Used in
Publishing is handled through the changesets
library. Publishing is done in CI if changes are found. For more information on how to work with changesets, see this document.
Run the following command and follow the prompt:
npx changeset
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 version
and publish
commands as appropriate.
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.
To use this script, you'll need to setup some config. This script uses Octokit to interface with the GitHub API easily.
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.
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.