cultureamp-front-end-scripts

The single dependency you need for building a Culture Amp front-end project.

Contributing and finding help

For Culture Amp staff:

• Ask in #front_end_practice if you need help
• Pull requests welcome. You’ll need a code-review to merge but all Culture Amp engineers have permission to approve and merge.

For everyone else

• Pull requests welcome!
• File an issue if you have trouble

WARNING: While this software is open source, its primary purpose is to improve consistency, cross-team collaboration and code quality at Culture Amp. As a result, it’s likely that we will introduce more breaking API changes to this project than you’ll find in its alternatives.

Quick Start

Starting from scratch:

TODO: set up yarn create cultureamp-app.

Adding to an existing repo:

Create a package.json if you don't have one already:

yarn init

Add the scripts dependency:

yarn add cultureamp-front-end-scripts

Add these to your package.json scripts:

"scripts": {
    "start": "cultureamp-front-end-scripts-start",
    "build": "cultureamp-front-end-scripts-build",
    "test": "cultureamp-front-end-scripts-test",
    "lint": "cultureamp-front-end-scripts-lint",
    "flow": "cultureamp-front-end-scripts-flow",
    "format": "cultureamp-front-end-scripts-format"
},

Then run yarn start and open http://localhost:8080/ to build, watch and preview your app.

Commands

• yarn start - start a development server and rebuild as files change
• yarn build - build production assets
• yarn test or yarn test --watch - run jest tests
• yarn lint - run eslint to check code quality on your files
• yarn flow - run flow for type checking
• yarn format - run prettier and eslint --fix on all JS and CSS files

Project structure

Our default project structure looks like this:

├── public
│   └── assets # Generated assets goes here
├── src
│   ├── main.js
│   └── main.test.js
├── package.json
└── yarn.lock

Things to note:

• Client-side source files and assets live inside 'src'.
• Generated assets are created in public/assets. These should be git-ignored.
• Webpack will automatically generate an index file at public/assets/index.html.
• The development server will run from public/, meaning when you load http://localhost:8080/ your assets will be available at http://localhost:8080/assets/.
• You will need to provide your own public/index.html. The easiest solution may be to create a symlink: ln -s public/assets/index.html public/index.html. The index.html in the assets folder is generated by webpack and will include your scripts and stylesheets, even if the generated names include a unique hash.
• None of the configuration files are in the repository by default, they mostly live in node_modules/cultureamp-front-end-scripts/config/.
• Your package.json should have a single cultureamp-front-end-scripts dependency, which in turn loads the various dependencies needed to build a standard Culture Amp front-end with React or Elm, and SASS / PostCSS etc.
• When running the webpack-dev-server (using yarn start), the assets will not be updated on the file-system, the webserver compiles and serves them without updating the files on disk. To update the files in public/assets you will need to run yarn build.

Configuration

Webpack

By default, our webpack configuration will:

• Use src/main.js as an entrypoint
• Use public/assets as an output path
• Append .bundle.js to the names of output files, so you can reference the main.js entrypoint from your HTML with <script src="assets/main.bundle.js">
• Use src/ as a modules folder, so you can import src/components/dropdown.js with import 'components/dropdown';
• Provide appropriate defaults for development (hot reloading etc), and production (minify, extract text etc)
• Provide loaders for:
  • Javascript (babel-loader)
  • Elm (elm-webpack-loader, elm-css-modules-loader, elm-webpack-svg-loader)
  • CSS (sass-loader, postcss-loader, css-loader (with modules), style-loader, Extract Text plugin)
  • SVG (svgo-loader, svg-sprite-loader)
• The configuration required for cultureamp-style-guide

You can provide your own Webpack configuration by supplying a file webpack.config.js.

Rather than creating an entire webpack configuration from scratch, we have created "WebpackConfigMaker" as an API that makes it easier to handle webpack configuration in a composable way using various presets.

// NOTE: this is still a work-in-progress
const WebpackConfigMaker = require('cultureamp-front-end-scripts/webpack-config-maker');
const HtmlWebpackPlugin = require('html-webpack-plugin');

var configMaker = new WebpackConfigMaker();
configMaker.usePreset(
  'cultureamp-front-end-scripts/config/webpack/presets/ca-standard'
);
configMaker.setEntryPoints([
  'app/client/entrypoints/admin.js',
  'app/client/entrypoints/demo.js',
  'app/client/entrypoints/exit.js',
]);
configMaker.setSourceDirectories(['app/client/', 'lib/client/']);
configMaker.addPlugin('my-html-plugin', new HtmlWebpackPlugin());

module.exports = configMaker.generateWebpackConfig();

TODO: provide full documentation for WebpackConfigMaker.

Jest

By default our Jest configuration will:

• Search for test files in src/**/*-test.js. You can optionally keep them in a __tests__ folder if you prefer.
• Preprocess our Babel and Sass/PostCSS files as required
• Use Enzyme, configured for React 16.
• Set automock to false.
• Provide some default shims. See config/jest/utils/setupShim.js
• Provide some custom matchers. See config/jest/utils/customMatchers.js
• Provide an acceptCallsTo() global function for working with mocked methods. See config/jest/utils/acceptCallsTo.js

You can provide your own Jest configuration by supplying a file jest.config.js:

const baseConfig = require('cultureamp-front-end-scripts/config/jest/jest.config.js');
module.exports = {
  ...baseConfig,
  automock: true,
};

ESLint

By default our ESLint configuration will provide a collection of rules curated to Culture Amp's needs. It was originally based on the AirBNB style guide, and expects prettier to provide code formatting.

You can provide your own ESLint configuration by supplying a file eslint.config.js:

const baseConfig = require('cultureamp-front-end-scripts/config/eslint/eslint.config.js');
const OFF = 0;
const WARN = 1;
const ERROR = 2;

module.exports = {
  ...baseConfig,
  rules: {
    ...baseConfig.rules,
    'prefer-const': OFF,
  },
};

Flow

By default our Flow configuration will:

• Check files in src/
• Ignore files in node_modules. You can use flow-typed to correctly type 3rd party libraries.
• Provide stubs for assets and CSS modules imported via Webpack.

The flow configuration lives in .flowconfig, and is copied into your directory the first time you run yarn flow. You can edit the flow configuration by editing this file.

Prettier

We currently don't offer any default prettier configuration, preferring to stick to the defaults.

If you wish to change the settings you can provide your own configuration file.