csnx

Monorepo for Guardian UIs

Projects in the monorepo

Packages

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/identity-auth
• @guardian/identity-auth-frontend
• @guardian/libs
• @guardian/newsletter-types
• @guardian/prettier
• @guardian/source
• @guardian/source-development-kitchen
• @guardian/tsconfig

Deprecated Packages

• @guardian/atoms-rendering

Development

1. Clone the repo
2. Run a task.

You'll be prompted to install any missing requirements if they are needed...

Tasks

Cross-project tasks

Tasks that apply to all projects are defined in the Makefile:

• make build builds all projects
• make build-storybook builds all storybooks
• make changeset creates a new changeset
• make changeset-version takes changesets that have been made and updates versions and dependencies of packages, as well as writing changelogs updates the lockfile with the updated versions of the packages https://github.com/changesets/changesets/issues/421
• make clean removes all build artifacts and task caches
• make dev runs the dev targets for all projects in single instance
• make e2e runs the e2e tests for all projects
• make fix attemps to fix lint errors across all projects
• make formatting:check check repo for formatting errors
• make lint checks all projects for lint errors
• make ls lists available make targets
• make storybooks runs storybook for all projects in single instance
• make test runs the unit tests for all projects
• make test:coverage get test coverage for CSTI projects
• make tsc type-checking all projects
• make validate makes sure absolutely everything is working
• make verify-dist runs unit tests against dist for all projects

Project-specific tasks

Project-specific tasks are defined as scripts in their package.json, and can be run with make <project>:<script>:

@guardian/ab-core

• make @guardian/ab-core:build
• make @guardian/ab-core:dev
• make @guardian/ab-core:fix
• make @guardian/ab-core:lint
• make @guardian/ab-core:test
• make @guardian/ab-core:tsc
• make @guardian/ab-core:verify-dist

@guardian/ab-react

• make @guardian/ab-react:build
• make @guardian/ab-react:dev
• make @guardian/ab-react:fix
• make @guardian/ab-react:lint
• make @guardian/ab-react:test
• make @guardian/ab-react:tsc
• make @guardian/ab-react:verify-dist

@guardian/browserslist-config

• make @guardian/browserslist-config:fix
• make @guardian/browserslist-config:lint
• make @guardian/browserslist-config:tsc
• make @guardian/browserslist-config:update-readme

@guardian/cobalt-plugin-ts

• make @guardian/cobalt-plugin-ts:fix
• make @guardian/cobalt-plugin-ts:lint
• make @guardian/cobalt-plugin-ts:tsc

@guardian/core-web-vitals

• make @guardian/core-web-vitals:build
• make @guardian/core-web-vitals:dev
• make @guardian/core-web-vitals:fix
• make @guardian/core-web-vitals:lint
• make @guardian/core-web-vitals:test
• make @guardian/core-web-vitals:tsc
• make @guardian/core-web-vitals:verify-dist

@guardian/eslint-config

• make @guardian/eslint-config:fix
• make @guardian/eslint-config:lint
• make @guardian/eslint-config:tsc

@guardian/eslint-config-typescript

• make @guardian/eslint-config-typescript:fix
• make @guardian/eslint-config-typescript:lint
• make @guardian/eslint-config-typescript:tsc

@guardian/identity-auth

• make @guardian/identity-auth:build
• make @guardian/identity-auth:dev
• make @guardian/identity-auth:fix
• make @guardian/identity-auth:lint
• make @guardian/identity-auth:test
• make @guardian/identity-auth:tsc
• make @guardian/identity-auth:verify-dist

@guardian/identity-auth-frontend

• make @guardian/identity-auth-frontend:build
• make @guardian/identity-auth-frontend:dev
• make @guardian/identity-auth-frontend:fix
• make @guardian/identity-auth-frontend:lint
• make @guardian/identity-auth-frontend:test
• make @guardian/identity-auth-frontend:tsc
• make @guardian/identity-auth-frontend:verify-dist

@guardian/libs

• make @guardian/libs:build
• make @guardian/libs:dev
• make @guardian/libs:e2e
• make @guardian/libs:e2e:ui
• make @guardian/libs:fix
• make @guardian/libs:lint
• make @guardian/libs:sourcepoint-integration-test
• make @guardian/libs:test
• make @guardian/libs:tsc
• make @guardian/libs:verify-dist

@guardian/newsletter-types

• make @guardian/newsletter-types:build
• make @guardian/newsletter-types:dev
• make @guardian/newsletter-types:fix
• make @guardian/newsletter-types:lint
• make @guardian/newsletter-types:tsc

@guardian/prettier

• make @guardian/prettier:fix
• make @guardian/prettier:lint
• make @guardian/prettier:tsc

@guardian/source

• make @guardian/source:build
• make @guardian/source:build-generated
• make @guardian/source:build-storybook
• make @guardian/source:create-icons
• make @guardian/source:dev
• make @guardian/source:fix
• make @guardian/source:lint
• make @guardian/source:storybook
• make @guardian/source:test
• make @guardian/source:tsc
• make @guardian/source:verify-dist

@guardian/source-development-kitchen

• make @guardian/source-development-kitchen:build
• make @guardian/source-development-kitchen:build-storybook
• make @guardian/source-development-kitchen:dev
• make @guardian/source-development-kitchen:fix
• make @guardian/source-development-kitchen:lint
• make @guardian/source-development-kitchen:storybook
• make @guardian/source-development-kitchen:test
• make @guardian/source-development-kitchen:tsc
• make @guardian/source-development-kitchen:verify-dist

github-pages

• make github-pages:build
• make github-pages:dev
• make github-pages:start
• make github-pages:tsc

storybooks

• make storybooks:dev

Chromatic

CSNX 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.

Releasing a package update

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.

Troubleshooting

Editor setup

VS Code

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.

Unable to commit

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 use

Or 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.sh

Or for nvm:

# ~/.config/husky/init.sh
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" && nvm use

See https://typicode.github.io/husky/how-to.html for more info.