Matchbox

Matchbox is an open source design system and React component library, built for SparkPost's UI.

Welcome to Matchbox Development

Want to start using Matchbox? See:

• Getting Started

Looking for documentation? See:

• Design System Website
• Storybook
• Playroom

Collaborating on Matchbox

Matchbox uses Lerna to manage packages.

First install lerna globally, then run the following commands to get started:

npm i -g lerna
git clone [email protected]:SparkPost/matchbox.git
cd matchbox
npm i
lerna bootstrap

Root Repo Scripts

# Start Scripts
npm run start:storybook   # Runs storybook
npm run start:site        # Runs the design system website
npm run start:playroom    # Runs playroom

# Test Scripts
# Integration tests require storybook to be running first
npm run pretest           # Run before running tests for first time
npm run test:unit         # Runs unit tests
npm run test:e2e:gui      # Runs integration tests
npm run test:e2e:headless # Runs integration tests in headless mode

# Build Scripts
npm run build             # Builds all packages

Releases

Our release process isn't perfect, and requires some manual work.

We use lerna to handle versioning and publishing to NPM. Before publishing, ensure you are logged into SparkPost's NPM account locally via the NPM CLI. Reach out to #UXFE or #design-guild on Slack if you need access.

Publishing Steps

1. Merge all pull requests you wish to release to main.
2. Before publishing for the first time, set up your github auth token in .env. In order to run changelog you'll need to create a personal access token with the public_repo permissions and copy it to a GITHUB_AUTH variable in an .env file.
3. On the main branch, run npm run changelog. This generates a markdown changelog in CHANGELOG.md.
4. Open and edit CHANGELOG.md with correct title and version number of your release.
5. Push these changes to main if you have permissions, or on a new branch.
6. Run lerna version --force-publish. The Lerna CLI will prompt you for version numbers. The force-publish flag will force all packages to be bumped to the same version. See https://github.com/lerna/lerna/tree/master/commands/version.
7. Run lerna publish from-package. The Lerna CLI will prompt you for a one time password from your authenticator. See https://github.com/lerna/lerna/tree/master/commands/publish.

What the commands look like:

npm run changelog
# Open the changelog file and edit
git add CHANGELOG.md
git commit -m "Update CHANGELOG.md"
git push
lerna version --force-publish
lerna publish from-package
# That's it!