@financial-times/dotcom-page-kit-cli NPM

@financial-times/dotcom-page-kit-cli

The Page Kit CLI provides a suite of actions to assemble modern Web projects. The CLI can be extended via plugins to provide additional functionality.

Getting started

This package is compatible with Node 8+ and is distributed on npm.

npm install --save-dev @financial-times/dotcom-page-kit-cli

Configuration is provided to the CLI by a page-kit.config.js file placed in your project root (next to package.json). Create this file now, including the fields defined below:

module.exports = {
  plugins: [],
  settings: {}
}

The plugins property is used to supply the plugins that should be loaded by the Page Kit CLI. These plugins should be installed in your project as development dependencies. Plugins by convention are namespaced with dotcom-build-.

The settings property is used to provide specific configuration for the individual CLI actions. These settings are covered below (see actions.)

To view the available actions and global options provided by the CLI, run the page-kit command with the --help flag:

page-kit --help

Actions

`build`

This action can be used to assemble the static assets for your application using Webpack. By default this action includes only a barebones Webpack configuration to bundle JavaScript source code but this can be extended via plugins to add additional functionality.

The action also creates a manifest.json (the file name is default but can be configured). It includes the hashed output names for the generated .js and .css chunks

Options

Entry points

The path for the entry point into your source code can be provided via the --entryFile CLI flag or via the configuration file. The default entry point is "src/index.js". Multiple entry points can only be defined using the configuration file. See the Webpack entry documentation for more information about entry points. The configuration file will take precedence over the CLI flag.

Usage via CLI flag:

page-kit build --entryFile ./path/to/entry.js

Usage via configuration file:

module.exports = {
  plugins: [...],
  settings: {
    build: {
      entry: {
        main: './path/to/entry.js'
      }
    }
  }
}

Output path

The generated output can be directed to a destination directory using the --outputPath CLI flag or via the configuration file. The default destination is "./dist". The configuration file will take precedence over the CLI flag.

Usage via CLI flag:

page-kit build --outputPath ./path/to/dist

Usage via configuration file:

module.exports = {
  plugins: [...],
  settings: {
    build: {
      outputPath: './path/to/dist'
    }
  }
}

Files will be created using the pattern [name].js in development mode and [name].[contenthash].js in production mode.

Manifest file name

The generated manifest file details the hashed output names for the emitted .js and .css chunks. The file name can be changed via the configuration file. The default file name is "manifest.json".

Usage via configuration file:

module.exports = {
  plugins: [...],
  settings: {
    build: {
      manifestFileName: 'asset-hashes.json'
    }
  }
}

Targets

A browserslist-compatible query that describes the environments you support / target for your project. It defaults to: last 2 Chrome versions, ie 11, Safari >= 9.1, ff ESR, last 2 Edge versions.

Usage via configuration file:

module.exports = {
  plugins: [...],
  settings: {
    build: {
      targets: {
        chrome: '58',
        ie: '11'
      }
    }
  }
}

Development and production modes

In production mode the generated output will be optimised, file names hashed, and full source maps, gzip and brotli compressed assets generated. Production mode is the default.

To enable development mode you can use the --development CLI flag. This will disable several optimisations in favour of providing faster builds and rebuilds. See the Webpack mode documentation for further information about modes.

page-kit build --development

Watch mode

For convenience the build action can watch source files and trigger a rebuild whenever they change. To enable watch mode use the --watch CLI flag.

page-kit build --watch

Hooks

This plugin exposes the following hooks as extension points. They are available as constants on the exported hooks object.

import { hooks } from '@financial-times/dotcom-page-kit-cli'

Please note: The hooks below are listed in the order they will be executed.

`WEBPACK_CLEAN_PLUGIN_OPTIONS`

Configuration options for the clean plugin.

`WEBPACK_COMPRESSION_PLUGIN_OPTIONS`

Configuration options for the compression plugin

`WEBPACK_BROTLI_PLUGIN_OPTIONS`

Configuration options for the brotli compression plugin

`WEBPACK_MANIFEST_PLUGIN_OPTIONS`

Configuration options for the assets manifest plugin which provides the compilation entrypoints for each bundle by asset type e.g. scripts and styles.