Frontend Toolkit Utilities

Shared front-end utility packages published via NPM

This repository contains utilities and helpers for interacting with the front-end component toolkits. Each package should have its own folder in ./packages, which result in it being published to NPM using the @springernature scope.

• Installation
  • Using the correct node & npm versions
  • Installing dependencies
• Writing a package
  • Package structure
  • Naming
    • package.json
• NPM Scripts
• Testing
• Linting
• Continuous integration
  • Publishing
• License

Installation

This 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.

Installing dependencies

To install dependencies:

$ npm install

We hope to switch to npm ci when Node 10 is in LTS.

Writing a package

All packages are validated on our CI server (Travis) to ensure they conform to certain naming conventions, and that certain required files are present. The validation is configurable in the package-manager.json file. The current configuration is described below.

You can validate all the packages by running npm run validate from within the project on the command line, or test only your package by running npm run validate -- -p util-name-of-package.

You can auto-generate a new package with the correct configuration by running npm run create from within the project on the command line. This will generate a folder in the packages directory with the correct files and folders.

Package structure

frontend-util-toolkit
  └── packages
    ├── util-name-of-package
      └── {folders}
      └── 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
• In addition to these files, you can have any number of folders, containing and files and sub-folders

Naming

Packages should use the util prefix for naming. The package folder should use the convention util-name-of-package, where name-of-package uses only lowercase alphanumeric characters and hyphens.

package.json

Packages in frontend-toolkit-utilities are scoped to the springernature organisation. Packages are exported using the naming convention @springernature/util-name-of-package.

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

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 create

  Run the create script from the frontend package manager.

• npm run lint

  Run code linting for Javascript.

• 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.

Testing

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

To run all the tests use npm run test from within the project on the command line. The run an individual test use npm run 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 Travis CI and builds are run on all Pull Requests. On each build travis 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 in Travis, which detects a new version in a packages package.json file, and a corresponding entry in the HISTORY.md file.

License

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