Getting Started with Roots v3

Hello there and welcome! If you have used roots before, you're in for an awesome upgrade, and if not don't worry, roots has been built specifically to make things as simple and streamlined as possible!

To get started, make sure you have node.js installed and can install npm packages globally without sudo, then just run this command in your terminal:

$ npm i roots -g

This will take a minute -- roots has a number of dependencies. When it's done we can use roots' integration with sprout to generate a basic site template:

$ roots new example-project

This will ask you a couple questions about your site, then create the template in a folder called example-project in whatever directory you were in. cd into it, open it up in your favorite text editor, and let's take a look around. You should see a folder structure something like this:

.
├── app.coffee
├── app.production.coffee
├── assets
│   ├── css
│   │   ├── _settings.styl
│   │   └── master.styl
│   ├── img
│   └── js
│       └── main.coffee
├── package.json
├── readme.md
└── views
    ├── index.jade
    └── layout.jade

Roots is a node tool and for that reason uses npm and package.json to manage dependencies. You can see a basic package.json file at the root. This is optional though, if you have no dependencies you don't need it. Roots uses one more optional config file as well, app.coffee, which you can find at the root, as well as app.production.coffee. We'll talk about these in more depth soon.

Other than that, there are views and assets folders, which hold the html and css/js/images, respectively. If you open up the views folder you'll find a couple jade files. Jade is a great template engine and makes life much easier, but if it's not your jam, you can easily replace it with another option like ejs, handlebars, or one of many others just by installing the package with npm and changing the file extension. In fact, let's try it right now and make an ejs template. First run

$ npm i ejs --save

And now create a new file in the views folder with the ejs extension (maybe about.ejs). That's all it takes! We'll see the result in a moment when we compile.

Next, let's move on to the assets. Here we are using stylus and coffeescript, but again you can change these to whatever else you want, including just vanilla css and js if that's your preference. So now that we have reviewed the languages, let's get this site compiled. From your command line, run:

$ roots watch

This will compile your site, open it up in a browser, and watch the files for changes. If anything does change, it will recompile and reload the browser for you. Try it! While you're at it, check http://localhost:1111/about.html to make sure your ejs file compiled.

Using app.coffee

In roots, app.coffee is a configuration file where you can change settings and extend roots. Let's talk about a couple ways you can use app.coffee to your advantage.

First, let's try adding an extension. Roots extensions are a great way to extend roots' core functionality. As an example, let's bring in roots-browserify so that we can use browserify to handle our javascript pipeline. First, we need to install the extension:

$ npm i roots-browserify --save

Then require it into our app.coffee file and initialize it as an extension, making sure to replace js_pipeline, which is the default extension for handling your javascript:

browserify = require 'roots-browserify'

module.exports =
  extensions: [
    browserify(files: "assets/js/main.coffee", out: 'js/build.js')
  ]

For more info on initialization, check out the docs. Now we have the full power of browserify ready. If you restart the watcher (which you have to do when you change app.coffee), you should see a new file in the public folder at js/build.js. From here, you can install packages using npm and use commonjs to load them wherever you need. If you want, you can also add browserify transforms using the transforms option to add even more flexibility.

There are a bunch more options you can use to customize app.coffee as well, which you can read about here. You can also find a curated directory of roots extensions here.

Customizing compilers

You can also directly customize any compiled language's options through roots. You might have seen that there are already some stylus plugins being added in the roots default template, actually. You can modify the options for any other compiler as well, which allows you to customize roots' behavior exactly as you want it to be.

To customize a compiler's behavior, just add options under the compiler's name in app.coffee. For example, if we wanted jade to pretty-format the output, we could just add the pretty option to jade as such:

module.exports =
  jade:
    pretty: true

To see a full listing of options for each supported language, check out the accord docs (accord is the library that handles roots' multi-language compilation under the hood).

Using Environments

Sometimes you want to be able to specify different setting for different environments. For example, you might want to minify all your code in production, but not in development for easier debugging. Or you might want to produce source maps in development, but not in production. Luckily, this is easy to do using environment-specific app.coffee files. You will see that there is already a app.production.coffee at the root, that's exactly what this file is for. In this file, you can see that the sourcemap options are no longer passed to any compilers, and that the js and css pipelines now minify their code. You can make any other changes in here that you'd like, such as specifying different config values, etc.

To see the effects of the production settings, run roots watch or compile with the --env or -e flag, as such:

$ roots watch -e production

You should see your production settings in effect. Also note that you can make as many environment-specific files as you'd like. For example, if you also want a staging environment, you can make app.staging.coffee and run a compile with roots compile -e staging. For more information on environment-specific config files, check out the docs, here.

Thanks for taking the time to read through this guide, and hope that you enjoy roots! If you have any questions, make sure to refer to the docs section, and if you can't find your answers there, join us in the gitter chatroom, and/or file an issue if you think you've found a bug.