[!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 Component Toolkits for the Elements Design System
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.
node
& npm
versionsEnsure 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.
sass
versionThe 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.
Lerna needs a little help beyond the usual npm
install - run npm run bootstrap:local
before you try anything else.
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.
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.
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.
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 requiredscss
, js
, view
, img
, fonts
, __tests__
are the only folders that are allowed at the top level, they are optionalsub-folders
, but there are restrictions on the file types allowedPackages 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",
}
When writing CSS you should follow the guidelines in the Springer Nature Frontend Playbook, and in addition all SASS mixins/functions/variables should:
name-of-package--variable-name
for variablesname-of-package
for single mixins/functionsname-of-package--some-name
when there are multiple mixins/functions// 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 () {}
When writing Javascript you should follow the guidelines in the Springer Nature Frontend Playbook
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.
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
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
.
npm run test
npm test <name-of-package>
npm test <name-of-test-file>
NOTE: Make sure that you bootstrap all package dependencies before running tests using
npm run bootstrap:local
.
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.
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.
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.
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