All YaleSites projects have access to components in the YaleSites component library. Themes may choose which variations of components to implement, and options are available.
Prerequisites
Each environment that needs to pull @yalesites-org packages from GitHub needs to be authenticated using a "Personal Access Token". This only needs to be done once per-environment.
-
Go to
https://github.com/settings/tokens/new- In the "Note" field add something like "YaleSites GitHub Packages"
- Choose an expiration value
- Check the box for "write:packages" (this will automatically check all of the "repo" boxes as well)
- Click "Generate token"
-
On your local machine, create an environment variable. This process varies depending on the shell and operating system you use. It will be something similar to this though:
export KEY=value.- The
keyfor YaleSites projects needs to beYALESITES_BUILD_TOKEN - The
valueis the token you created above
- The
-
Done!
-
Here's a stack overflow post showing how to set persistent environment variables for various shells
If you want to work directly on the component library locally, you can clone this repo and install the dependencies as described below.
- Clone the repository
git clone [email protected]:yalesites-org/component-library-twig.git - Change directories into the repo
cd component-library-twig - Verify you're using the correct version of node
nvm use - Install dependencies
npm install - Run the develop script
npm run develop - Make your changes and commit them!
There must be a .npmrc file in the project root that tells npm to get @yalesites-org packages from GitHub rather than npm.
- Create a
.npmrcfile in your project root (or modify an existing one) and add the following:
@yalesites-org:registry=https://npm.pkg.github.comThen you can install the package like any other npm dependency.
npm install @yalesites-org/component-library-twigAny time something is pushed to the main branch on GitHub, a GitHub Action is run to determine whether a new release is needed (via semantic-release.)
This is an entirely automated process, so whether changes are pushed directly to main or if they go through the preferred PR workflow the release process will be run. Merges into main should be performed using a merge commit.
You can view the latest version of the component library at any time by visiting the Deployed Storybook. All new commits to the main branch trigger a rebuild and deploy of the component library, so it will always be up-to-date with the latest released code.
The develop branch also has an auto-deployed component library. This will contain all of the work that will go out in the next release. It is deployed to netlify.
PRs also have auto-deployed component libraries, which allow reviewers to load the latest state of a PR at any given time without having to fiddle with local tooling. Each PR will have a link posted to the PR comments by the "netlify bot" when the link is ready. See screenshot below.
This project uses Percy's StoryBook integration to visually test and verify components during Pull Requests in GitHub.
View the status of any build here: https://percy.io/95144ff9/component-library-twig
NOTE: Percy is temporarily auto-approving all branches for now. (Original was only auto-approving main) This will be reverted once we have a better handle on how to manage the visreg tests.
Visual regression tests are automatically run on Percy any time a PR is changed from "Draft" state to "Ready for Review". So there are a few things to keep in mind when creating PRs.
- When you initially create a PR that needs visreg tests, click the "Create draft PR" button instead of the "Create Pull Request" button.
- Then, when the PR is ready for review, you can click the "Ready for Review" button at the bottom of the page. This will trigger the visual regression tests to be run.
- If you've already created a PR and need forgot to create a draft first, or you need to re-run the visual regression tests after changes were made, you can click the "Convert to draft" link at the bottom of the page.
- Then click the "Ready for Review" button mentioned above to trigger visual regression tests.
Official Docs: https://docs.percy.io/docs/storybook
By default all new Stories are tested, but stories can be excluded if a test does not provide value in isolation.
In the project root, there is a .percyrc file that can be used to modify Percy's configuration, including custom css, and which Stories to skip when testing.
For example, we use the following percy-specific css to hide images from screenshots (since we use a random image service, which would otherwise cause regressions on every test that includes an image.)
img {
visibility: hidden;
}Since Percy bills by the screenshot, it's best to only test the Stories that provide value when tested visually. Some reasons stories should be excluded include:
- Anything that is simply a representation of a base or "primitive" token. These will be represented in the larger components that implement them, so in isolation they don't provide significant value to visual testing.
- Dynamic stories that automatically update when new tokens are added upstream. e.g. The colors story. Since colors aren't really a concern at this level (they're defined in Figma by a designer) we don't really need to test them in isolation here.
- "Playground" types of stories. e.g. The site "Header" story. Since there are a number of choices, or props, that can affect how the site header looks, we have a "playground" story that allows a visitor to toggle all of the controls to see what can be generated with the design system options. What SHOULD be tested is one or more examples of the component with various decisions selected. That is why we have a "Header Examples" story that demonstrates the allowed color combinations.
To exclude stories, add an item to the exclude array in a regex format. Some examples of what we currently exclude are:
storybook:
exclude:
- 'Tokens/Breakpoints: Breakpoints' # This specific story (must match exactly)
- 'Tokens/Effects: [a-zA-Z]+' # Any story in the `Tokens/Effects` section, since they are dynamically generated.