origami-build-tools

Standardised build tools for Origami modules and products developed based on these modules (with CSS only build option).

If you have any issues with OBT, please check out troubleshooting guide before raising an issue.

• Installation
• Usage
• Commands
• Migration guide
• Licence

Installation

1. Install these dependencies:

   • node.js

2. Install the build tools globally:

    npm install cnk-digital-solutions/origami-build-tools
   

   or if using Docker:

    docker-compose run --rm origami npm install cnk-digital-solutions/origami-build-tools
   

Usage

Usage
	$ obt <command> [<options>]

Commands
	build, b      Build CSS and JS in current directory
	buildsass, s  Build CSS only in current directory
	demo, d       Build demos into the demos directory
	init          Initialise a new component with a boilerplate folder structure
	install, i    Install npm and bower dependencies required to build modules
	test, t       Run Origami specification tests and component specific tests
	verify, v     Check folder and code structure follows Origami specification

Options
	-h, --help                 Print out this message
	--watch                    Re-run every time a file changes
	--run-server               Build demos locally and runs a server
	--js=<path>                Main JavaScript file (default: ./src/main.js)
	--sass=<path>              Main Sass file (default: ./src/main.scss)
	--build-js=<file>          Compiled JavaScript file (default: main.js)
	--build-css=<file>         Compiled CSS file (default: main.css)
	--build-folder=<dir>       Compiled assets directory (default: ./build/)
	-v, --version              Print out version of origami-build-tools
	--production               Compiled assets will be minified for production systems
	--browserstack             Run tests using Browserstack instead of Chrome Stable
	--standalone               Create a named export for the built JavaScript
	--demo-filter=<demo-name>  Build a specific demo. E.G. --demo-filter=pa11y to build only the pa11y.html demo.
	--brand=<brand-name>       Build SCSS for a given brand. E.G. --brand=internal to build the component for the internal brand.
	--suppress-errors          Do not error if no demos are found when using the --demo-filter option.
	--debug                    Keep the test runner open to enable debugging in any browser.
	--verbose                  Output sass warnings with backtraces.

Developing products

Build CSS and JavaScript bundles in the build directory:

Local:

origami-build-tools build

Docker:

docker-compose run --rm origami origami-build-tools build

Developing modules locally

Build and browse the demos (typically: http://localhost:8080/demos/local/), automatically re-build the module's demos and assets every time a file changes:

origami-build-tools demo --runServer --watch

Commands

install or i

Install npm and bower dependencies required to build modules.

build or b

Build CSS and JavaScript bundles (typically, from main.js and main.css).

It comes with support for things like:

• Babel so you can use ES2017 features in your modules and products
• autoprefixer so you don't have to worry about writing browser prefixes in your Sass

Set the main JavaScript file with the --js option. (default: ./src/main.js) Set the main Sass file with the --sass option. (default: ./src/main.scss) Set the name of the built JS file with the --build-js option. (default: main.js) Set the name of the built CSS file with the --build-css option. (default: main.css) Set the name of the folder to store the built CSS and JS with the --build-folder option. (default: ./build/) Build the files for production environments with the --production option. (default: off)

If building a library use the --standalone option to specify the name you want the library to be accessed with. (default: off)

buildsass or s

Build CSS (typically, from base.css).

It comes with support for things like:

• autoprefixer so you don't have to worry about writing browser prefixes in your Sass

Set the main Sass file with the --sass option. (default: ./src/main.scss) Set the name of the built CSS file with the --build-css option. (default: main.css) Set the name of the folder to store the built CSS with the --build-folder option. (default: ./build/) Build the files for production environments with the --production option. (default: off)

If building a library use the --standalone option to specify the name you want the library to be accessed with. (default: off)

CLI examples:

Local:

./node_modules/.bin/obt buildsass --sass=./private/sass/base.scss --buildCss=bundle.css --buildFolder=static/css

Docker:

docker-compose run --rm origami /app/node_modules/.bin/obt buildsass --sass=./private/sass/base.scss --buildCss=bundle.css --buildFolder=static/css

Building locally when origami-build-tools is installed in a Docker container:

Rebuild node-sass:

npm rebuild node-sass

Then build:

./node_modules/.bin/obt buildsass --sass=./private/sass/base.scss --buildCss=bundle.css --buildFolder=static	

demo or d

Build demos found in the demo config file.

Build a specific demo with the --demo-filter option.

• If --production is set, demos are built to pull assets through the Origami Build Service.

Non-production demos consist of HTML, CSS and JS (if Sass & JS exists), and are created in demos/local/. These files should not be committed. It is recommended to add demos/local/ to your .gitignore.

verify or v

Lints JavaScript, Sass and configuration files against Origami coding standards.

test or t

Run Origami specification tests and component specific tests.

• If --debug is set, the test runner will not exit automatically to allow debugging of the tests.

Checks Sass supports silent and non-silent compilation modes. If pa11y.html demo exists, confirms it is accessible using Pa11y. If package.json contains a test script, confirms it exits with a 0 exit code. Runs tests using Karma defaulting to Chrome Stable, can be configured to use BrowserStack by using the --browserstack flag. You will need the environment variables BROWSER_STACK_USERNAME and BROWSER_STACK_ACCESS_KEY set. This will run the tests on the minimum version for enhanced experience based on the [FT Browser Support Policy[(https://docs.google.com/document/d/1mByh6sT8zI4XRyPKqWVsC2jUfXHZvhshS5SlHErWjXU).

init

Initialises a new component with a full boilerplate folder structure.

This command takes an argument in the form of a component name, which will populate all of the relevant files within that tree. Defaults to o-component-boilerplate.

e.g.

obt init o-my-new-component

Migration guide

Migrating from 7.X.X to 8.X.X

OBT no longer supports NodeJS v6 because it uses async functions. To use this version of OBT, you will need NodeJS v8 or above.

Migrating from 6.X.X to 7.X.X

The ability to use OBT via it's programmatic API has been removed, if you were using OBT via gulp, you will need to migrate to the command line version of OBT. OBT has removed the ability to configure the way it installs/builds/verifies code, this is to ensure that systems built with OBT follows the Origami specification and conventions.

Migrating from 5.X.X to 6.X.X

OBT build

The 6.0.0 release removes the ability for OBT to include the Babel/Core-JS polyfills in the built Javascript. If you are relying on this feature, we recommend that you use the Polyfill service instead.

OBT verify

The 6.0.0 release swapped out scss-lint for sass-lint.

If you are supplying your own custom scss-lint configuration you need to convert it to an equivalent sass-lint configuration, here is a tool which can do this for you. The programatic API and CLI flag has also changed from scssLintPath to sassLintPath.

Licence

This software is published by the Financial Times under the MIT licence.