Sage

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

Features

Sass for stylesheets
Modern JavaScript
Laravel Mix for compiling assets and concatenating and minifying files
Browsersync for synchronized browser testing
Blade as a templating engine
CSS framework (optional): Bootstrap 4, Bulma, Foundation, Tachyons, Tailwind

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

Requirements

Make sure all dependencies have been installed before moving on:

WordPress >= 5.2
PHP >= 7.1.3 (with php-mbstring enabled)
Composer
Node.js >= 8.0.0
Yarn

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

To install the latest development version of Sage, add dev-master to the end of the command:

$ composer create-project roots/sage your-theme-name dev-master

During theme installation you will have options to update style.css theme headers, select a CSS framework, and configure Browsersync.

Theme structure

themes/your-theme-name/   # → Root of your Sage based theme
├── composer.json         # → Autoloading for `app/` files
├── composer.lock         # → Composer lock file (never edit)
├── dist/                 # → Built theme assets (never edit)
├── functions.php         # → Composer autoloader, Acorn bootloader
├── 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
├── style.css             # → Theme meta information
├── app/                  # → Theme PHP
│   ├── Composers/        # → View composers
│   ├── Providers/        # → Service providers
│   ├── admin.php         # → Theme customizer setup
│   ├── filters.php       # → Theme filters
│   ├── helpers.php       # → Helper functions
│   └── setup.php         # → Theme setup
├── config/               # → Config files
│   ├── app.php           # → Application configuration
│   ├── assets.php        # → Asset configuration
│   ├── filesystems.php   # → Filesystems configuration
│   ├── logging.php       # → Logging configuration
│   └── view.php          # → View configuration
├── dist/                 # → Built theme assets (never edit)
├── resources/            # → Theme assets and templates
│   ├── assets/           # → Front-end assets
│   │   ├── fonts/        # → Theme fonts
│   │   ├── images/       # → Theme images
│   │   ├── scripts/      # → Theme JS
│   │   └── styles/       # → Theme stylesheets
│   └── views/            # → Theme templates
│       ├── layouts/      # → Base templates
│       └── partials/     # → Partial templates
├── storage/              # → Storage location for cache (never edit)
└── vendor/               # → Composer packages (never edit)

Theme setup

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

Theme development

Run yarn from the theme directory to install dependencies
Update webpack.mix.js with your local dev URL

Build commands

yarn start — Compile assets when file changes are made, start Browsersync session
yarn build — Compile and optimize the files in your assets directory
yarn build:production — Compile assets for production