Mayflower
Mayflower is the enterprise design system for the state government of Massachusetts.
- Core Documentation: The official documentation of Mayflower design system, live at mayflower.digital.mass.gov/core
- Experimental component libraries: component libraries created by Massachusetts Digital Service to build sites like Mass.gov, Search.mass.gov, and Massachusetts budget sites.
License
This project is licensed under the is licensed under the GNU General Public License v2.0 - see the LICENSE.txt file for details.
Monorepo Package Management
This monorepo is managed using Rush and PNPM.
Getting Started on Development
To get started, install rush globally by running the following command:
npm install -g @microsoft/rushOnce installed, run rush install. This will install pnpm and each package's dependencies on disk and symlink together all local packages that depend on one another.
To start developing mayflower react:
rush start:react
To start developing mayflower patternlab:
rush start:patternlab
To start developing mayflower site:
cd packages/react && rushx build(build local @massds/mayflower-react)rush start:site
Monorepo Structure
All uses of npm or yarn have been replaced by rushx. rushx uses pnpm run behind the scenes to execute scripts within a package. For the moment, the following are defined as packages for the mayflower monorepo:
- Mayflower Core (located under
packages/core/) - Mayflower Assets (located under
packages/assets/) - Mayflower React (located under
packages/react/) - Mayflower Patternlab (located under
packages/patternlab/) - Mayflower Homepage (located under
packages/site/)// Mayflower monorepo
├── docs ├── packages | ├── core | ├── assets | | ├── scss | | └── static | | ├── fonts | | └── images | ├── patternlab | | └── styleguide | ├── react | └── site *
Each packages' dependencies from npm are installed using Rush's cli tools. When using `rush install`, rush will use `pnpm install` behind the scenes within each package's directories. Each dependency is actually installed in a directory (.pnpm) located in your home directory and hardlinked to within Rush's internal temporary store at `common/temp/`. Each dependency of a package located under `<package-name>/node_modules/` is actually a hard symlink to rush's own temporary store at `common/temp/`.
Rush configuration is stored in the root directory as `rush.json`.
Each package also no longer uses package-lock.json or yarn.lock. Instead, a single pnpm-lock.yaml file is made under `common/temp/` which is created/updated when running rush commands.
Rush also either symlinks (by default) or local installs a copy of every package that uses one another from the monorepo. An example of this is Mayflower React. Mayflower React depends on Mayflower Assets, so under Mayflower React's `node_modules/` there is a symlink that points directly to the location of Mayflower Assets on disk instead of the rush temporary store under `common/temp/`.
#### Useful Commands
- `rush install` - Use this to install dependencies for all packages.
- `rush update` - Use this after updating rush/pnpm configurations.
- `rush build` - Use this to make production builds for all packages.
- `rush add` - Use this to add a new dependency to a package.
- To add a dependency for a package, `cd` into the specific package directory and run `rush add --package "example@^1.2.3"`
> For more rush commands, see the [rush command documentation](https://rushjs.io/pages/commands/rush_add/).
#### Other Commands
When needing to run other commands for a package (such as starting up development mode), use `rushx` instead of `npm` or `yarn` in the package directory. For example, to run development mode for react, instead of using `npm run start`, move to the `packages/react/` direction and use `rushx start`.
### Custom Commands
Custom commands for rush are defined within `common/config/rush/command-line.json`. The following custom commands exist:
- `rush start:core` - Starts storybook in development mode for Mayflower Core.
- `rush start:react` - Starts storybook in development mode for Mayflower React.
- `rush start:patternlab` - Starts patternlab in development mode for Mayflower Artifacts
- `rush start:site` - Starts gatsby in development mode for `packages/site`.
> For more information on custom commands see the [Rush custom commands documentation](https://rushjs.io/pages/maintainer/custom_commands/).
## Continuous Integration using CircleCI
By default, each push to a remote branch will trigger build and tests for React Storybook and Patternlab, deploy the Patternlab site build bundle to S3, as well as run the distribution build for the mayflower-tokens package in the [assets](/assets) folder.
For efficiency purposes, we allow CircleCI to bypass certain jobs based on the prefix of the branch name. Please only use these prefixes for the following scenarios:
| Branch name prefix | Rule | Scenario |
|---|---|---|
| `core/` | This will bypass Patternlab build, deploy and tests | This prefix should only be used if all your changes are in the [core](/packages/core) folder
| `react/` | This will bypass Patternlab build, deploy and tests | This prefix should only be used if all your changes are in the [react](/packages/react) folder, and nothing in the shared [assets](/packages/assets) folder that could potentially impact the build of the Patternlab implementation |
| `pattern/` | This will bypass React Storybook build and tests | This prefix should only be used if all your changes are in the [patternlab](/packages/patternlab) folder, and nothing in the shared [assets](/packages/assets) folder that could potentially impact the build of the React implementation |
| `site/` | This will bypass all React and Patternlab and assets build, deploy and tests. | Only use this prefix if all the changes are in the [site](/packages/site) folder. e.g. Content changes to the homepage site that won't impact React, Patternlab and shared assets. |
| `docs` | This will bypass all React and Patternlab and assets build, deploy and tests, as well as Mayflower site build and tests. | Only use this prefix if all the changes are in the [docs](/docs) folder. e.g. Documentation changes for the repo that won't impact React, Patternlab, shared assets and the homepage static site. |