Manage frontend dependencies
GOV.UK Platform as a Service team has four major web apps that require regular maintenance:
PaaS admin is a server-side rendered React web app. It utilises NPM dependencies and it will have by far the most dependency updates. Dependabot is set up to raise dependecy update pull requests and security audits. Tests are set up and demand 100% code coverage.
On merge to
- tests run and if sucessful, a git tag with a version number is created, and updated in the paas-admin version file
- once the tag is created, staging tests and deployment commence; if sucessful, a new git tag is created (
- if staging deployment is sucessful, production deployment goes ahead
Pull request merge commits must be signed with a team member’s GPG key, which can be done using the GDS CLI tool (
gds git merge-sign alphagov/paas-admin PR_NUMBER).
Do not merge through the GitHub UI.
Product pages are a set of static pages built by NextJS. It utilises NPM dependencies and will have many fewer dependency updates than PaaS admin Dependabot is set up to raise dependecy update pull requests and security audits.
There are some tests set up but it’s recomended to run a local static build for bigger updates,
which is documented in the
Dependabot pull requests need to be approved and can be merged in the Github web UI.
Tenant-facing tech docs and team manual
Tech docs and team manual are implementations of the
tech-docs-gem, a Ruby gem that distributes the Tech Docs Template. The Tech Docs Template is a middleman template that you can use to build technical documentation using a GOV.UK style.
In addition to the upstream tech-docs-gem dependency there are some local Ruby dependencies. Dependabot will raise update pull request against all dependencies, but it’s always best to check if a new version of the gem has been released. Follow the project READMEs to get started.
Dependabot pull requests can be merged in the Github web UI.
Some of the strategies to use when managing updates
- read release notes
Most packages will have some release notes. Even though they might use semantic versioning (semver), it doesn’t mean a fix/patch update doesn’t contain major changes.
Most packages below version 1, don’t necessarily use semVer. When in doubt, check usage in our codebase.
- run locally to check the build (if needed)
If you’re unsure about package changes, need to run tests (locally or against staging, etc) or wish to manually check everything is OK, all of these have the ability to run locally.
- merge and deploy one dependency at a time
Sometimes there are unexpected staging or production build or test failures, so a good strategy is to merge and deploy one at a time. That way you can easily roll back the commit and continue with other dependencies.
In case of
paas-admin, if a staging tag is created, all is ok. All others are deployed straight to production.
Audit installed NPM dependecies
npm ls <package name>This will list all the versions of packages that are installed.
Example output for
npm ls got
├─┬ email@example.com │ └─┬ firstname.lastname@example.org │ └─┬ email@example.com │ └─┬ firstname.lastname@example.org │ └─┬ email@example.com │ └── firstname.lastname@example.org └─┬ email@example.com └── firstname.lastname@example.org
npm explain <package name>This will list the chain of dependencies causing a given package to be installed in the current project, a “bottoms up” view of why a given package is included in the tree at all.
Example output for
npm explain got
email@example.com dev node_modules/got got@"^9.6.0" from firstname.lastname@example.org node_modules/package-json package-json@"^6.3.0" from email@example.com node_modules/latest-version latest-version@"^5.1.0" from firstname.lastname@example.org node_modules/update-notifier update-notifier@"^5.1.0" from email@example.com node_modules/nodemon nodemon@"2.0.16" from firstname.lastname@example.org node_modules/nodemon-webpack-plugin dev nodemon-webpack-plugin@"^4.8.0" from the root project email@example.com node_modules/openid-client/node_modules/got got@"^11.8.0" from firstname.lastname@example.org node_modules/openid-client openid-client@"^4.9.1" from the root project
Audit and update NPM sub-dependecies
Submits a description of the dependencies configured in the project to the default registry and asks for a report of known vulnerabilities.
If any vulnerabilities are found, then the impact and appropriate remediation will be calculated.
fix argument is provided, then remediations will be applied to the package tree.
If dependabot has raised an alert about a potential security vulnerabilities in project dependencies, you can use
npm audit to check for any packages that can be updated.
Example output of
No fix available node_modules/got node_modules/openid-client/node_modules/got package-json <=6.5.0 Depends on vulnerable versions of got node_modules/package-json latest-version 0.2.0 - 5.1.0 Depends on vulnerable versions of package-json node_modules/latest-version update-notifier 0.2.0 - 5.1.0 Depends on vulnerable versions of latest-version node_modules/update-notifier nodemon >=1.3.5 Depends on vulnerable versions of update-notifier node_modules/nodemon nodemon-webpack-plugin * Depends on vulnerable versions of nodemon node_modules/nodemon-webpack-plugin 6 moderate severity vulnerabilities Some issues need review, and may require choosing a different dependency.