You can configure roots through an optional
app.coffee file at the root of your project. Although it is not required for simple projects, there are a lot of very powerful options you can take advantage of, which are explained below in the options section. But first, let's talk about the format of the file
app.coffee can come in two flavors. The first is more simple, just configured as a coffeescript object. For example:
output: 'public' env: 'development' after: -> console.log('what a useful function')
This is a great way to format the file for maximum simplicity. It ends up being very clean and easy to manage. However, if you want to do more advanced things like
requireing in files node/commonjs-style, you will not be able to do this. It is parsed simply as an object, not with full node functionality. If you do want full node functionality though, you're in luck -- all you have to do is add
module.exports = to the top, like this:
axis = require('axis-css') autoprefixer = require('autoprefixer-stylus') module.exports = output: 'public' stylus: use: [axis, autoprefixer]
As you can see, here we are able to locally require in extra dependencies and push them directly into the roots pipeline. Make sure if you are requiring locally to note the use of
module.require - since this is loaded into roots' context, you'll need the
module prefix in order to load your deps from the right place.
Below are all the options that you can pass to roots, from the simplest to the most advanced.
The path to a folder (starting from project root) that your project will be compiled into.
An array containing minimatch strings that represent files or folder you wish to ignore from the compile process. Full globstar syntax supported. Automatically ignores
app.coffee and your output directory (wouldn't want to have it recursively compile itself!)
Array of directories that will have their contents dumped into the output folder rather than compiling into the folder they are in.
Basic environment variable. Usually set through command line options, but if you need you can override here.
When enabled, commands will dump out lots of information on what roots is doing internally.
When enabled, on
roots watch, the browser will automatically reload every time you save a file in your project.
roots watch will automatically open a browser to the local server. You can also pass a string which will be proxied to the
open() function, allowing you to open an external URL besides localhost after each compile.
An object that is injected into the options every compiler in use in the project. So for example, if you are using both jade and ejs in a project and some locals to be the same across the two, you don't have to duplicate, just add them to
locals. If there is a conflict between
locals and compiler-specific options, the compiler options will win out.
Hook function that is run before each compile. Function passes in an instance of the `roots class](../lib/index.coffee), so you have access to everything. Accepts either a single function or an array of functions, which will be run in order. Expects a promise or value to be returned from each function.
Same thing as before, but is run after each compile. Surprise surprise.
Roots uses charge as a local server, which exposes a bunch of useful options for customizing the way your static site is served. Charge can also be used standalone in production if you want to conserve your site's config, and charge's options match up with those of divshot, a great static hosting service.
You can pass in any of charge's options under the
server key other than
log to customize how your site is served. This can be great for redirects, clean urls, and/or single page apps.
You can also pass options directly to any compiler through
app.coffee. Just add them as an object under the name of the compiler. For example, if you want jade to output non-compressed html:
jade: pretty: true
That's all it takes. This will work for any compiler you have loaded. For more info on each supported compiler's options, see the accord docs.