npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ons/design-system

v72.1.2

Published

ONS Design System built CSS, JS, and Nunjucks templates

Downloads

1,988

Readme

ONS Design System

GitHub release Tests GitHub pull requests Github last commit Github contributors

Installing as a dependency

Nunjucks macros for components and templates are available from npm. Built CSS and JS is also available if you need access to pre-release CSS/JS, otherwise CSS and JS should be loaded from the CDN.

yarn add @ons/design-system

Run Locally

You'll need Git, Node.js, and Yarn to run this project locally.

The version of node required is outlined in .nvmrc.

Using nvm (optional)

If you work across multiple Node.js projects there's a good chance they require different Node.js and npm versions.

To enable this we use nvm (Node Version Manager) to switch between versions easily.

  1. install nvm
  2. Run nvm install in the project directory (this will use .nvmrc)

Install dependencies

yarn install
yarn husky install

Start a local server

yarn start

Once the server has started, navigate to http://localhost:3030

Lighthouse Testing - local

This project uses LHCI.

yarn global add @lhci/cli
yarn test-lighthouse

Testing - macros and scripts

This project uses jest and supports its command line options.

yarn test [jest-args]

Run macro, unit and in-browser interaction tests

Macros and units are tested in the Node execution environment whereas interaction tests are ran in the web browser using puppeteer.

yarn test

Run specific tests

Tests can be filtered using the testNamePattern jest argument.

To run all macro tests:

yarn test --testNamePattern="macro:"

To run tests associated with a specific macro:

yarn test --testNamePattern="macro: button"

To run all axe tests:

yarn test --testNamePattern="axe"

Snapshot test for base page template

There is a snapshot test of the base page template that runs alongside the component tests. The snapshot will need to be updated if the base page template is changed.

To update the snapshot:

yarn test --testNamePattern="base page template" -u

Run tests locally in watch mode

This will watch for changed files based on git uncommitted files.

yarn test --watch

Note: This command is of limited use since JavaScript and SCSS files will only be processed and bundled once each time the above command is ran. This command is only useful when working on JavaScript units that can be tested without bundling.

Testing tips

It is sometimes useful to adjust the following settings when writing tests or diagnosing issues:

  • headless in 'jest-puppeteer.config.js' - when set to false will show web browser whilst running tests. Many browser windows open since jest runs tests in parallel so it is useful to also adjust the test script inside 'package.json' such that it targets a specific test file. await new Promise(r => setTimeout(r, 100000)); can be temporarily added to a test to allow yourself time to inspect the browser that appears.

  • testTimeout in 'jest.config.js' - set to a high value such as 1000000 to prevent tests from timing out when doing the above.

Testing - Visual regression tests

This project uses Backstop JS for visual regression testing. The tests run in Chrome headless using Puppeteer inside docker and run in three viewports; 1920 (desktop), 768 (tablet) and 375 (mobile). Reference images are stored in Git LFS and any approved changes will automatically be stored in Git LFS when pushed to the repository.

The visual tests will run automatically on pull requests and the result will be available in the Github Action logs. If the tests fail, the process for viewing the failures and approving changes will need to be handled locally using the following workflow and commands.

The first time you run the tests locally you will need to install Git LFS on your machine. Follow the install instructions for Git LFS.

You will need to have Docker installed and started locally. We are using Docker as there are font rendering issues that caused failures across different os versions when we run the tests in CI. There is further information on this in the Backstop JS docs.

Checkout the branch locally and run:

git lfs fetch - This downloads the files into your .git/lfs if you have never run vr test locally.

git lfs checkout - This will pull the current reference images from the repository for you to test against.

yarn test-visual - This will run the same tests locally as were run in Github Actions. After they have completed the report will open in your default browser.

yarn test-visual:approve - This will approve the failures/diff caught by the tests.

git lfs push --all origin - First commit the files in the normal way then run the command. This will push the new reference images to Git LFS.

You can then commit and push the updated references and your changes to your branch. The test images that would have been created when you ran yarn test-visual are gitignored and the new references images will be pushed to Git LFS.

If your local tests are failing but you have approved them, run yarn test-visual:reference. This will update the reference images locally on your machine.

Build

Generate a build into ./build.

yarn build

Manually publish to NPM

Make sure you are logged into the CLI with the DS shared npm account

Make sure dependencies are installed:

yarn install

Set the version (replacing "" with actual release version e.g. 70.0.0):

npm version <DS release version>

Create an NPM package by running:

yarn npm-bundle

Once you have published to npm, the version you have published can never be used again so you want to make sure you have the right files included to do this run:

npm pack

Then compare this list with the list of the current version here (https://www.npmjs.com/package/@ons/design-system?activeTab=code)

If these match or have some expected changes then run this to publish:

npm publish --access public

Recommended Visual Studio Code Extensions for this project