Mayflower-react is a React component library under the enterprise design system for the Commonwealth of Massachusetts.
- Live demo: mayflower-react storybook
- NPM package: @massds/mayflower-react.
- Codebase: Mayflower monorepo
Mayflower monorepo comprised of Mayflower documentation, two component libraries — Mayflower React and Mayflower PatternLab, and their shared assets. Refer to Mayflower PatternLab Static Site for the set of UI components consumed in Mass.gov.
Version 10.x of mayflower-react has removed the
lib/ directories. Instead, the ES5 and ES6 versions now live in the same directory of the component as
// This is the ES5 version.;;// This is the ES6 version.;;
Mayflower React v10.x has its module entry point set to
dist/index.mjs, so if your project is set to use ES Modules, importing from
@massds/mayflower-react will default to using the ES6 version of the package.
As of version 10.x, Mayflower React styles come directly from the
@massds/mayflower-assets package. Each component has been documented with the exact scss files from mayflower-assets you need to include in your project for it to render the same as the Mayflower React Storybook:
/*** Example pulled from ButtonAlert module.* @module @massds/mayflower-react/ButtonAlert* @requires module:@massds/mayflower-assets/scss/01-atoms/button-with-icon* @requires module:@massds/mayflower-assets/scss/01-atoms/button-search* @requires module:@massds/mayflower-assets/scss/01-atoms/input-typeahead* @requires module:@massds/mayflower-assets/scss/01-atoms/svg-icons* @requires module:@massds/mayflower-assets/scss/01-atoms/svg-loc-icons*/
Using Mayflower-React in Your Project
- Install mayflower-react and mayflower-assets into your project dependency:
npm i @massds/mayflower-react @massds/mayflower-assets --save
- Import components into your App:
;// You can also directly point to each component's path:;;;
- Render components:
<Button text="Button" onClick= console />
For a more detailed guide and information on the components included in Mayflower React and their functionality, visit our Mayflower React Storybook. Click on the Info and Knobs tabs for component prop types, details and options.
npm start: This will run the demo application.
- node.js, currently standardized on version 12.18.0
- npm, currently standardized on version 6.4.1
- That's it! All other dependencies should be included when you run
The most common commands can be found in the package.json's
npm run lint and
npm run lint-fix Runs eslint code style checks, with the
-fix added it will attempt to auto-correct any found issues.
npm test: Starts Jest test suite in watch mode
npm run test:coverage Generates a test report
npm run build: Compile the code from
/src into es6 and commonjs formats in preparation for publishing. This command also generates icon components from the .svg files under
We manage all dependencies using npm in the normal way, and we follow the typical convention of committing our package-lock.json file as well. This means that if you install a new dependency, your workflow will look something like this:
npm i purgecss (Installs the new dependency, if you run
git status after this you should see both package.json and package-lock.json showing changes).
git add package.json package-lock.json
git commit -m 'Added purgecss library'
Icon Component Generation
Mayflower React's SVG icon components are generated using SVGR at build time for both development and production modes. Currently, the
.svg files under
src/components/base/Icon/assets are generated into React components. When icon components are generated for production, both ES6 and CommonJS versions of the components are created using babel.
A custom template used by SVGR to create the icon component files can be found within
icon-template.js. SVGR itself is configured using
Production build testing
npm start will kick off a develop environment that hot reloads as you make changes to the codebase. This is great, but sometimes you want to test the production build locally. To do so, you can use the following:
npm i -g http-server
npm run build-storybook
This will spin up a fully optimised production build in your browser for testing.
Production bundle explorer
Source map exploring is useful for analyzing the production js bundles and looking for potential optimizations. It shows you exactly how much of your production bundles are being used by what dependency in a visual way that makes it easy to spot bloat. To open the explorer on a prod build in your browser, use the following:
npm i -g source-map-explorer
npm run build
Testing unpublished Mayflower React components
If you're developing on Mayflower React and want to test your changes on another project (such as Gatsby, Next.JS, Create React App, etc), we recommend using yalc instead of
npm link or
yarn link, as Node dependency resolution issues may arise.
To use yalc:
yalc publishin the
react/directory. This will run Mayflower React's build script and store the build version of the package under your yalc global directory.
yalc link @massds/mayflower-reactin your other project. Mayflower React will now be installed and pointing to the version from step 1.
Mayflower-React Release Process
We are tracking versions of this project in the package.json, which means when cutting a release we expect the main
"version": "0.30.0" to be updated using proper semantic versioning. So if we were releasing a bugfix or other minor improvement we would bump to
0.30.1, if we were releasing a new feature we would bump to
Publish to NPM
- Create a version bump PR into
developupdating package version in
package-lock.json. Squash and merge when ready.
- Create a release PR into
develop. Regular merge when ready.
npm publish. This will publish the latest changes to npm, and automatically runs
npm run buildfirst.
Publish to S3
npm run build-storybook. This will build storybook static site into /storybook-static
- From project root, $
aws s3 sync storybook-static s3://mayflower-react.digital.mass.gov/ --delete(Deploys build to S3 bucket)
aws configure set preview.cloudfront true(Enables CloudFront invalidation commands)
aws cloudfront create-invalidation --distribution-id [!!PROD_DISTRIBUTION_ID_HERE!!] --paths '/*'(Invalidates CloudFront for prod box)
You should see your changes live at mayflower-react storybook within a few minutes!