WordPress Sage Theme Documentation: Theme Build and Deployment

The Sage front-end workflow mainly uses the following tools.

• gulp

  gulp is a front-end streaming build tool. In the earlier Roots theme, we used Grunt.

• Bower

  Bower is a front-end package manager. By default, we pull in Bootstrap, Modernizr, and the latest jQuery from Bower.

• BrowserSync

  During development, BrowserSync injects updated CSS and JS so multiple browsers stay in sync with front-end changes. In the earlier Roots theme, we used LiveReload.

• asset-builder

  asset-builder uses a manifest file to collect and organize front-end assets.

• wiredep

  wiredep injects Sass and Less dependencies from Bower packages into the theme’s stylesheet files.

Install project dependencies

Before you begin, make sure your development machine meets the following requirements.

• Node >= 0.10.0
• npm >= 2.1.5

After installing Node.js, it is recommended that you upgrade npm to the latest version:

npm install -g npm@latest

Run the following commands in the command line.

• Install gulp and Bower globally: npm install -g gulp bower
• Switch to the theme directory and run npm install to install the Node.js dependencies.
• Run bower install to install the Bower dependencies.

Once everything is installed, we have the prerequisites needed to build the front-end assets.

Available Gulp commands

• gulp — Compiles and optimizes the files in the assets directory.
• gulp watch — Watches the files in the assets directory and recompiles them whenever they change.
• gulp --production — Compiles the files in assets for production without sourcemaps.

Before using BrowserSync, update the devUrl value at the bottom of assets/manifest.json so it matches the hostname on your development machine.

Add front-end packages with Bower

Use the following command to add a Bower package: bower install --save package-name. When you use the --save parameter, Bower writes the package dependency information into the theme’s bower.json file.

asset-builder uses main-bower-files to read bower.json and automatically collect CSS and JS from packages that define a main property. You can override that behavior with the overrides property in bower.json.

You can see examples of those overrides in bower.json.

Resource pipeline

The manifest.json file in the assets/ directory is used by asset-builder to build the CSS and JS files used by the theme.

Theme styles

Sage includes a main stylesheet: dist/styles/main.css. This file is built from assets/styles/main.scss.

In main.scss:

• wiredep is used to inject Sass dependencies from Bower.
• Barebones partials are imported to help you start customizing the theme styles.

Any CSS provided by Bower packages through their main dependency is automatically included in the main stylesheet.

The editor stylesheet used by TinyMCE is generated from the main stylesheet.

Theme JavaScript

Sage includes a main JavaScript file: dist/scripts/main.js. This file is built from assets/scripts/main.js.

Any Bower packages required by the main JavaScript file are automatically bundled into the main JavaScript file.

To ensure that jQuery works normally, Sage loads jQuery before the other files.