WordPress starter theme with a modern development workflow
Latest commit 9ebe9cd Jan 19, 2017 @retlehs retlehs committed on GitHub Merge pull request #1806 from roots/beta2
Beta 2



Packagist devDependency Status Build Status

Sage is a WordPress starter theme with a modern development workflow.

Sage 9 is in active development and is currently in beta. The master branch tracks Sage 9 development. If you want a stable version, use the latest Sage 8 release.


  • Sass for stylesheets
  • ES6 for JavaScript
  • Webpack for compiling assets, optimizing images, and concatenating and minifying files
  • Browsersync for synchronized browser testing
  • Laravel's Blade as a templating engine
  • CSS framework options:

See a working example at roots-example-project.com.


Make sure all dependencies have been installed before moving on:

Theme installation

Install Sage using Composer from your WordPress themes directory (replace your-theme-name below with the name of your theme):

# @ app/themes/ or wp-content/themes/
$ composer create-project roots/sage your-theme-name dev-master

During theme installation you will have the options to:

  • Update theme headers (theme name, description, author, etc.)
  • Select a CSS framework (Bootstrap, Foundation, none)
  • Add Font Awesome

Theme structure

themes/your-theme-name/   # β†’ Root of your Sage based theme
β”œβ”€β”€ assets                # β†’ Front-end assets
β”‚Β Β  β”œβ”€β”€ config.json       # β†’ Settings for compiled assets
β”‚Β Β  β”œβ”€β”€ build/            # β†’ Webpack and ESLint config
β”‚Β Β  β”œβ”€β”€ fonts/            # β†’ Theme fonts
β”‚Β Β  β”œβ”€β”€ images/           # β†’ Theme images
β”‚Β Β  β”œβ”€β”€ scripts/          # β†’ Theme JS
β”‚Β Β  └── styles/           # β†’ Theme stylesheets
β”œβ”€β”€ composer.json         # β†’ Autoloading for `src/` files
β”œβ”€β”€ composer.lock         # β†’ Composer lock file (never edit)
β”œβ”€β”€ dist/                 # β†’ Built theme assets (never edit)
β”œβ”€β”€ functions.php         # β†’ Composer autoloader, theme includes
β”œβ”€β”€ index.php             # β†’ Never manually edit
β”œβ”€β”€ node_modules/         # β†’ Node.js packages (never edit)
β”œβ”€β”€ package.json          # β†’ Node.js dependencies and scripts
β”œβ”€β”€ screenshot.png        # β†’ Theme screenshot for WP admin
β”œβ”€β”€ src/                  # β†’ Theme PHP
β”‚Β Β  β”œβ”€β”€ lib/Sage/         # β†’ Blade implementation, asset manifest
β”‚Β Β  β”œβ”€β”€ admin.php         # β†’ Theme customizer setup
β”‚Β Β  β”œβ”€β”€ filters.php       # β†’ Theme filters
β”‚Β Β  β”œβ”€β”€ helpers.php       # β†’ Helper functions
β”‚Β Β  └── setup.php         # β†’ Theme setup
β”œβ”€β”€ style.css             # β†’ Theme meta information
β”œβ”€β”€ templates/            # β†’ Theme templates
β”‚Β Β  β”œβ”€β”€ layouts/          # β†’ Base templates
β”‚Β Β  └── partials/         # β†’ Partial templates
└── vendor/               # β†’ Composer packages (never edit)

Theme setup

Edit src/setup.php to enable or disable theme features, setup navigation menus, post thumbnail sizes, and sidebars.

Theme development

Sage uses Webpack as a build tool and npm to manage front-end packages.

Install dependencies

From the command line on your host machine (not on your Vagrant development box), navigate to the theme directory then run yarn:

# @ example.com/site/web/app/themes/your-theme-name
$ yarn

You now have all the necessary dependencies to run the build process.

Build commands

  • yarn run start β€” Compile assets when file changes are made, start Browsersync session
  • yarn run build β€” Compile and optimize the files in your assets directory
  • yarn run build:production β€” Compile assets for production

Additional commands

  • yarn run rmdist β€” Remove your dist/ folder
  • yarn run lint β€” Run eslint against your assets and build scripts
  • composer test β€” Check your PHP for code smells with phpmd and PSR-2 compliance with phpcs

Using Browsersync

To use Browsersync you need to update devUrl at the bottom of assets/config.json to reflect your local development hostname.

If your local development URL is https://project-name.dev, update the file to read:

  "devUrl": "https://project-name.dev",

If you are not using Bedrock, update publicPath to reflect your folder structure:

  "publicPath": "/wp-content/themes/sage/"

By default, Browsersync will use webpack's HMR, which won't trigger a page reload in your browser.

If you would like to force Browsersync to reload the page whenever certain file types are edited, then add them to watch in assets/config.json.

  "watch": [


Sage 8 documentation is available at https://roots.io/sage/docs/.

Sage 9 documention is currently in progress and can be viewed at https://github.com/roots/docs/tree/sage-9/sage.


Contributions are welcome from everyone. We have contributing guidelines to help you get started.


Keep track of development and community news.