financial-times/origami-build-tools

Standard Origami component development tools.

origami-build-tools

Build tools for developing Origami components.

• Installation
• Usage
• Commands
• API Reference
• Migration Guides
• Licence

Installation

1. Install node.js

2. Install the build tools globally:

   npm install -g origami-build-tools

Usage

Developing Existing Components Locally

First, change to your components directory:

git clone [email protected]:Financial-Times/o-table.git
cd o-table

Then install its dependencies:

obt install

To preview the components demos run the dev command. The dev command will automatically re-build the demos every time a file changes:

obt dev

After making your changes run the linter and check for errors:

obt lint

Also run the components tests:

obt test

To debug JavaScript test errors with immediate feedback and breakpoints, pass the debug flag. This will open the tests in a browser window with logs in the browser console. It will also watch and rebuild tests when you make changes:

obt test --debug

Further, JavaScript tests may be run in BrowserStack automatically with the --browserstack flag. See the test command for more details.

Creating A New Component

Origami Build Tools provides boilerplate for creating up a new Origami component. Run obt init and follow the prompts.

API Reference

Usage
	$ obt <command> [<options>]

Commands
	install, i             Install npm dependencies required to build the component
	develop, dev           Build demos locally every time a file changes and run a server to view them
	demo, d                Build demos into the demos directory
	init                   Initialise a new component with a boilerplate folder structure
	test, t                Run Origami specification tests and component specific tests
	verify, v, lint, l     Check folder and code structure follows Origami specification

Options
	-h, --help                 Print out this message
	-v, --version              Print out version of origami-build-tools
	--browserstack             Run tests using Browserstack instead of Chrome Stable
	--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.
	--debug                    Keep the test runner open to enable debugging in any browser.

Commands

install or i

Install npm required to build components.

develop or dev

Build demos locally every time a file changes and run a server to view them.

init

Creates boilerplate for a new Origami component.

demo or d

Build demos found in the origami.json manifest.

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

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 or lint or l

Lints JavaScript, Sass and configuration files (see Origami code recommendations).

test or t

Runs JavaScript and Sass tests.

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

Checks Sass includes a primary mixin. If pa11y.html demo exists, confirms it is accessible using Pa11y. 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).

Migration Guides

State	Major Version	Last Minor Release	Migration guide
✨ active	11	N/A	migrate to v11
⚠ maintained	10	10.9	migrate to v10
╳ deprecated	9	9.0	migrate to v9
╳ deprecated	8	8.2	migrate to v8
╳ deprecated	7	7.14	migrate to v7
╳ deprecated	6	6.2	migrate to v6
╳ deprecated	5	5.8	-
╳ deprecated	4	4.5	-
╳ deprecated	3	3.3	-
╳ deprecated	2	2.1	-
╳ deprecated	1	1.0	N/A

Licence

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

origami-build-tools's Issues

use update-notifier

So users know when their installation of origami-build-tools is out of date.

https://github.com/yeoman/update-notifier

Refactor

Results of the meeting to discuss Origami build process:

• We'd like to use one tool, as far as possible, for both components and products
• We're not really keen on ft-frontend-build as it stands currently. It's too complicated and very opinionated.
• Origami-build-tools is a preferable pattern, but needs to be more useful for products, and easier to add tasks.
• If we are going to use a task runner, Gulp is probably better

It's proposed that we modify origami-build tools to build it around Gulp, and make it possible to use it as a CLI tool (in which case you don't need any npm dependencies in your module or product), or as a Gulp config plugin, in a similar manner to that advocated by ft-frontend-build, in which case you do need Gulp in your project. But that pattern should be reserved for products, and only those that use Node.

Usage for modules will mirror the existing setup, ie commands like:

origami-build-tools install

Should continue to work as they do currently. Usage in products will most likely involve creating your own gulp file and importing tasks from the origami-build-tools. Propose the following atomic tasks:

• install-dependencies
• install-tools
• scss-lint
• jshint
• browserify
• uglify
• sass
• csso

And these higher level ones:

• install = install-tools + install-dependencies
• demo = Read demo config, loop demos and invoke browserify + uglify + sass + csso for each one (no longer any need to add the local demo warning, we can deal with this using global .gitignores)
• verify = scss-lint + jshint
• test = Read bower.json and invoke browserify + uglify + sass + csso for main files and again if silent mode is supported, test that files are produced which are zero or non-zero length as appropriate.
• build = Read bower.json and invoke browserify + uglify + sass + csso for main files

Alias to obt

Only install the sass gem if necessary

Currently, install will install the Ruby sass gem regardless of whether it's already installed. This makes it needlessly slow when running it locally.

There should be a check to see what version, if any, is already installed.

Verify breaks when .gitignore not present

$ obt verify

fs.js:432
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                 ^
Error: ENOENT, no such file or directory '/Users/rhys.evans/Sites/o-modules/o-cookies/.gitignore'
    at Object.fs.openSync (fs.js:432:18)
    at Object.fs.readFileSync (fs.js:289:15)
    at Object.getGitIgnorePaths (/usr/local/lib/node_modules/origami-build-tools/lib/files.js:133:22)
    at createScssLinterTask (/usr/local/lib/node_modules/origami-build-tools/lib/commands/verify.js:53:30)
    at exports.run (/usr/local/lib/node_modules/origami-build-tools/lib/commands/verify.js:93:9)
    at Object.<anonymous> (/usr/local/lib/node_modules/origami-build-tools/lib/origami-build-tools.js:70:3)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)

Add dev/prod option to build

For js

• dev creates srcmap
• prod either browserify shouldn't create a srcmap and should use the uglify transform, or just uglify after browserifying

For sass

• dev generates nested css with srcmap
• prod generates compressed sass and runs csso

Static code analysis

Does this look OK?

Running origami-build-tools verify will do the following:

• if main.scss is present, run scss-lint (using our agreed config)
• if main.js is present, run jshint (using our agreed config)

and output the results.

Should this be --watchable?

In future we could build in custom checks for Origami compliance - checking presence of origami.json etc.

Support using main.mustache as default template and pass it html

Support doing something like this and instead of passing it html, be able to pass it mustache templates.

Padding and margin declarations flagged wrong

Example:
margin should be written more concisely as 0 0 20px instead of 0 0 20px 0. Adding 0 to the end is not wrong in my opinion.

Another example:
padding should be written more concisely as 8px 8px 0 instead of 8px 8px 0 8px
This is wrong, how should I add left padding?

--buildservice demos still include local JS

<script src="main.js" />

Also, when the demo just uses the main.js (or main.scss), the --buildservice version should just use the normal bundles URL.

Lint tabs vs. spaces so that we can have consistent indentation across Origami

I've used this and it's quite nice. https://github.com/evanshortiss/lintspaces-cli

Suggested use of lintspaces (probably a better way to do files but good enough to test hack):-

lintspaces -n -t -d "tabs" -i js-comments `find . -name "*.js" ! -path "./node_modules/*" ! -path "./bower_components/*"`

I would have made a pull request but it's really quite tricky to add tasks. Raising a separate issue about this.

[Full disclaimer - even though I am suggesting tabs here, in my own time, I use spaces: https://github.com/matthew-andrews/offline-todo-api/blob/master/package.json#L9]

Stop magically fixing the missing .bowerrc

So I don't have the special .bowerrc file, I run bower install and it doesn't work. Then I run the build tool and it works.... because it magically resolved the dependency locations... perhaps rather than magically fixing this we could check for the existence of the file and tell the developer to fix it.

It's really hard to add tasks

Could we consider refactoring this to use an industry wide task runner instead?
Eg. Grunt, Gulp, Make

SCSSHint: camel case classes are not allowed

Camel case classes are valid class names, they work perfectly, I don't see the point to force them to all lowercase. All lowercase is harder to read as well.

Example: Class deleteInProgress in selector should be written in all lowercase as deleteinprogress

Only install Bower if it's not already installed

To speed up install command locally.

Doesn't work on Windows

Add no script tag when module is scriptless

Adds <script src="undefined" /> to the html at present

Verbose file output when in --local demo mode

Would be good to have sass output expanded and browserify in debug mode with src map when building a local demo

Add an update/upgrade task

Which just runs npm install -g https://github.com/Financial-Times/origami-build-tools/tarball/master

And some way of notifying users that their copy of build tools is out of date would be nice

And a post install script in package.json which runs origami-build-tools install (or at least the bit of it that installs non-npm dependencies)

verify to verify validity of origami.json

I'm happy to do this [it's quite simple] but just wanted to check that there's general agreement (or otherwise) that this is a sensible idea.

Things to check:-

• jshint origami.json outputs 0
• Check required properties are set: description, origamiType, support, supportStatus, etc
• Check origamiVersion is set to 1 (probably not worth doing anything that future-proofs this against future versions because we currently have no idea what an origami v2 might look like)

http://origami.ft.com/docs/syntax/origamijson/

Adding other modules from the build service to generated demo html

In some cases, one might want to use certain modules only in a demo, and not the whole module, like o-colors does with o-grid and o-techdocs. Right now, you would have to manually add the build service link requesting the css for those modules, and every time you build the demos, that will be lost and only the link to the demo sass file will be added.

Could we maybe add a property to the config file called dependencies for demos?

Using with Grunt

Can we add a grunt wrapper for the build task (or document how to write your own if it's relatively simple)

Incorrect console log when installing scss-lint

https://github.com/Financial-Times/origami-build-tools/blob/master/lib/commands/install.js#L76

Depth limit reported by SCSSlint

Depth limit is 3, but in the usecase of comment integration (where default Livefyre CSS should be overridden), a deepness much bigger than 3 is needed.
Because Livefyre is using deeper CSS selectors than 3, and our selectors need to be more specific to override, this limit should be either increased or removed.

Run module tests

Maybe agree on a convention that module developers, and event product developers add their test command to their package.json, and then obt test will run npm test.

Support new demo syntax

We now support a new demo syntax (see Financial-Times/ft-origami#184). The build tool should write the new syntax, or not write the demo list in the origami.json at all.

demo config should default to demos/src/config.json

So the command is shorter:

origami-build-tools demo --local --watch

or even, since --buildservice is already the default:

origami-build-tools demo

Add polyfill service to demos

Add a warning that SASS 3.4 is not supported...

... And ideally suggest the best version of 3.3 that is tested :-)

Using component's own .jshintrc file in verify

Since the spec allows for a component to have it's own .jshintrc file, could the verify command use this (if it exists)?

why no ruby installer?

The build tools automate the process of ruby dependencies, why not ruby itself?

RVM should be used in any environment where process.getuid is available and set to 0 (Ruby installer has to run as root).

For windows the ruby installer can be downloaded and run in silent mode (/silent or /verysilent) so it doesn't prompt the user for anything.

use semver

Static assets needs to be copied to the 'buildFolder' directory

Otherwise they don't show up

--local demo still uses build service asset paths

code snippet in demos

Not sure which project this issue should be created under...

I see this added to all the demos created by the build tools.

 <script src='http://registry.origami.ft.com/embedapi?autoload=resize'></script>

Why is it necessary? Resizing the iframe is something the parent window can do... there are no CORS issues to prevent this.

Demo build should populate origami.json demos property

When using OBT to build demos, it should also populate the demos property in origami.json, to ensure this always matches up with the demos that have been created.

Perhaps it should remove the property when you build for --local, and populate it only when you build for --buildservice.

scss-lint doesn't run for o-ft-forms

Running origami-build-tools verify for o-ft-forms. You just get this:

scss-lint
No SCSS files specified

2 errors

There are .scss files in the module...

Don't output a link tag if there's no stylesheet for the demo

https://github.com/Financial-Times/o-grid/blob/master/demos/test.html#L10 shows

<link rel="stylesheet" href="/bundles/css?modules=o-grid:/undefined" />

Because there's no stylesheet for this demo. That said, there ought to be a stylesheet for this demo so there's actually a bug here in grid as well, which may get fixed before the issue in obt.

Allow shorthand colors

ccc is considered wrong, while shorthand padding and margin declaration is forced.

This should be consistent (either shorthand or expanded or both allowed).
In my opinion shorthand color code is good.

Add a watch task

e.g. origami-build-tools watch -tasks [list of tasks to carry out]

absolute gitignore paths are handled the wrong way

Let's say you are in your git repo folder, where a .gitignore will contain this:
/bower_components
/node_modules

Git reads them as "absolute to the folder of the repo".

verify.js runs the pathsToGlob function for each entry in the gitignore file, and tries to identify if they exist and if they are folders. Passing an absolute path to the fs.existsSync will try find the path relative to the root of file system and not relative to the folder of the repo, this will miss to interpret the path as a folder, and will generate wrong ignore entries. The result: linting will run on everything inside node_modules and bower_components folder.

Solution: add process.cwd() before a path that is absolute.

Verbose output of scss-lint

Current output is

$ obt verify
scss-lint

1 errors

Debug mode by default

Currently on failing no errors are output

Travis build fails when phantomjs is an NPM dependency

At least that seems to be the cause. Example build failure:

https://travis-ci.org/Financial-Times/o-dom/builds/23515390

It seems to get stuck on installing phantomjs, give up and then skip the bower install.

Running the equivalent commands instead of origami-build-tool install resolves the problem.

JSHint verify reports "'requireText' is not defined."

requireText should be declared as a valid global variable in jshint.json, as textrequireify is used as a transform for the browserify build.

What demo files do I commit

This is a bit of a placeholder issue because I don't fully understand what the build tool does or what the intention is. @dansearle-ft explained it but still not 100% on what I'm meant to be doing.

When I run the demo build (for local development) it changes the origami.json file and creates HTML files that shouldn't be commit. It's not obvious why this is or what I should be commit or adding to .gitignore

Could all built demo files that should not be commit be place in a .tmp folder if they are for local use only? We can then just add .tmp to all .gitignores (including the one in the spec).

Also I would rather the tool didn't change the origami file for me, but rather direct me to make the change. If it does need to make a change then it should ask me if it's ok to update the file. Looking a the files changed in git status is surprising when there are changes.... Am I meant to commit them or is there weirdness happening?

Add csso

We should add csso to the standard build process. It's in the build service and ft-frontend-build, not currently in the manual build tutorial or obt.

Publish on npm?

Is there any reason why we can't publish this on npm?

A specific version of the SASS gem should be installed

Otherwise, when a new version is released, it could cause build failures.

3.3.3?

Allow a build with standalone option for browserify

Standalone option of browserify should be available using OBT, which would export a global variable with the value of module.exports of main.js.