node-modules

🧪 An experimental monorepo for @guardian/* NPM packages.

This repo contains a number of pre-configured workflows that make it easier to develop and update packages in accordance with the Guardian's recommendations.

Show workflows

• Node version management
• NPM package management
• TypeScript configuration
• Eslint configuration
• Testing (using Jest)
• Bundling (using @guardian/pkgu – a member of this project)
• Versioning (using changesets)
• Publishing (using changesets)
• Package config validation

Packages

The following packages live in ./packages:

• @guardian/editorconfig
  • A standard .editorconfig for the Guardian.
• @guardian/foo
  • A simple test module.
• @guardian/foo-react
  • A simple test module with react.
• @guardian/pkgu
  • Automatically build @guardian packages for publishing to NPM in line with our recommendations.

Adding a package

🚧 It's not ready for new packages yet, but when it is...

Packages only need to worry about what they do – everything else is managed by the project.

1. Create a directory in ./packages
2. Add a package.json, README.md and src/index.ts
3. Run make verify-packages

You now have a minimal but verifiable, publishable package.

Development

tl;dr

1. Clone the repo
2. Run make dev, or
3. Run make help to see what else you can do

Details

npm-scripts

Key project tasks (build, test etc) are defined in the npm-scripts of the root package.json.

These are mainly for CI or advanced use. Feel free to run them directly if you prefer, but the makefile (below) is intended to day-to-day development work.

makefile

Human-optimised project tasks are defined in the makefile.

These are the npm-scripts wrapped in unobtrusive admin tasks that overcome common dev gotchas (correct Node version, up-to-date deps etc).

🧑‍💻 If it helps, think of the makefile tasks like GitHub Actions for people.

Running makefile tasks

Run them from the terminal using make. Here are some common examples:

• make build build all packages
• make bump bump all updated packages
• make changeset create a new changeset
• make clean delete all dist directories
• make dev run the test suite in watch mode
• make fix try to fix eslint errors
• make help list available commands
• make install install everything you need to run the project
• make lint run eslint over all source code
• make manage-repo keep repo config up-to-date
• make release publish all updated packages
• make test run all tests
• make tsc check all typescript compiles
• make validate runs test, lint, tsc and verify-packages
• make verify-packages verify all packages are setup correctly

Run make help to see the full list of commands.

Project requirements

Node version, package manager, NPM dependencies etc are automatically managed by the make tasks – you can use any make command without worrying about them.

You'll be prompted if you need to install anything.

Advanced

Behind the scenes, the project is a pnpm workspace.

If you need to do more than the tasks defined in the makefile – for example, adding a dependency to your package or managing CI – you should use pnpm directly.

See the pnpm docs for full information.

Releasing

Versioning and releasing of updated packages is managed with changesets.

Make sure you understand how changesets work before starting a new release.

# generate a new changeset
$ make changeset

# version-bump updated packages
$ make bump

# push the new versions to NPM
$ make release