springernature / frontend-toolkits

Frontend Component Toolkits for the Elements Design System
MIT License
13 stars 3 forks source link

[!IMPORTANT] There is a newer version of the Elements Design System
Please make sure you are using the correct one
If you are unsure speak to the Design System Team

Frontend Toolkits

Build Status MIT licensed Node version SASS version

Frontend Component Toolkits for the Elements Design System

Installation

The toolkits repository functions as a monorepo, and uses Lerna to manage dependencies within it's packages.

To try and ensure that installs are consistent, we all use the same version of node & npm when working in the repo.

Using the correct node & npm versions

Ensure you have nvm installed, then in the root of the repo run nvm use. This will read the version of node (and therefore npm) to use from the .nvmrc and ensure you are using the correct versions.

Using the correct sass version

The components found within the toolkits are validated using the sass package on NPM. You should use the same version within your application (currently 1.47.0) build process.

Get bootstrapped for local development

Lerna needs a little help beyond the usual npm install - run npm run bootstrap:local before you try anything else.

Installing dependencies

To install dependencies:

$ npm ci

We install from the package-lock.json file to ensure that all tests, linting, and validation are run under the same conditions.

What is a toolkit?

Toolkits are collections of front-end packages for use across the Springer Nature ecosystem. We provide toolkits for each of our major brands within Springer Nature, as well as a global toolkit containing packages for use across the whole of Springer Nature.

Packages are bundles of front-end assets (HTML, CSS, JS, images, tests etc...) that are published via NPM and allow us to share robust, tested, user-validated solutions to front-end problems across the business. This helps us to reduce the duplication of effort, provide a platform for starting up greenfield projects, and standardise the presentation of our brands online.

Writing a package

All packages are validated on GitHub Actions CI to ensure they conform to certain naming conventions, file/folder structure, and that certain required files are present.

The validation is configurable in the package-manager.json files that can be found in the repository root (this config is shared across all toolkits), and in the root folder for each toolkit.

You can validate all the packages by running npm run validate from within the project on the command line.

frontend-package-manager

The creation, validation and publication of packages is controlled via the Frontend Package Manager.

The README for that repository provides information on the package creation wizard, which can be run with npm run create, as well as detailing additional options for package validation, as well how packages are automatically published via GitHub Actions.

Package structure

name-of-toolkit
  └── packages
    ├── prefix-name-of-package
      └── scss
        └── **/*.{scss,css,md}
      └── js
        └── **/*.{js,json,md}
      └── view
        └── **/*.{html,dust,md}
      └── img
        └── **/*.{jpg,gif,png,svg,md}
      └── fonts
        └── **/*.{woff,woff2,eot,svg,ttf,json}
      └── __tests__
        └── **/*.{js,json}
      └── HISTORY.md
      └── package.json
      └── README.md

The files and folders detailed here are subject to the following validation rules:

Naming

Packages should use the prefix defined within the individual toolkit configuration. The package folder should use the convention <prefix>-name-of-package, where name-of-package uses only lowercase alphanumeric characters and hyphens.

package.json

Packages in frontend-toolkits are scoped to the springernature organisation. Packages are exported using the naming convention @springernature/<prefix>-name-of-package. For example:

{
  "name": "@springernature/global-name-of-package",
}

SASS

When writing CSS you should follow the guidelines in the Springer Nature Frontend Playbook, and in addition all SASS mixins/functions/variables should:

// variables
$name-of-package--variable-name
$name-of-package--other-name

// mixins
@mixin name-of-package () {}
@mixin name-of-package--some-name () {}

// functions
@function name-of-package () {}
@function name-of-package--some-name () {}

Javascript

When writing Javascript you should follow the guidelines in the Springer Nature Frontend Playbook

NPM Scripts

The following script commands are available:

Comparing component versions

In addition to the scripts above you can also use the util-package-diff tool to compare two versions of the same component (one from NPM, and the current local version). This is run via npx from the repository root, as in the example below

$ npx @springernature/util-package-diff -p global-corporate-footer@4.0.0

Testing

Tests for your package should be written in your packages/<prefix>-name-of-package/__tests_ folder. For example, unit tests for global-name-of-package should live in packages/global-name-of-package/__tests__/unit/*.js.

NOTE: Make sure that you bootstrap all package dependencies before running tests using npm run bootstrap:local.

Linting

Javascript linting is enforced using the Springer Nature Eslint config across all packages. Run the linter using npm run lint from within the project on the command line.

Continuous integration

This repository uses GitHub Actions and builds are run on all Pull Requests. On each build GitHub will boostrap all of the package dependencies using Lerna Boostrap, before running linting and all tests.

Publishing

To publish a new package please follow the contributing guidelines. Publishing to NPM is done automatically via GitHub Actions, which detects a new version in a packages package.json file, and a corresponding entry in the HISTORY.md file.

License

The frontend-toolkits repository is licensed under the MIT License. All packages within this repository are licensed under the MIT License. Copyright © 2020, Springer Nature