Run dev server

Starts a browsersync proxy of the same server, typically on localhost:3000 (actual port will be shown when starting the command). This is used to live inject the styles (via browsersync) and JS (via webpack hot reload)

Building for production

Compiles files for production to your destination directory. JS files are built with webpack 3 with standard production optimizations (uglfiy, etc.). CSS is run through CSSNano.

If rev is set to true in your task-config.js file, filenames will be hashed (file.css -> file-a8908d9io20.css) so your server may cache them indefinitely. A rev-manifest.json file is output to the root of your dest directory (public by default), and maps original filenames to hashed ones. Static files are automatically updated to reference the hashed filenames. A custom Jekyl plugin (rev) is used to to read the manifest file and replace references to static asset filenames via a liquid filter.

Secondary tasks

Linting

Linting (via yarn lint) is enforced on a pre-push hook via Husky. This can be disabled / modified via .huskyrc.

JS files are also linted at Babel compile time via eslint-friendly-formatter.

The following tasks are available for your manual linting requirements:

yarn lint-styles
yarn lint-js
yarn lint # all the things

Building styleguide as static HTML

yarn generate-styleguide

This builds the Fractal styleguide to static HTML and outputs it to a component-library/ directory (gitignored) in the project root.

Check HTML links (WIP)

Because we're currently deploying the site to a subdirectory, it also requires some temporary changes to _config.yml or it will throw a large number of false positives:

Required:

comment out the url and baseurl keys. This is required so that Jekyll writes out links in a way that html-proofer can resolve. This can probably be worked around using html-proofer's url_swap feature, but we have not currently got that working correctly.

Optional:

Change env to development (not required but will disable html minification making the build much faster)

Release and deployment

A release script is included for convenience. Use a semver compliant version.

Blendid

You may override the default configuration via editing path-config.json and task-config.js in the build/ directory. See the separate README.md and inline documentaton in that directory for full options available.

Contributions application

The contributions/ directory contains a small Sinatra application that takes form submissions and turns them into issues / PRs on the GitHub repo via the GH api. For full details of this component of the project see contributions/README.md.

Hacks

The jekyll-git_metadata is monkey patched in src/_plugins/git_metadata.rb to handle the fact that we're running Jekyll in a subdirectory of the project

Other useful bits

Regenerate the table of content for this README.md (or any other) by running ./scripts/gh-md-toc README.md and pasting in the output