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

Frontend Component Toolkits for the Elements Design System

• Installation
  • Using the correct node & npm versions
  • Using the correct sass version
  • Installing dependencies
• What is a toolkit?
• Writing a package
  • Frontend Package Manager
  • Package structure
  • Naming
    • package.json
  • SASS
  • Javascript
• NPM Scripts
  • Comparing component versions
• Testing
• Linting
• Continuous integration
  • Publishing
• License

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:

• README.md, HISTORY.md, package.json are the only files allowed at the top level, they are all required
• The folders scss, js, view, img, fonts, __tests__ are the only folders that are allowed at the top level, they are optional
• Within these folders you can have any number of sub-folders, but there are restrictions on the file types allowed

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:

• Take the form name-of-package--variable-name for variables
• Take the form name-of-package for single mixins/functions
• Take the form name-of-package--some-name when there are multiple mixins/functions
• Use only lowercase alphanumeric characters and hyphens

// 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:

• npm run bootstrap:local

  Bootstrap all package dependencies for running tests and using components locally. This is run automatically on CI.

• npm run build

  Run the lint, test, and validate scripts before pushing.

• npm run build:ci

  As above, but run on CI. Do not use locally.

• npm run context

  This is run as part of the boostrap commands and installs the correct version of brand-context in each package's dependencies, for testing and validation. You can also run this with the -n flag to specify a package name. This will install the brand-context for that package only e.g. npm run context -- -n name-of-package

• npm run create

  Run the create script from the frontend package manager.

• npm run demo -- -p name-of-package

  Create a static example file from a demo folder. Part of frontend package manager. For example npm run demo -- -p global-autocomplete.

• npm run lint

  Run code linting for Javascript and SASS.

• npm run lint:sass

  Run code linting for SASS.

• npm run lint:js

  Run code linting for Javascript.

• npm run publish

  Run the publish script from the frontend package manager.

• npm run test

  Run unit tests via Jest.

• npm run test:ci

  Run unit tests on CI. Do not use locally.

• npm run validate

  Run the validate script from the frontend package manager.

• npm run validate:global

  Run the validate script, filtered by the global toolkit.

• npm run validate:nature

  Run the validate script, filtered by the nature toolkit.

• npm run validate:springer

  Run the validate script, filtered by the springer toolkit.

• npm run validate:springernature

  Run the validate script, filtered by the springernature toolkit.

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 [email protected]

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.

• To run all the tests use npm run test
• To run all the tests for a particular package use npm test <name-of-package>
• To run an individual test use npm test <name-of-test-file>

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