Monorepo for Guardian UIs
The following packages live in libs/@guardian/* and are published to NPM:
- @guardian/ab-core
- @guardian/ab-react
- @guardian/browserslist-config
- @guardian/core-web-vitals
- @guardian/eslint-config
- @guardian/eslint-config-typescript
- @guardian/eslint-plugin-source-foundations
- @guardian/eslint-plugin-source-react-components
- @guardian/identity-auth
- @guardian/identity-auth-frontend
- @guardian/libs
- @guardian/newsletter-types
- @guardian/prettier
- @guardian/source-foundations
- @guardian/source-react-components
- @guardian/source-react-components-development-kitchen
- @guardian/tsconfig
- Clone the repo
- Run a task.
You'll be prompted to install any missing requirements if they are needed...
Tasks that apply to all projects are defined in the Makefile:
make buildbuilds all projectsmake build:storybooksbuilds all storybooksmake changesetcreates a new changesetmake cleanremoves all build artifactsmake devruns the dev targets for all projects in single instancemake e2eruns the e2e tests for all projectsmake fixattemps to fix lint errors across all projectsmake formatting:checkcheck repo for formatting errorsmake lintchecks all projects for lint errorsmake lslists availablemaketargetsmake storybooksruns storybook for all projects in single instancemake testruns the unit tests for all projectsmake validatemakes sure absolutely everything is workingmake verify-distruns unit tests against dist for all projects
Project-specific tasks are defined as scripts in a package.json or targets in a project.json files, and can be run with make <project>:<script>/make <project>:<target>:
make @guardian/ab-core:buildmake @guardian/ab-core:devmake @guardian/ab-core:fixmake @guardian/ab-core:lintmake @guardian/ab-core:testmake @guardian/ab-core:verify-dist
make @guardian/ab-react:buildmake @guardian/ab-react:devmake @guardian/ab-react:fixmake @guardian/ab-react:lintmake @guardian/ab-react:testmake @guardian/ab-react:verify-dist
make @guardian/browserslist-config:fixmake @guardian/browserslist-config:lintmake @guardian/browserslist-config:update-readme
make @guardian/cobalt-plugin-ts:fixmake @guardian/cobalt-plugin-ts:lint
make @guardian/core-web-vitals:buildmake @guardian/core-web-vitals:devmake @guardian/core-web-vitals:fixmake @guardian/core-web-vitals:lintmake @guardian/core-web-vitals:testmake @guardian/core-web-vitals:verify-dist
make @guardian/design-tokens:buildmake @guardian/design-tokens:fixmake @guardian/design-tokens:lint
make @guardian/eslint-config:fixmake @guardian/eslint-config:lint
make @guardian/eslint-config-typescript:fixmake @guardian/eslint-config-typescript:lint
make @guardian/eslint-plugin-source-foundations:buildmake @guardian/eslint-plugin-source-foundations:devmake @guardian/eslint-plugin-source-foundations:fixmake @guardian/eslint-plugin-source-foundations:lintmake @guardian/eslint-plugin-source-foundations:testmake @guardian/eslint-plugin-source-foundations:verify-dist
make @guardian/eslint-plugin-source-react-components:buildmake @guardian/eslint-plugin-source-react-components:devmake @guardian/eslint-plugin-source-react-components:fixmake @guardian/eslint-plugin-source-react-components:lintmake @guardian/eslint-plugin-source-react-components:testmake @guardian/eslint-plugin-source-react-components:verify-dist
make @guardian/identity-auth:buildmake @guardian/identity-auth:devmake @guardian/identity-auth:fixmake @guardian/identity-auth:lintmake @guardian/identity-auth:testmake @guardian/identity-auth:verify-dist
make @guardian/identity-auth-frontend:buildmake @guardian/identity-auth-frontend:devmake @guardian/identity-auth-frontend:fixmake @guardian/identity-auth-frontend:lintmake @guardian/identity-auth-frontend:testmake @guardian/identity-auth-frontend:verify-dist
make @guardian/libs:buildmake @guardian/libs:devmake @guardian/libs:e2emake @guardian/libs:fixmake @guardian/libs:lintmake @guardian/libs:testmake @guardian/libs:verify-dist
make @guardian/newsletter-types:buildmake @guardian/newsletter-types:devmake @guardian/newsletter-types:fixmake @guardian/newsletter-types:lint
make @guardian/prettier:fixmake @guardian/prettier:lint
make @guardian/source-foundations:buildmake @guardian/source-foundations:build-storybookmake @guardian/source-foundations:build-type-presetsmake @guardian/source-foundations:devmake @guardian/source-foundations:fixmake @guardian/source-foundations:lintmake @guardian/source-foundations:storybookmake @guardian/source-foundations:testmake @guardian/source-foundations:verify-dist
make @guardian/source-react-components:buildmake @guardian/source-react-components:build-storybookmake @guardian/source-react-components:create-iconsmake @guardian/source-react-components:devmake @guardian/source-react-components:fixmake @guardian/source-react-components:lintmake @guardian/source-react-components:storybookmake @guardian/source-react-components:testmake @guardian/source-react-components:verify-dist
make @guardian/source-react-components-development-kitchen:buildmake @guardian/source-react-components-development-kitchen:build-storybookmake @guardian/source-react-components-development-kitchen:devmake @guardian/source-react-components-development-kitchen:fixmake @guardian/source-react-components-development-kitchen:lintmake @guardian/source-react-components-development-kitchen:storybookmake @guardian/source-react-components-development-kitchen:testmake @guardian/source-react-components-development-kitchen:verify-dist
make @guardian/tsconfig:fixmake @guardian/tsconfig:lint
make github-pages:buildmake github-pages:devmake github-pages:start
make storybooks:dev
Tasks are managed by Nx.
Nx remotely caches the output of build, lint, test, and verify-dist.
This means only one full iteration of these tasks runs for a given state of a project – ever – which makes them extremely fast to re-run.
For example, you're working on something, run the tests and they pass. Nx remotely caches the result. You push your changes to CI. When CI runs the tests, nothing has changed, so Nx fetches the (passing) cached results, the build goes green and you can merge.
When I pull your changes, my copy of the code is identical to what you pushed and merged, so I also get the cached results. If I then change the code, Nx re-runs the tests and, again, caches the results.
This happens per project. So if you change project-a but not project-b, Nx will get the cached results for project-b, but still run the tests for project-a. From then on, until project-a changes again, Nx will always use the cached results for both.
This includes between development and CI, between machines, pulls etc.
To force the tasks in the Makefile to skip the Nx cache, set SKIP_NX_CACHE=true, e.g.
SKIP_NX_CACHE=true make testCSNX uses Chromatic for visual regression testing, and all PRs require the Chromatic checks to pass before merging.
However, each run costs money, so we only want to run Chromatic when a PR is ready to merge (rather than for every push, for example).
Therefore, initially, Chromatic checks will not run.
When your PR is ready, add the run_chromatic label. This will starts Chromatic checks.
Note
Each push while the label is applied will trigger new checks, so you may want to remove the label if you're making more changes.
Once all checks pass, you're good to merge.
Libs within CSNX are available as NPM packages. We use Changesets to automate this release process.
To publish your changes to NPM, run make changeset. This will open the Changesets CLI, and you will be offered a list of packages to release. Once you've selected the changed package/s you'll be given the option of major, minor or patch release. Select one of these and add a description.
This will create a "changeset": a .md file containing the release information. When you merge your branch, the changeset will be picked up by the Changests GHA, which will in turn create a release PR. To complete the NPM release merge this second PR.
You will be prompted to install the recommended extensions when you open the repo.
There is also a suggested settings file (./.vscode/settings.json.default) with some defaults you may useful. It covers project-specific enhancements, useful settings for common extensions etc.
If you want to use any/all of them, create a copy of the file and remove the .default extension.
n.b. these are your personal settings for this repo, so add anything else you find useful and remove/change anything you don't like.
If you get a command not found error or a message saying you're using the wrong version of Node when commiting using a GUI (VSCode, GitHub desktop etc), add a ~/.config/husky/init.sh file and load your Node version manager there.
Note
This used be located in ~/.huskyrc. If you set that up before, you will need to recreate it at ~/.config/husky/init.sh.
mkdir -p ~/.config/husky && cp ~/.huskyrc $_/init.sh
For example, if you use fnm:
# ~/.config/husky/init.sh
eval "$(fnm env)"
fnm useOr for asdf:
# ~/.config/husky/init.sh (installed with git)
. $HOME/.asdf/asdf.sh# ~/.config/husky/init.sh (installed with brew on intel macs)
. /usr/local/opt/asdf/libexec/asdf.sh# ~/.config/husky/init.sh (installed with brew on apple silicon)
. /opt/homebrew/opt/asdf/asdf.shOr for nvm:
# ~/.config/husky/init.sh
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" && nvm useSee https://typicode.github.io/husky/how-to.html for more info.