0.0.2 • Published 5 months ago

@govuk-one-login/frontend-logger

Licence

ISC

Version

0.0.2

Deps

Size

66 kB

Vulns

Weekly

Summary Dependency Versions

GovUK Frontend Monorepo

This monorepo is designed to house packages and UI components based on the GOV.UK Frontend design system. It utilises the Nx workspace for managing multiple projects within a single repository.

Features

Nx workspace setup for efficient development and collaboration.
Integration of GovUK Frontend packages and UI components.
Simplified build and deployment processes.
Consistent coding standards and best practices set out in the GDS way https://gds-way.digital.cabinet-office.gov.uk/standards

Project Structure

The monorepo is organised using Nx workspace conventions

Continuous Deployment (CD) Workflow

To trigger the CD workflow manually, follow these steps:

Go to the Actions tab in this repository.
Click on the "CD" workflow.
Click the "Run workflow" button.
Select the target package and the desired increment type.
Click the "Run workflow" button to start the deployment process.

Getting started

At present we consume one package from a private registry (@govuk-one-login/event-catalogue). To authenticate with GitHub Packages to get this package you should follow the instructions in the team manual.

To get started in this repository we recommned you:

Run npm install to get all the neccessary dependencies.
Run npm run prepare-dependencies to prepare any dependencies that were broken by disabling npm lifecycle scripts.
Run npm run build to build all dependencies so that interlinked packages work.

Create A New Package

To create a new package, follow these steps:

Run the following command:

nx g automation:generate-component

Or, if you want to specify the package name, run:

nx g automation:generate-component package-name

The NX prompt will ask you the following questions:
- Name: What name would you like to use? (required)
- Description: What is the package about? (optional)
Answer the prompts accordingly. If you provided the package name in the command, you won't be asked for it.
After answering the questions, the command will generate the package with the necessary files.

Lint and format the code with Biome:

This project uses Biome for linting and formatting. Biome replaces ESLint and Prettier with a single fast tool.

To Run All Packages

To check linting and formatting issues in all packages: nx run-many --target=lint --all

To check code formatting in all packages: nx run-many --target=format:check --all

To fix formatting issues that can be resolved automatically: nx run-many --target=format --all

To run a full check (lint + format + import sorting) and auto-fix: npm run check:fix

To run the above commands on just affected packages, replace run-many with affected

To Run a Singular Package

To check lint issues in a specific package: nx run [package-name]:lint

To check and fix code formatting issues in a specific package: nx run [package-name]:format

Configuration

The rules for linting and formatting are defined in biome.json at the root of the repository. Biome uses a single configuration file for both linting and formatting.

Editor Integration

Install the Biome VS Code extension for format-on-save and inline lint diagnostics.

Setup Instructions

To ensure that NX is running the latest versions of all packages within the monorepository, follow these steps:

At the Root Level:

Install dependencies by running npm install.
Build the entire project by running npm run build.

At the `alpha-app` Level:

Start the development server by running npm run dev. This will automatically refresh the symlink as part of the watch command, ensuring that changes to linked packages are up-to-date.

At the `frontend-language-toggle` Level:

Start the development process by running npm run dev.
Ensure that this package is running alongside the dev command to reflect updates properly.

Running `alpha-app`

npm run build at the root
npm run start in alpha-app
The app should be running on localhost:3000

Publishing Packages

To release a package from the monorepo, use the GitHub Actions Release workflow. This workflow automates versioning and package publishing to NPM. Follow these steps to initiate a release:

Trigger the Workflow
Go to the Actions tab in the GitHub repository, select the Release workflow, and click Run workflow.
Fill in the Required Inputs:
- Target: Choose the package you want to release from the list of options:
  - @govuk-one-login/alpha-component
  - @govuk-one-login/frontend-analytics
  - @govuk-one-login/frontend-language-toggle
  - @govuk-one-login/frontend-passthrough-headers
  - @govuk-one-login/frontend-vital-signs
  - @govuk-one-login/frontend-asset-loader
  - @govuk-one-login/frontend-device-intelligence
- Increment: Select the version increment for this release (patch, minor, or major) based on Semantic Versioning.
- First Release: Specify if this is the first release of the package from this repository. If set to true, the workflow will treat it as an initial release.
- Dry Run: Set this to true for a dry run, which will simulate the release process without publishing.
Publishing Process
The workflow will:
- Run format, lint, test, and build checks on the specified package.
- Automatically version and publish the package to NPM if the dry_run is set to false.
Verify the Release
Once the workflow completes, confirm the package has been published on the NPM registry.

Maintaining Older Package Versions

When releasing a new major version of a package (e.g., frontend-ui v5 → v6), you need to maintain the ability to patch the older version for consumers who haven't upgraded yet. This is done using version branches.

Branch Naming Convention

Version branches follow the format: {package-name}@v{major-version}

Examples:

frontend-ui@v1 — maintains v1.x.x of @govuk-one-login/frontend-ui
frontend-analytics@v2 — maintains v2.x.x of @govuk-one-login/frontend-analytics

When to Create a Version Branch

Create a version branch before releasing a new major version. For example, if frontend-ui is currently on v5.3.2 and you're about to release v6.0.0:

Create the version branch from the current state of main (or from the last release tag):
```
git checkout main
git checkout -b frontend-ui@v5
git push -u origin frontend-ui@v5
```
Proceed with the major version release from main.

Releasing a Patch from a Version Branch

Create a feature branch from the version branch:

git checkout frontend-ui@v5
git checkout -b fix/ticket-number/description

Make your changes and push the feature branch.
Open a PR targeting the version branch (e.g., frontend-ui@v5), not main.
Get the required review approval and wait for status checks to pass.
Merge the PR.
Go to Actions → Release → Run workflow.
Select the version branch (e.g., frontend-ui@v5) from the branch dropdown.
Choose the target package and set increment to patch.
Run the workflow — this will publish the patch release from the version branch.

Branch Protections

Version branches have the same protections as main:

Pull requests are required (minimum 1 approving review)
Status checks must pass before merging
Force pushes are blocked
Branch deletion is blocked

See docs/version-branch-ruleset-setup.md for details on how the repository ruleset is configured.

Releasing on Alternative Channels

Sometimes you need to release a pre-release or alternative-channel version of a package — for example, a release candidate (rc) or a beta — without affecting consumers on the latest npm tag. This is done using channel branches.

Channel Branch Naming Convention

Channel branches follow the format: {package-name}@v{version}/{channel-name}

Examples:

frontend-analytics@v1.0.0/rc — release candidate channel for @govuk-one-login/frontend-analytics
frontend-ui@v5.2.0/beta — beta channel for @govuk-one-login/frontend-ui

When to Use a Channel Branch

Use a channel branch when you need to:

Publish a release candidate for testing before a full release
Provide a hotfix to specific consumers without promoting it to latest
Test a package change in a production-like environment before general availability

Creating a Channel Branch and Releasing

Create the channel branch from the appropriate base (e.g., main or a version branch):

git checkout main
git checkout -b frontend-analytics@v1.0.0/rc
git push -u origin frontend-analytics@v1.0.0/rc

Create a feature branch from the channel branch for your changes:

git checkout frontend-analytics@v1.0.0/rc
git checkout -b fix/ticket-number/description

Make your changes and push the feature branch.
Open a PR targeting the channel branch (e.g., frontend-analytics@v1.0.0/rc), not main.
Get the required review approval and wait for status checks to pass.
Merge the PR.
Go to Actions → Release → Run workflow.
Select the channel branch (e.g., frontend-analytics@v1.0.0/rc) from the branch dropdown.
Choose the target package. The increment input is ignored for channel branches — the workflow automatically detects the channel name from the branch and produces a prerelease version (e.g., 1.0.0-rc.0, 1.0.0-rc.1, etc.).
Run the workflow — this will publish a prerelease version to npm.

Installing a Channel Release

Consumers can install a specific prerelease version:

npm install @govuk-one-login/frontend-analytics@1.0.0-rc.0

Channel Branch Protections

Channel branches have the same protections as main and version branches:

Pull requests are required (minimum 1 approving review)
Status checks must pass before merging
Force pushes are blocked
Branch deletion is blocked

See docs/version-branch-ruleset-setup.md for details on how the repository ruleset is configured.

Deprecating Packages

To deprecate a specific package version from the monorepo, use the GitHub Actions Deprecate workflow. This workflow automates deprecating packages in NPM:

Trigger the Workflow Go to the Actions tab in the GitHub repository, select the Deprecate workflow, and click Run workflow.
Fill in the Required Inputs:
- Target: Choose the package you want to release from the list of options:
  - @govuk-one-login/alpha-component
  - @govuk-one-login/event-catalogue-utils
  - @govuk-one-login/frontend-analytics
  - @govuk-one-login/frontend-language-toggle
  - @govuk-one-login/frontend-passthrough-headers
  - @govuk-one-login/frontend-vital-signs
  - @govuk-one-login/frontend-asset-loader
  - @govuk-one-login/frontend-ui
  - @govuk-one-login/frontend-device-intelligence
  - @govuk-one-login/frontend-logger
- Version: Enter the version you want to deprecate (eg 0.0.1, 0.1.1, 1.0.1)
Deprecation Process The workflow will automatically run the npm deprecate command with the input values you have selected.
Verify the Deprecated Once the workflow completes, confirm the package has been deprecated on the NPM registry with an appropriate message.

How to Run Performance Tests

To run performance tests using k6, follow these steps:

Head over to the alpha app and run it in product mode
Change the end-point in the alpha app to test-submit-button
Run the command k6 run testServer.js if you have K6 installed otherwise run npm run test:server

Contributing Code

We welcome contributions from other teams to the govuk-one-login-frontend monorepo! Follow these guidelines to ensure consistency and quality across the repository.

Steps to Contribute

Clone The Repo

Clone the repository locally and navigate into the project directory:

git clone git@github.com:govuk-one-login/govuk-one-login-frontend.git ./your_folder_name

Replace your_folder_name with your desired directory name. If you omit this part, it will clone into a folder named govuk-one-login-frontend.

Creating A Branch

After cloning, create a new branch with a descriptive name that reflects the changes you’re making. For example:

git checkout -b ticket-number/your-feature-name

Install Dependencies

Ensure all dependencies are installed, by running:

npm install

Make Your Changes

Add your code changes, ensuring that they align with GOV.UK OneLogin coding standards and best practices.

Run Tests and Linting

Before pushing your changes, run all tests and linting to make sure your code adheres to the monorepo's requirements:

If you only want to run tests in the affected package, cd into the package folder and run npm test or just npm test at the root level to run all test suites.
If there are any uncommitted changes, you will need to run npx nx run-many -t test as the tests and linters cache the results, so they will only run for changed cases.
Lint and format the code with Biome:

Commit and Push Changes

Use Conventional Commits for your commit messages to ensure automatic versioning and changelog updates. This allows NX to automatically generate a changelog with merged PRs for each release, helping users track the latest changes when they update their packages.

For example:

feat(ticket-number): add new component for user authentication
fix(ticket-number): correct header alignment issue
docs(ticket-number): update README with contribution guidelines

When pushing commits, avoid git push -f to prevent overwriting others' changes. Use git push --force-with-lease to ensure remote changes aren’t accidentally overwritten.

We also encourage squashing each merge to main using conventional commits. This keeps the git log clean and organised.

Open a Pull Request

We use a PR template to ensure all necessary details are captured. Simply fill in the details and check the relevant checkboxes.

Review and Approval

Your PR needs to be reviewed by a member of the code owners, the digital-identity-frontend-capability team. Once approved can be merged into main, but the branch should not be deleted.