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

@royaloperahouse/harmonic

v0.1.0

Published

Welcome to The Royal Opera House Front End Design System, `@royaloperahouse/harmonic`

Downloads

72

Readme

Royal Opera House Harmonic - Front End Design System

Welcome to The Royal Opera House Front End Design System, @royaloperahouse/harmonic

This package is a library of UI components intended to be used in the ROH website.

It uses React, TypeScript, TSDX and Storybook.

The NPM packages are published at coming soon

The Storybook for the latest version of the library is hosted at coming soon

Prerequisites


  • Make sure the required package dependencies are installed using yarn install

  • If this is the first time you are working on Harmonic, make sure to run yarn build to build all the modules.

  • To deploy the storybook publicly you will need credentials for the parent 'Royal Opera House' AWS account in your ~/.aws/credentials file.

    • The deploy script expects these to be called [parent].

    • You can find these values at:

      AWS 'Your Applications' page -> 'Royal Opera House' -> 'Developer Access' -> 'Command line or programmatic access'

  • To deploy a preview for demo / QA you will need the CHROMATIC_PROJECT_TOKEN -- find this in 1Password

  • To publish the NPM package you will need the ROH NPM_TOKEN -- find this in 1Password

Versioning


We use Semantic Versioning for Harmonic.

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible library changes
  • MINOR version when you add functionality in a backwards compatible manner
  • PATCH version when you make backwards compatible bug fixes

When you create a new release always update the CHANGELOG and package.json

Increment your version from the latest stable version on (WIP)

Deploying the Storybook


1. To build and deploy locally

You can quickly build and serve the contents of /storybook-static from your local machine, for development and manual testing. To do this run:

yarn storybook

By default the storybook will be accessible at http://localhost:6006/

The server will hot-reload on most changes.

2. To deploy a preview version remotely

You can deploy a release candidate, or work-in-progress to Chromatic for showcase or QA.

NOTE: you will need the CHROMATIC_PROJECT_TOKEN as described in Prerequisites above.

Either set the token as a shell variable or use a .env file in the (WIP) root directory containing the token, as so:

CHROMATIC_PROJECT_TOKEN=tokengoeshere

Run:

yarn deploy-storybook-dev

to build and deploy the storybook from your repo to Chromatic.

You will find the address of your deployed storybook in the console output, looking something like this:

→ View your Storybook at https://randomHexString-randomAlphabeticalString.chromatic.com

3. To deploy a release version

You can deploy the contents of ./storybook-static to S3 as a static site, which is permanently accessible at WIP

NOTE: To do this you will need the correct AWS credentials set up, as described in Prerequisites above.

First build the storybook using:

yarn build-storybook

then run:

yarn deploy-storybook

IMPORTANT: This URL is intended to showcase the latest stable version of (WIP), it should be kept up to date with the main (WIP) branch and should only be used for release versions. If you want to deploy a development version follow the steps above under To deploy a preview version remotely.

Releasing a New Package Version


This is the procedure for releasing a new Harmonic NPM package.

There are two types of package:

A snapshot can be published to use a development version of the (WIP) library in our frontend staging environments, to perform integrated, manual testing.

A stable package is published for use in production.

NOTE: You will need the NPM_TOKEN, as described in 'Prerequisites' above.

1. To release a snapshot version

IMPORTANT: Make sure you always publish your snapshots from (WIP) after merging in your feature branch.

For snapshots, RELEASE_VERSION should be the same as the latest stable version of the (WIP) Library, as found in (WIP), followed by an unused lowercase letter.

For example, if the latest stable release was 1.42.0, and the last snapshot published to NPM was 1.42.0-w, you would use RELEASE_VERSION 1.42.0-x

To publish a snapshot use:

NPM_ROH_TOKEN={NPM_TOKEN} RELEASE_VERSION={RELEASE_VERSION} yarn publish-snapshot

The version published to NPM will be named, e.g. 1.42.0-a-harmonic-development, use this to install the snapshot package in the frontend repos.

2. To release a stable version

IMPORTANT: Make sure you always publish your stable packages from (WIP) after merging in your feature branch.

For stable releases, increment your version from the latest stable version found on (WIP), following the rules described in Versioning above, and use this as RELEASE_VERSION. (Make sure it matches the version in your package.json and CHANGELOG.md!)

To publish a stable package use:

wip

Using the Package


The package is deployed to NPM, and can be installed using yarn or npm:

npm i --save @royaloperahouse/harmonic
yarn add @royaloperahouse/harmonic

Testing


To Lint the package use:

yarn lint
# Use the --fix option to perform automatic fixes

To run the unit tests (using Jest) use:

yarn test

# Use the -u option to update snapshots if needed
# Run `yarn test:watch` to re-run tests on changes

To run and and store the unit tests for display in storybook use:

yarn test-storybook
# Use the -u option to update snapshots if needed

Development Process


1. Branching Model

  • The (WIP) project lives in the roh-components monorepo
  • When working on WIP, treat the (WIP) directory as your root
  • The WIP development branch is currently WIP
  • The WIP main branch is currently WIP
  • All work should be done on a correctly named feature branch of the format: issueType/ticketNumber-short-description-of-feature, e.g. WIP
  • Always create your feature branch FROM, and submit pull requests TO, the main branch
  • For QA / UAT of a WIP component in isolation: following review you should deploy a preview version to Chromatic straight from your feature branch without merging to development
  • For releasing an NPM snapshot: merge your feature branch into the development branch and publish the NPM snapshot from there

2. Detailed Workflow

Before review:

  • Git pull the latest version of WIP
  • Checkout a new, correctly-named feature branch from WIP
  • Do your work on this feature branch
  • Run: yarn lint
  • Run: yarn test
  • Commit your changes
  • Create a pull request from your feature branch to WIP
  • Add the appropriate reviewers

Before QA / UAT:

After your PR is approved, you have two options:

i. For QA of a component in isolation:

  • Follow the steps above in Deploying the Storybook -> 2. Deploying a preview version remotely
  • Share the generated Chromatic URL with the appropriate people for QA / UAT

ii. For integrated testing of a component in the frontend staging environments:

  • Check out the WIP branch
  • Merge your work in to WIP
  • Follow the steps above under Publishing a New Package Version -> 1. To release a snapshot version
  • Git push the updated WIP branch to remote
  • Finally, in the frontend repo:
  1. Update the package.json to reference the new snapshot version
  2. Run: yarn install
  3. Deploy the frontend to a staging environment

When ready for production:

  • Return to your WIP feature branch
  • Update the WIP version in package.json, incrementing from the last stable release, found in WIP, and following the rules described in the Versioning section
  • Update CHANGELOG.md, adding the new version number and a short description of your changes
  • Run: yarn lint
  • Run: yarn test
  • Run: yarn test-storybook -u
  • Run: yarn build-storybook
  • Git commit, push, and update your PR for final approval
  • Merge your approved PR to WIP
  • Follow the steps in Publishing a New Package Version -> 2. To release a stable version to publish the NPM package
  • Finally, follow the steps in Deploying The Storybook -> 3. To deploy a release version, to update the public WIP Storybook page

Once you have successfully published a new release version, you can open a ticket to update to this version in any of the frontend repos.

Notes


The storybook-static folder

This folder contains all the HTML / JS required to deploy the Storybook as a static site. It's autogenerated whenever the Storybook is built and therefore will show up a lot of merge conflicts when you merge other branches into your feature branch. It is best to leave generating the storybook until the later part of your workflow, but in case you run into conflicts earlier, it's ok to just delete the folder and regenerate using:

yarn build-storybook

For the same reason changes to this folder will cause a lot of big diffs, when looking at a PR, but can mostly be skimmed over unless something looks unusual.


Examples

There is an example implementation in the example folder. Alternatively there are also integration examples in storybook. Make sure to keep these updated so as to showcase the current components available.


Bundle analysis

Calculate the real cost of your library using size-limit with yarn size and visualize it with yarn analyze.