University of Birmingham Component Library

This is the frontend component library for the University of Birmingham website built using Storybook 7 and SASS.

Contents

• Installation and setup
• Working locally on the project
• Creating Components
• Deploying changes to the public Storybook
• Publishing changes to the NPMJS package library
• Using the NPMJS package library

Installation and setup

Compatibility

• Node: ^18.18.0
• React: ^17.0.2

Setting up the project locally

1. Clone the repo from Github: git clone [email protected]:uob-itservices/component-library.git
2. Install NPM Node Modules by running npm install from the project root

Working locally on the project

Run npm run storybook from the project root. This will run a new instance of Storybook that can be accessed from localhost:6006.

Changes made locally are automatically compiled and the browser instance of Storybook will automaticaly refresh, hot-loading changes very quickly where possible.

Creating components

Components should always be created within the src/components folder.

Naming component folders

You can create a new folder within src/components that is based on the chosen name for your component. The format of this folder name, react component and story should always be PascalCase i.e. MyNewComponent. SASS files should always be camelCase i.e. myNewComponent

Component file structure

Within the component folder you must create the following 3 files:

ComponentName
 |_ {ComponentName}.tsx
 |_ {ComponentName}.stories.ts
 |_ {componentName}.scss

{ComponentName}.tsx

This file is where the Component Structure is defined.

{ComponentName}.stories.ts

This file allows developers to pass in mockup content to the component that will render within Storybook. More information is available in the Storybook docs Storybook JS - Defining Stories

{componentName}.scss

This is where component styling is defined using SASS/CSS.

Deploying project changes to the public Storybook

The visible Storybook for sharing changes is private and is accessed at https://stunning-invention-1w42em5.pages.github.io/ you will need to be a member of the uob-itservices GitHub organisation and have access to the repository.

This is automatically deployed and built when changes are pushed to the develop branch of the GitHub repository.

Linting Before Committing

Before pushing a new commit to this component-library, please ensure that you run the following ES Lint command in your terminal:

npm run lint

This will highlight any linting issues that may arise when making file changes that will need to be fixed.

To adhere to the commit message best practice commitlint is used. More information on commit message linting can be found here at https://github.com/conventional-changelog/commitlint/#what-is-commitlint

Publishing changes to the NPMJS package library

The repository will need publishing to the NPMJS package library https://www.npmjs.com/package/@uob-web-and-digital/component-library before it can be used in the UoB website.

This is a private package so a read-only NPM access token will need be created in order to install the package.

When the library in ready for a new release of the NPM package, you will need to increase the version number in the package.json and run a npm install to ensure the project gets updated with this version. After this you will need to create a pull request into the develop branch and then another pull request from the develop branch into main

As this is a manual process, ensure that the main branch of the repository is always in sync with the currently published package.

Releasing to the NPM registry are managed by GitHub Actions. You will need to create a new release and use the new release version as the tag. Once the release is published a GitHub Action will automatically run all the steps to publish the package on NPM.

Using the component package library

In order to use the package you must have a NPM Access Token with read-only access to @uob-web-and-digital/component-library.

To install the package run npm install @uob-web-and-digital/component-library.

After installation you will need to add the following to your layout file;

import '@uob-web-and-digital/component-library/dist/main.css';

Base64 fonts

Fonts are base64 encoded so they are not hosted on a third party.

To encode fonts to base64 you can run;

base64 -i Font.woff2 -o Font64txt