Upgrading From Roots v2

Version 3 of roots is a massively breaking upgrade, so if you are expecting to be able to upgrade from a project built on v2, you might run into some issues. Make sure to keep your project locked at version 2 until you have the time to make a bunch of changes required for the upgrade, which will be reviewed below.

New app.coffee structure

The structure of the app.coffee file in v3 is entirely different, so if you're looking to convert yours, you probably will have to rewrite most/all of it. Make sure to check out the full documentation for the new app.coffee format for help converting it over.

Specifically of note, you will need to add the dynamic context extension in manually if you were using dynamic content (more info below), and add in axis etc to your stylus pipeline. You can check out an example of the new default app.coffee file here.

Dynamic content is now an extension

We pulled the dynamic content feature (where you can add front matter to files in a folder then access them in other views) out into its own roots extension. This means that it won't weigh down the project if you aren't using it, and you can customize options better if you are. Make sure to check out the extension's documentation and take note of a few features that have changed, such as automatically inserted variable names (usually prefixed with an underscore now to avoid conflicts), and lack of an integrated layout system (discussed further below).

No more roots layout system

In roots v2, we had a small layout system integrated in to roots, that worked around each compiler's limitations. However, we found that there were a lot of people asking for extra layout-based features that we could not provide without having to patch each language we supported. Since it's the compiled language's role to handle layouts anyway, we stripped out roots' layout system and now are relying on systems provided by each compiled language, which tend to be more powerful, flexible, and natural to the language anyway.

This means no more = yield or = content, and no specifying the layout in the front matter or app.coffee. Our default view engine, jade, has a great layout system that you should take advantage of.

View helpers not automatically bundled

Later in the life of roots v2, we bundled in a couple of view helpers that we thought might be useful, such as sorting and string manipulation functions. This was always a silly idea, and is much better to give users control over what they want to include as view helpers. So in roots v3, you define your own view helpers. If you want to include view helpers, just install via npm, require them into your app.coffee file, then add them through locals. You can find more info on locals in the configuration docs.

Use package.json to manage dependencies

In roots v2, all the compiler dependencies were bundled into core. This also was a bad idea, as it restricted us from upgrading any dependency without potentially introducing breaking changes. In v3, you control your compilers and dependencies so that you can upgrade or lock them as you need using node's native package.json. When you generate a new project, the package.json file will already be set up for you, but for more info if you are not familiar, check out the npm docs for the package file.

New version of axis

Since roots v2, Axis has gone through many changes for the better. We also have produced 2 additional libraries that are super useful and form the core of a solid stylus pipeline, rupture for media queries and autoprefixer-stylus for browser prefixing. All three of these are included in the new roots v3 base template. In addition, we have removed vertical rhythm, as it was not well-maintained and really belongs in a separate library, so if you were using it take note of this.

If you are upgrading old code, there are a lot of changes to axis, so be careful. You can find full interactive docs for the latest version of axis here.

Global variables renamed to prevent conflicts

This is not a change that will affect most people, but there were a few global variables inserted automatically for dealing with edge cases, the most commonly used one probably being path to give you the current page path (useful for auto-adding body classes). Any of these variables have been changed over such that they are prefixed by an underscore to prevent any potential conflicts. So now it's _path. You can always log out all the locals in a jade template using = JSON.stringify(locals) if you are curious.