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.
-
Install these dependencies:
-
Install the build tools globally:
npm install -g origami-build-tools
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
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
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 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 whentrue
. For npm this will be the result of--loglevel info
. (Default: false)
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'
:
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 aFunction
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
- js:
- 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}
)
- sass:
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
Thedemos
property of yourorigami.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 onrunServer
. 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
.
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']
- scssLintPath:
- 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']
- jsHintPath:
- 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
- editorconfigPath:
- origamiJson() If there's an 'origami.json' file in your project's root, it will make sure it's compliant with the spec
- 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
)
- HEROKU_AUTH_TOKEN: The result of running
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.
This software is published by the Financial Times under the MIT licence.