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!
$ 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
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.
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.
$ npm i roots-browserify --save
Then require it into our
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.
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).
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
-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.