Skip to content
This repository has been archived by the owner on Mar 14, 2022. It is now read-only.

Financial-Times/origami-build-tools

Folders and files

NameName
Last commit message
Last commit date

Latest commit

author
Alberto Elias
Aug 11, 2015
3624ae1 · Aug 11, 2015
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

origami-build-tools Build Status

Standardised build tools for Origami modules and products developed based on these modules.

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

Installation

  1. Install these dependencies:

    • node.js
    • Ruby (Macs typically ship with Ruby by default)
  2. Install the build tools globally:

     npm install -g origami-build-tools
    

Usage

Run the install task for the first time will to install required dependencies:

origami-build-tools install

### Developing products

Build CSS and JavaScript bundles in the build directory:

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 --local --watch

Tasks

All the tasks are built using gulp, and almost all of them return a stream. They are structured in 5 higher level tasks, and each one has one or more subtasks.

Usage: origami-build-tools <command> [<options>]

Commands:
   install  Install system and local dependencies
   build    Build module in current directory
   demo     Build demos into the demos/ directory
   verify   Lint code and verify if module structure follows the Origami specification
   test     Test if Sass silent compilation follows the Origami specification

Mostly used options include:
   [--watch]                    Re-run every time a file changes
   [--runServer]                Build demos locally and runs a server
   [--updateorigami]            Update origami.json with the latest demo files created
   [--js=<path>]                Main JavaScript file (default: ./src/main.js)
   [--sass=<path>]              Main Sass file (default: ./src/main.scss)
   [--buildJs=<file>]           Compiled JavaScript file (default: main.js)
   [--buildCss=<file>]          Compiled CSS file (default: main.css)
   [--buildFolder=<dir>]        Compiled assets directory (default: ./build/)
   [--scssLintPath=<path>]      Custom scss-lint configuration
   [--jsHintPath=<path>]        Custom JSHint configuration
   [--editorconfigPath=<path>]  Custom .editorconfig

install

Install tools and dependencies required to build modules.

Runs:

  • installScssLint() globally (if it's not already installed)
  • installBower() globally (if it's not already installed)
  • runNpmInstall() if there is a package.json inthe root directory
  • runBowerInstall() using both the Origami Registry and the default Bower registry to resolve dependencies

The versions that are installed and supported are:

  • scss-lint: '0.35.0'
  • Bower: '^1.3.0'

Config:

  • verbose: Boolean Outputs verbose results of bower and npm installation when true. For npm this will be the result of --loglevel info. (Default: false)

build

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

It comes with support for things like:

  • Babel so you can use ES2015 features in your modules and products
  • autoprefixer so you don't have to worry about writing browser prefixes in your Sass
  • If env is set to 'production':
    • uglifyJS which minimises your JavaScript bundle
    • clean-css which minimises your CSS bundle

Runs:

  • js(gulp, config) Config accepts:
    • js: String Path to your main JavaScript file. (Default: './main.js' and checks your bower.json to see if it's in its main key)
    • buildJs: String Name of the built JavaScript bundle. (Default: 'main.js')
    • buildFolder: String Path to directory where the built file will be created. If set to 'disabled', files won't be saved. (Default: './build/')
    • env: String It can be either 'production' or 'development'. If it's 'production', it will run uglify. If it's 'development', it will generate a sourcemap. (Default: 'development')
    • cwd: String The path to the working directory, in which the code to be built exists. (Default: current working directory)
    • sourcemaps: Boolean Set to true to output sourcemaps, even if env is 'development'. (Default: false)
    • transforms: Array Additional browserify transforms to run after babelify, debowerify and textrequireify. Each transform should be specified as a
      • Function The transform function. e.g: var brfs = require('brfs'); config.transform.push(brfs);
    • insertGlobals: See browserify documentation
    • detectGlobals: See browserify documentation
    • ignoreMissing: See browserify documentation
    • standalone: See browserify documentation
  • sass(gulp, config) Config accepts:
    • sass: String Path to your main Sass file. (Default: './main.scss' and checks your bower.json to see if it's in its main key)
    • autoprefixerBrowsers: Array An array of strings of browser names for autoprefixer to check what prefixes it needs. (Default: ["> 1%", "last 2 versions", "ie > 6", "ff ESR"])
    • autoprefixerCascade: Boolean Whether autoprefixer should display CSS prefixed properties cascaded (Default: false)
    • autoprefixerRemove: Boolean Remove unneeded prefixes (Default: true)
    • cwd: String The path to the working directory, in which the code to be built exists. (Default: current working directory)
    • buildCss: String Name of the built CSS bundle. (Default: 'main.css')
    • buildFolder: String Path to directory where the built file will be created. If set to 'disabled', files won't be saved. (Default: './build/')
    • env: String It can be either 'production' or 'development'. If it's 'production', it will compile the Sass file with the 'compressed' style option and will also run clean-css. (Default: development)
    • cleanCss: Object Config object to pass to clean-css. (Default: {advanced: false})

demo

Build demos found in the demo config file into the demos/ directory.

Config:

  • local: Boolean Build local HTML, CSS and JS files, in addition to demo HTML for the build service. Default: false
  • demoConfig: String The path to the demo config file. Default: demos/src/config.json
  • updateorigami: Boolean The demos property of your origami.json file will be updated - to list the demo files that have been created.
  • runServer: Boolean Whether you want to run a local server or not. If true, it also sets 'local' to true. Default: false
  • livereload: Boolean Will enable livereload on runServer. Default: true

Runs:

  • runServer(gulp) Starts a local server

Build service demos consist of only HTML, with build service URLs for static resources, and are created in demos/.

Local 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

Lints JavaScript and SCSS against Origami coding standards (see standards for SCSS and JavaScript).

Runs:

  • scssLint(gulp, config) Config accepts:
    • scssLintPath: String Path to your custom 'scss-lint.yml' config file. (Default: 'origami-build-tools/config/scss-lint.yml') This may be set for product development, but developers of Origami-compliant components are required to accept the default
    • excludeFiles Array e.g. ['!**/demo.scss']
  • jsHint(gulp, config) Config accepts:
    • jsHintPath: String Path to your custom jsHint config file. (Default: 'origami-build-tools/config/jshint.json' This may be set for product development, but developers of Origami-compliant components are required to accept the default
    • excludeFiles Array e.g. ['!**/demo.js']
  • lintspaces(gulp, config) Config accepts:
    • editorconfigPath: String Path to your '.editorconfig' that lintspaces uses for linting. (Default: 'origami-build-tools/config/.editorconfig') This may be set for product development, but developers of Origami-compliant components are required to accept the default
  • origamiJson() If there's an 'origami.json' file in your project's root, it will make sure it's compliant with the spec

test

  • silentCompilation(gulp) Test silent compilation. Check the Sass outputs no CSS by default. Only ran af a $<module-name>-is-silent variable is found
  • silentCompilation(gulp) Test silent compilation. Check the Sass outputs some CSS with $<module-name>-is-silent set to false. Only ran af a $<module-name>-is-silent variable is found
  • npmTest() Runs 'npm test', so whatever test script that you have in you package.json will be executed
  • browserTest(gulp, config) Runs Nightwatch tests on our Selenium grid by deploying the demo pages to Heroku. This is an optional subtask that requires the config option browserTest to be set to true. You also need to set the following environment variables:
    • HEROKU_AUTH_TOKEN: The result of running heroku auth:token
    • SELENIUM_USER: The username of the Selenium grid proxy
    • SELENIUM_KEY: The key to use the proxy to the Selenium grid
    • SELENIUM_HOST: The host of the Selenium grid or proxy Config accepts:
    • testUrl: String Url to where the html the tests are going to run agains is. (Default: 'https://module-name.herokuapp.com')
    • nightwatchConfig: String Path to your 'nightwatch.json' file that Nightwatch uses for testing. (Default: ./test/browser/nightwatch.json)
    • environments: String Comma separated list of environments from your nightwatch config file to run your tests on. (Default: chrome_latest,chrome_latest-1,firefox_latest,firefox_latest-1,ie8_Grid,ie9_Grid,ie10_Grid,ie11_Grid,safari7_Grid)
    • testsPath: String Relative path from your project's root directory to where your nightwatch tests are. (Default: test/browser/tests)

gulpfile usage

Use the build tools in your own Gulp file to incorporate the Origami build process into a product (don't use this method if you are building an Origami component). An in depth explanation of how to use the origami-build-tools in your product to build Origami modules can be found in the Origami spec.

To run these tasks in your gulpfile.js, you only need to require origami-build-tools and run the task or subtask you need, passing gulp and an optional config object.

var gulp = require('gulp');
var obt = require('origami-build-tools');

gulp.task('build', function() {
	obt.build.js(gulp, {js: './src/main.js'});
	obt.build.sass(gulp, {sass: './src/main.scss'});
});

gulp.task('verify', function() {
	obt.verify(gulp, {
		js: './src/main.js',
		sass: './src/main.scss'
	});
});

Note: to use this you will need to install origami-build-tools and gulp as direct dependencies of your project. Additionally, if you do not have it installed already, you will also need to install gulp globally.

npm install --save-dev origami-build-tools
npm install --save-dev gulp
npm install -g gulp

The origami-build-tools module also defines some helper methods to verify and list the available tasks:

obt.isValid(taskName) will return a boolean value indicating whether the name of the given task is valid.

obt.list() will return a list of valid task names.

obt.loadAll() will return an object with all of the available tasks loaded onto it. Access tasks on this object as properties in the same way as the obt object.

Licence

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