Create Frontend

This toolkit generates your project's frontend build system. It uses Webpack under the hood.

Features

• JS (Babel, Eslint, Core-JS, Flow, JSX). Can import relative to project root: import x from 'client/js/y'
• SCSS with autoprefixer, normalize.css. Images can be imported relative to project root with tilde: background-image: url('~client/images/logo.svg')
• Hot reload for development
• Works with zero configuration, but customization is possible if needed
• Usable with any backend.
• .html files are built from /client/html by default, with assets automatically linked.

Usage

1. In Bash, navigate into your project directory
2. Type npx @optimistdigital/create-frontend and follow the instructions. You may also specify flags:
   • --template=react - Generates a React boilerplate
   • --template=universal-react - Generates a React boilerplate that renders on client and server (using Node.js). Documentation here
   • -y - Skips user confirmation (assume yes)

CLI

• npm run dev - Start a webpack server for development
• npm run build - Build assets for production
• npm run build:debug - Build assets with debug logs. In JS, __DEBUG__ will be transformed to true

There are also flags to customize the dev environment:

• npm run dev -- --webpackPort=8000 - Custom port for dev server
• npm run dev -- --webpackDomain=localhost - Custom domain for dev server
• npm run dev -- --protocol=https - Run the dev server with https

Configuration

Configuration can be done in two places:

• In your package.json under the create-frontend property. Since this is a JSON file, not all configuration is going to be possible.

{
    "create-frontend": { "publicDirectory": "public" }
}

• In the create-frontend.conf.js file that you can create in your project root. Use this if you need more complex expressions or JSON isn't enough.

module.exports = { "publicDirectory": "public" }

Here are all the options (default in parens):

• publicDirectory (public) - Project's public root. Relative to project root.
• buildPath (build) - Where the build files will go. Relative to the public directory.
• hashFileNames (true) - Whether or not filenames should be hashed in production (e.g app-503dcc37.js). An asset-manifest.json file will be generated either way.
• htmlPath (client/html) - Html files from this directory will be built into the public directory with html-webpack-plugin.
• htmlOptions ({}) - Options that will get passed to html-webpack-plugin
• entryPoints - Object/string/array that contains the entry points for your application. Relative to project root. Default:

  {
      app: 'client/js/entry.js',
  }

• appendPlugins - Function that returns an array of Webpack plugins. Appended to the end of the plugins array.
• prependRules - Function that returns an array of Webpack rules. The first one to match will be used (oneOf). These take precedence over default rules - if your custom rule matches, the default ones will not be used.
• editConfig - Function that can be used to return a customized version of the Webpack config. First argument is the webpack config that is generated by Create Frontend. Use this as an escape hatch to customize the Webpack config directly.
• editDevServerConfig - Function that can be used to return a customized version of the Webpack Dev Server config.

The opts parameter contains the following object: { IS_PRODUCTION: boolean, paths: Object, config: Object }

Configuring Babel

If you need to make changes to the babel config, you can extend our babel preset by making a configuration file in your project root:

• In babel.config.js

const config = require('@optimistdigital/create-frontend/babel-config');
/* Make adjustments */
module.exports = config;

• In .babelrc

{
    "extends": "@optimistdigital/create-frontend/babel-config.js"
}

Using hot module replacement

Hot module replacement is enabled for the app, however you must choose manually what you want to update when changes are made. To do this, go into your entry.js file and uncomment the relevant code.

Updating

To update the local version of the toolkit, type npm install @optimistdigital/create-frontend. Please look at the changelog to see if there are any breaking changes.

If you're not using npx, remember to update the global version of the library as well.