Gamut

The component library & design system for Codecademy. ✨

---

This repository is a monorepo that we manage using NX. That means that we publish several packages to npm from the same codebase, including:

Gamut Kit

We provide a single package to manage the versions of a few core dependencies: gamut, gamut-icons, gamut-illustrations, gamut-patterns, gamut-styles. Since these packages are highly intertwined we suggest only installing @codecademy/gamut-kit when your app needs all of these.

gamut-kit: Include in your application instead of the individual packages to simplify version management.

• 

1. Run yarn add @codecademy/gamut-kit
2. Add each of the managed packages to your peer dependencies (this is required for enabling intellisense for these packages and does not have any effect on version resolution)

{
  "peerDependencies": {
    "@codecademy/gamut": "*",
    "@codecademy/gamut-icons": "*",
    "@codecademy/gamut-patterns": "*",
    "@codecademy/gamut-illustrations": "*",
    "@codecademy/gamut-styles": "*",
    "@codecademy/gamut-tests": "*",
    "@codecademy/variance": "*"
  }
}

Individual Packages

gamut: Our React UI component library

• 

gamut-styles: Utility styles for Gamut components and codecademy apps

• 

gamut-icons: SVG Icons for Gamut components and codecademy apps

• 

variance: TypeScript CSS in JS utility library

• 

styleguide: Styleguide Documentation & storybook development sandbox

Local development

1. Run yarn in the root directory
2. Run yarn build to build all of the packages (certain packages like gamut-icons need to be built to function in storybook).

Running the storybook styleguide

1. Run yarn nx storybook styleguide to start the storybook server
2. Add new stories to packages/styleguide/src
3. Stories are written using storybook's Component Story Format and MDX. Check out our comprehensive guide on writing stories here.

Publishing Modules

This repository uses NX Release with Version Plans for package versioning and publishing.

Creating a Version Plan

1. Create a version plan for your changes using yarn nx release plan. This interactive command will prompt you to:
   • Select which packages are affected by your changes
   • Choose the type of version bump (major, minor, or patch)
   • Provide a description of the changes for the changelog
2. The version plan will be saved as a markdown file in .nx/version-plans/
3. Commit this version plan file along with your code changes
4. The version plan will be applied when your PR is merged to main

Version Plan Format

Version plan files are markdown files with YAML front matter. Here's an example:

---
gamut: minor
gamut-styles: patch
---

Add new Button variant and fix spacing issues

- Added a new "ghost" variant to the Button component
- Fixed margin spacing in the Card component

Publishing Process

1. Make your changes in a feature branch, and get another engineer to review your code
2. Create and commit a version plan for the changes (yarn nx release plan)
3. CI checks that a version plan is present for the PR
4. After reviews and checks pass, you can merge your branch into main
5. Once your branch is merged into main, it will be published automatically by GitHub Actions using NX Release.
   • NX Release will apply all version plans found in .nx/version-plans/
   • It will bump package versions according to the plans
   • It will generate changelog entries from the version plan descriptions
   • It will publish the packages to npm
   • It will create git tags and GitHub releases
6. You can find the new version number on npmjs.com/package/, or find it in that package's package.json on the main branch

Publishing an alpha version of a module

Every PR that changes files in a package publishes alpha releases that you can use to test your changes across applications.

NOTE: in case an alpha build is not published upon opening of the PR or Draft PR, re-run the build-test check and that will re-run the alpha build publishing flows

1. Create a PR or Draft PR.
   • This will kickoff a Github Action workflow which will publish an alpha build. (This will appear in Github as the "Deploy")
2. After the alpha build is published, the codecademydev bot should comment on your PR with the names of the published alpha packages.
   
3. Install this version of the package in your application you wish to test your changes on.

Working with pre-published changes

NOTE: Due to the inconsistencies of symlinks in a monorepo, instead of using yarn link, we recommend using the npm-link-better package with the --copy flag to copy packages into your local repo's node_modules directory.

Initial Setup:

1. Ensure you have npm-link-better installed: npm install -g npm-link-better
2. Ensure you've built the entire gamut repo since you last synced: yarn build

Instructions:

For each of your local gamut packages (e.g. gamut), you'll need to do 2 things to get it working in your project:

1. Make sure your package changes have been built into the gamut/packages/[package]/dist folder.

   • yarn build
     or
     yarn build:watch (not all packages support this yet)

2. Copy that built /dist folder to your project's node_modules/@codecademy/[package] folder.

   cd myProjectRepo
   npm-link-better --copy --watch path/to/gamut/packages/[package]

   NOTE: The --watch flag will automatically copy your package into node_modules everytime it is built.

Example Workflow

Let's say we are making changes to the gamut package, and our app that uses the gamut package uses yarn start to build, serve, and watch our app for changes.

Let's also assume these two repos are sibling directories inside of a folder called repos

repos
  |- gamut
  |- my-app

We would run the following commands in 3 separate shells

# Shell 1: Auto-build Gamut changes
cd repos/gamut/packages/gamut
yarn build:watch

# Shell 2: Auto-copy built Gamut changes to my-app.
cd repos/my-app
npm-link-better --copy --watch ../gamut/packages/gamut

# Shell 3: Auto-update app when anything changes.
cd repos/my-app
yarn start

This would allow us to make a change in our gamut package, and see that change automatically reflected in our local app in the browser.

Troubleshooting

• If you see compilation issues in your project's dev server after running npm-link-better, you may have to restart your app's dev server.

• If you are seeing compilation issues in a gamut package, you may need to rebuild the whole repository via

  yarn build

Instructions for using `yarn link` instead (not recommended)

For quicker development cycles, it's possible to run a pre-published version of Gamut in another project. We do that using symlinks (the following instructions assume you have set up and built Gamut):

1. cd /path/to/gamut/packages/gamut
2. yarn link
3. cd path/to/other/repo
4. yarn link @codecademy/gamut
5. yarn install

If your other project uses React, you must link that copy of React in Gamut:

1. cd path/to/other/repo
2. cd node_modules/react
3. yarn link
4. cd /path/to/gamut/packages/gamut
5. yarn link react
6. yarn build

See the docs for more information for why you have to do this.

Adding a New Package

1. Use NX generators to create the new package. For example:

   yarn nx g @nx/react:library <package-name> --buildable --publishable

   • Make sure to set the publishConfig field to { "access": "public" } in the generated package.json to let your published package be public by default
2. Customize the generated source code as needed for your package
3. Run yarn install from the repository root
4. Send a feat PR adding that package with a version plan (using yarn nx release plan)
5. Once merged, message out in our #frontend Slack channel to other Gamut developers to re-run yarn install after they merge from main

Notes:

If your package will be used in other packages in the monorepo, you may need to set up aliases in jest and storybook so that they can be run without building your package first. You can find these aliases in jest.config.js and the styleguide storybook config.

NX

This monorepo uses NX to cache previous builds locally and in CI.

The config for NX is located at /nx.json, along with project.json files for each package.

For new packages, please use an NX generator plugin to create your initial package, this will ensure that all of the configuration for linting & testing is set up correctly.

Breaking Changes

Breaking changes are indicated in version plans by specifying a major version bump. When creating a version plan with yarn nx release plan, select "major" as the bump type for packages that introduce breaking changes.

Examples of version plans with breaking changes:

---
gamut: major
---

Breaking: Removed deprecated Button variants

This removes the previously deprecated "primary-blue" and "secondary-red" variants.

You should create a major version bump if your changes introduce any incompatibilities with previous versions of the module. This will indicate to package consumers that they need to refactor their usage of the module to upgrade.

Breaking Changes Release Process

Because Gamut is a separate repository from its consumers, it can be tricky to coordinate technically breaking changes. If your changes will require changes in any downstream repositories:

1. Create a PR in Gamut to create alpha package versions
2. Create PRs in the repositories using those alpha package versions
3. Update each downstream PR description to link to the Gamut PR, and vice versa
4. Once all PRs have been approved, merge your Gamut PR first
5. Update your repository PRs to use the new (non-alpha) package versions once published
6. Merge your repository PRs

This process minimizes the likelihood of accidental breaking changes in Gamut negatively affecting development on our other repositories.

Changelog Descriptions

Changelog content is driven by the description in version plan files (in .nx/version-plans/), not the PR title or PR description.

Publishing Storybook

Storybook is built and published automatically when there are merges into the main branch.