dotcom-tool-kit: A TypeScript repository from Financial Times

Tool Kit is modern developer tooling for FT.com repositories. It's fully modular, allowing repos that need different tooling to install separate plugins that work consistently together.

Tool Kit only handles common tooling use cases that are required for most apps to work. Tool Kit sets up the minimal configuration for third party packages to run.

Your repo does not need to use Tool Kit for all of its tooling, and tooling not supported by Tool Kit can be configured directly in your repo.

Installing Tool Kit

Interactive installation & migration

For an empty repository (containing at least a valid package.json), or to migrate an existing repo from n-gage, you can run the interactive Tool Kit init script:

npm init @dotcom-tool-kit@latest

See the migration guide for a full explanation of what this script does.

Installing and configuring manually

Install the core of Tool Kit as a devDependency:

npm install --save-dev dotcom-tool-kit

On its own, Tool Kit doesn't do anything, so you'll need to install some plugins to give it functionality. For example, if you want to run Jest tests with npm run test via Tool Kit, you can install the jest and npm plugins:

npm install --save-dev @dotcom-tool-kit/npm @dotcom-tool-kit/jest

Add a .toolkitrc.yml to the root of your repository to include these plugins:

plugins:
  - '@dotcom-tool-kit/npm'
  - '@dotcom-tool-kit/jest'

Every time you change your .toolkitrc.yml, e.g. adding or removing a plugin or configuring a hook, you should tell Tool Kit to install configuration files in your repository:

npx dotcom-tool-kit --install

Running Tool Kit

You don't run Tool Kit directly; you run plugin tasks using things like npm scripts, automatically configured in your package.json by Tool Kit. With the npm and jest plugins installed, Jest tests are run with the npm test script:

npm run test

At any time, you can run --help to see what plugins you have installed, what configuration files they're managing, and what tasks you can run with them:

npx dotcom-tool-kit --help

Core concepts

Integration with tooling is grouped into modular Plugins that are installed separately.
Tool Kit abstracts running other tooling with Tasks, written in Typescript.
When running Tool Kit, you run Commands, which you (or a plugin) configure to run one or more Tasks.
Hooks manage configuration files in your repository to run Commands from tooling such as npm scripts or CircleCI jobs.

The concepts document has more details about how these work together.

Configuring Tool Kit

The .toolkitrc.yml file in your repo determines everything about how Tool Kit runs in that repo. It controls what plugins are included (which determine what hooks and tasks are available), gives you fine-grained control over what tasks are running on what commands, and lets you provide options to plugins, tasks, and hooks.

An example .toolkitrc.yml might look like:

plugins:
  # provides the test:local hooks
  - '@dotcom-tool-kit/npm'
  # provides the Jest task
  - '@dotcom-tool-kit/jest'
  # provides the Eslint task
  - '@dotcom-tool-kit/eslint'

commands:
  # run both Jest and ESlint when running `npm run test`
  # required to resolve the conflict between their defaults
  test:local:
    - Eslint
    - Jest
  # options for tasks can be set on a per-command basis
  test:e2e:
    - Jest
        configFile: jest.e2e.config.js

options:
  # ESlint plugin needs to know which files to run ESlint on.
  # there's a default setting, but your repo might need something else
  tasks:
    Eslint
      files:
        - server/**/*.js
  # instruct the hook that manages your repo's `package.json` to
  # install a command to run `test:e2e` as an npm script
  hooks:
    - PackageJson:
        scripts:
          test-e2e: 'test:e2e'

The options available for each plugin are documented in their readmes. If the tooling that a plugin is using has its own method of configuration (like .eslintrc, .babelrc, jest.config.js, webpack.config.js), Tool Kit options aren't used for that; they're not merged with that config and don't replace it. Tool Kit options are only for things that need to be known to run the tooling in the first place, or where tooling doesn't provide its own configuration.

Financial-Times/dotcom-tool-kit