WA Gov Web Standards library

This library is developed to establish unique, yet consistent experience among all the different microservices that are developed in WA Gov. This library repo contains a set of React.js + SASS components, bundled and build by Rollup and documented/visualized through Storybook. On top of that, we use Typescript to offer static-type support for easier usage. Testing with Jest is a pending feature currently

How we use it - setup

This library is build/bundled to plain JavaScript with Rollup.js and published to NPM Registry. Then, this library can be used in any React.js project. For best performance and faster local development, we recommend you use the same React.js version between this library and the project

Notice that this library has both package-lock.json and yarn.lock. We update the npm packages by running

npm install

Then run yarn import. This is intended exclusively for local development, because both npm and yarn have linking capabilities (more about this below). In any case, we must make sure package.json is up-to-date before we try to link or publish new version

How we use the components locally

We use 2 tools/features to speed up development and ensure everything is working as expected

1. Using yarn/npm dependency linking on local environment for development purposes (yarn is recommended, yet npm can be used as well). Once connected, it should maintain the link indefinitely)

   • Open the library's project folder in the console and run

     yarn link

   • Open another console window in the project folder using the library and run

     yarn link @dgov/components-library

   • If you have issues doing that, you might have to 'yarn link' react and react-dom from the node_modules folder (check this quick solution). Suggest a better solution, if this issue arises to you, anyways this should work in case of errors

   • After this, your project will have the latest local library changes everytime you rebuild the library by running

     yarn build

   Linking helps us to develop this library in parallel with our project, decreasing the number of published npm versions

2. Using Storybook to document the library and create UI/UX playground website, where you can test the library components in isolation. To run a local version of the website, in the console run

   yarn storybook

   In order to deploy the storybook website on a domain you should run

   yarn storybook:export

How we develop components

The best way to develop/improve library components is do it with a purpose in mind. In other words, we develop/improve components ONLY when that's is necessary for a particular project. The aim is to connect the library to your project, and develop/improve the component.

In case where you improve/change a component, PLEASE make sure all the other projects where that component is used to be updated/reviewed as well. We should avoid breaking functional or visual changes, otherwise we should make sure this breaking changes are handled properly.

Each component has to be independent, meaning you can move the component folder around or copy it in a different project, and that won't cause the component to crash. Every component should have at least these 4 files:

1. index.tsx - functional component code
2. [name].scss - SCSS styling for that component
3. [name].stories.tsx - Storybook rendering file for the playground
4. [name].types.ts - all Typescript interfaces and types for the component

How we publish new version on NPM registry

Once you get logged in to Node and have developer permissions to publish new versions you can run npm publish --access=public

You must bump up the version before you publish the changes. You can do this in 2 ways

1. Update the version in package.json and package-lock.json. Ocassionally, you can run in console yarn import to maintain consistency
2. Write in the console npm version patch, which will update the patch version and git-commit the updated version