JavaScript Standards

Documentation and configuration files for QB's JavaScript Coding Standards.

If any JavaScript config references file locations, please copy, don't extend.

Currently we advise copying the contents of our configuration files, and NOT extending them. References within JavaScript files to path.resolve, __dirname, and other constructs concerned with path resolution work best when the file is evaluated when sitting in the root of the project. For example, if you required a file at relative/path/, any references to __dirname within that file would be evaluated to the position of that relative file, and not the project root.

View our Coding Styleguide:

• JavaScript
• React

Using Configuration Files

Assumptions regarding project structure project structure:

src/
dist/

Installing Dependencies

Install this package via npm:

npm i @quantumblack/javascript-standards --save-dev`.

You'll need to request access to this repo while it's on QB's private bitbucket.

ESLint

We use Airbnb's ESLint config extended with a number of our preferences.

Install ESLint

npm i eslint --save-dev

Install Dependencies

(
  export PKG=eslint-config-airbnb;
  npm info "$PKG@latest" peerDependencies --json | command sed 's/[\{\},]//g ; s/: /@/g' | xargs npm install --save-dev "$PKG@latest" eslint-plugin-require-jsdoc
)

Create the configuration file

Create a file called .eslintrc.js in your project. This is usually in the root of your source folder, but it can be anywhere (remember to update the relative path accordingly).

Your new file should extend QB's ESLint config. In this case, we are using config specific to a React codebase:

var baseConfig = require('@quantumblack/javascript-standards/config/react/eslint/.eslintrc-source');

module.exports = baseConfig;

Config types

• .eslintrc-source for JavaScript source code
• .eslintrc-test for JavaScript tests - TODO
• .eslintrc-config for linting config files! - TODO

Stylelint

Enforces our rules for defining CSS syntax.

Install

npm i stylelint --save-dev

Install Dependencies

npm i stylelint-order --save-dev

Create a stylelint config file called stylelint.config.js with the following contents:

var baseConfig = require('@quantumblack/javascript-standards/config/stylelint/stylelint.config.js');

// you can extend or modify rules here

module.exports = baseConfig;

See stylelint configuration) where you extend our rules and overrides as required:

Webpack

Install

npm i webpack --save-dev

Our configuration is designed to work with Webpack 2. Please ensure this version is installed. If required, see the Migrating Guide from v1 to v2.

Install Dependencies

npm i babel-plugin-webpack-loaders webpack-hot-middleware css-loader style-loader babel-loader svg-react-loader babel-plugin-transform-react-jsx --save-dev

Customizing Configuration

Create files named webpack.dev.config.js and webpack.build.config.js in your project.

We recommend copying the contents of our webpack config files (found in /config/react/webpack/) to your project, as extending them can cause issues relating to path resolution. For example, __dirname will evaluate to the location at which the file is located, and you would normally assume this to be the root of the project within webpack config.

Development and Build Config

As our webpack config filenames have been slightly customised, you'll need to pass the filename in within the webpack arguments in your package.json scripts:

"scripts": {
    "build": "webpack -p --config webpack.build.config",
    "build:dev": "webpack -d --config webpack.dev.config"
}

Our repo contains configuration for a dev webpack config to use with webpack-dev-server for hot reloading, which includes warnings and sourcemaps enabled.

Babel

Install

If you want to use Babel from the CLI you can install babel-cli or if you want to use the Node API you can install babel-core.

npm i babel-core --save-dev

Install Dependencies

The Babel presets below enable lots of plugins.

npm i babel-loader babel-plugin-lodash babel-plugin-transform-object-rest-spread babel-plugin-webpack-loaders babel-preset-env babel-preset-react babel-register --save-dev

Create a file called .babelrc in your project.

The file should extend QB's Babel config. In this case, we are using config specific to a React codebase:

{
  "extends": "./node_modules/@quantumblack/javascript-standards/config/react/babel/.babelrc"
}

Extending with additional plugins

Once you extend our base .babelrc, you can enable any additional plugins by installing them as a dev dependency, and adding to the plugins property.

Here is our extended version from a project using lodash and AVA:

{
  "extends": "./node_modules/@quantumblack/javascript-standards/config/react/babel/.babelrc",
  "plugins": [
    "lodash",
    "transform-es2015-modules-commonjs",
    "transform-es2015-destructuring",
    "transform-object-rest-spread"
  ],
  "env": {
    "AVA": {
      "plugins": [
        ["babel-plugin-webpack-loaders", {
          "config": "${CONFIG}",
          "verbose": true
        }]
      ]
    }
  }
}

AVA

We are able to test a Webpack project via AVA with a custom Webpack config file.

You may need to use different loaders, or stub certain endpoints out in your test environment.

Install

npm i ava --save-dev

Install Dependencies

• Babel register ensures require hook will bind itself to node's require and automatically compile files on the fly.
• Ignore styles ensures css/style imports are ignored when running in Node.

npm i babel-register ignore-styles babel-plugin-webpack-loaders babel-plugin-transform-object-assign browser-env --save-dev

Extending Base Configuration

Create a file called webpack.ava.config.js in your project.

We recommend copying the contents of /config/ava/webpack.ava.config.js to this file.

Mocking the browser environment.

We want to ensure things in the browser scope like document, window, etc, exist in our test environment. Create a file test/helpers/setup-browser-env.js with the following contents:

import browserEnv from 'browser-env';
browserEnv();

Add a command to your scripts property and add AVA configuration inside your package.json. You probably want to only run Unit Tests if your lint task succeeds.

"scripts": {
  "ava": "CONFIG=$(pwd)/webpack.ava.config.js NODE_ENV=AVA BABEL_DISABLE_CACHE=1 ava",
  "eslint": "eslint src/*.js src/**/*.js src/**/*.jsx",
  "test": "npm run eslint && npm run ava"
},
"ava": {
  "files": [
    "test/**/*.js",
    "src/**/*.test.js"
  ],
  "verbose": true,
  "babel": "inherit",
  "require": [
    "babel-register",
    "ignore-styles",
    "./test/helpers/setup-browser-env.js"
  ]
},

PostCSS

Install

npm i autoprefixer postcss-loader postcss-cssnext --save-dev

Configuration

This is configured in our webpack config via postcss-loader.

React Styleguidist

A React style guide generator. This package includes default configuration which makes a number of assumptions about your project structure, all of which can be overridden.

Install

npm i react-styleguidist@beta --save-dev

Webpack 2 support is only available in the beta release.

Install Dependencies

• Lodash is used in our configuration file.

npm i lodash --save-dev

Extending Base Configuration

Create a file called styleguide.config.js in your project root.

Copy the contents of /config/react-styleguidist/styleguide.config.js to it, and modify as required to match your project requirements.

Editor Config Files

Config files used to configure your IDE across a team are stored in config/editor. Our Editor Config ensures white space is formatted consistently according to a simple set of rules. You may need to install an EditorConfig plugin in your IDE to ensure the rules are implemented automatically.

Create a file called .editorconfig in your project root, with the following contents:

# EditorConfig is awesome: http://EditorConfig.org

# top-most EditorConfig file
root = true

# Unix-style newlines with a newline ending every file
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true

# 2 space indentation
[**.*]
indent_style = space
indent_size = 2

[**.md]
indent_style = space
indent_size = 4

This file can't be extended, and must be copied. For reference, the file is stored in this repo at /config/editor/.editorconfig.