Roots

5.2.0 verified Fri May 01 auth: no javascript maintenance

Roots is a fast, simple, and customizable static site compiler, currently in maintenance mode at version 5.2.0. It offers a flexible build pipeline with support for various preprocessors (Jade, Stylus, CoffeeScript, etc.), automatic asset pipeline, and live reload via Browsersync. Roots is no longer actively developed; the team now maintains Spike, a more modern alternative. Roots compiles static sites with minimal configuration and supports project scaffolding via Sprout. It is best suited for small-to-medium projects that don't require server-side rendering.

Common errors

error Error: Cannot find module 'roots' ↓

cause Roots not installed or global module not in PATH.

fix

Install globally: npm install -g roots

error Roots: command not found ↓

cause Roots not installed globally or npm bin not in PATH.

fix

Install globally: npm install -g roots; ensure npm global bin is in PATH.

error Error: Cannot find module 'jade' ↓

cause Missing Jade dependency for .jade files.

fix

Install jade locally: npm install --save-dev jade; or use Pug (rename to .pug and install pug).

Warnings

deprecated Roots is in maintenance mode. No new features will be added. Consider migrating to Spike (https://github.com/static-dev/spike). ↓

fix Evaluate Spike as a replacement for new projects.

breaking roots deploy command removed in v5.0.0. Use ship separately. ↓

fix Install ship globally: npm i ship -g, then run: roots compile && ship public -to <target>

breaking Babel upgraded to v6 in roots v4.0.0. If using Babel, must use Babel 6 or higher. ↓

fix Update Babel to v6 or remove Babel dependency.

gotcha EACCES permission errors when installing roots globally on macOS/Linux. ↓

fix Either use nvm or change npm global directory: see https://roots.cx/docs/error#eacces-permission-denied

Install

npm install roots

yarn add roots

pnpm add roots

Imports

default import
wrong
```
const roots = require('roots')
```
correct
```
import roots from 'roots'
```
Roots is typically used as a CLI tool, not imported programmatically. If you must import it, use ESM syntax.
compile function
wrong
```
const { compile } = require('roots')
```
correct
```
import { compile } from 'roots'
```
ESM-only since v5? Actually roots v5 still supports CJS, but ESM is preferred.
Roots class
wrong
```
const Roots = require('roots').default
```
correct
```
import Roots from 'roots'
```
Default export is the Roots constructor. CJS require yields the same object.

Quickstart

Create a new Roots project, add a layout (Jade) and page, a Stylus stylesheet, compile to public/.

<!-- Install globally -->
npm install roots -g
<!-- Create a new project -->
roots new my-project
cd my-project
<!-- Add a layout and page -->
mkdir -p views/layouts
cat > views/layouts/default.jade <<EOF
!!!
html
  head
    title My Site
  body
    block content
EOF
cat > views/index.jade <<EOF
extends ./layouts/default.jade

block content
  h1 Hello, Roots!
EOF
<!-- Add a stylus file -->
mkdir -p assets/css
cat > assets/css/main.styl <<EOF
body
  font-family: sans-serif
EOF
<!-- Compile -->
roots compile
<!-- Output in public/ -->
ls public/