🧪 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
The following packages live in ./packages
:
@guardian/editorconfig
- A standard
.editorconfig
for the Guardian.
- A standard
@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.
- Automatically build
🚧 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.
- Create a directory in
./packages
- Add a
package.json
,README.md
andsrc/index.ts
- Run
make verify-packages
You now have a minimal but verifiable, publishable package.
- Clone the repo
- Run
make dev
, or - Run
make help
to see what else you can do
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.
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.
Run them from the terminal using make
. Here are some common examples:
make build
build all packagesmake bump
bump all updated packagesmake changeset
create a new changesetmake clean
delete all dist directoriesmake dev
run the test suite in watch modemake fix
try to fix eslint errorsmake help
list available commandsmake install
install everything you need to run the projectmake lint
run eslint over all source codemake manage-repo
keep repo config up-to-datemake release
publish all updated packagesmake test
run all testsmake tsc
check all typescript compilesmake validate
runstest
,lint
,tsc
andverify-packages
make verify-packages
verify all packages are setup correctly
Run make help
to see the full list of commands.
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.
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.
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