Last updated on 24th February 2026

Sage & DeployHQ: A Comprehensive Guide

Sage is a WordPress starter theme built by Roots that brings modern development practices to theme development. If you have landed here looking for Sage accounting software, this guide is not for that — this covers the Roots Sage WordPress starter theme, a Composer-managed, Blade-templated theme used by agencies and developers who want a Laravel-inspired workflow inside WordPress.

Sage pairs naturally with Bedrock, the Roots WordPress boilerplate, to form a modern WordPress stack. This guide walks through what Sage offers, how it is structured, and how to deploy it reliably with DeployHQ.

Why Sage

Traditional WordPress themes mix PHP logic, HTML markup, and asset handling into a single tangled layer. Sage separates these concerns using patterns borrowed from Laravel:

  • Blade templating — Laravel's template engine replaces the WordPress template hierarchy with clean, composable views. Layouts, partials, and directives like @if, @foreach, and @include replace the usual get_template_part() calls.
  • Composer dependency management — Sage and its dependencies are managed through Composer rather than manual file drops. This includes Acorn, the package that bridges Laravel components into WordPress.
  • Bud.js build toolchain — Sage 10 and 11 use Bud.js for asset compilation. Bud replaced both Laravel Mix and raw Webpack configurations from earlier versions, offering a faster and more ergonomic build system with hot module replacement out of the box.
  • Modern frontend workflow — PostCSS or Tailwind CSS for styles, ES modules for scripts, and a dev server with live reloading during development.

If your team already knows Laravel, Sage will feel familiar. If not, the learning curve is steeper than a conventional theme, but the payoff is a significantly more maintainable codebase.

Sage Project Structure

A Sage theme follows a structured layout that separates application logic from presentation:

themes/sage/
├── app/                    # PHP application code
│   ├── Providers/          # Service providers (boot theme features)
│   ├── View/               # View composers (pass data to Blade views)
│   └── filters.php         # WordPress filter hooks
├── resources/
│   ├── views/              # Blade templates (.blade.php)
│   │   ├── layouts/        # Base page layouts
│   │   ├── partials/       # Reusable components
│   │   └── sections/       # Page sections
│   ├── styles/             # CSS/PostCSS/Tailwind source files
│   └── scripts/            # JavaScript source modules
├── public/                 # Compiled assets (build output)
├── bud.config.js           # Bud.js build configuration
├── composer.json           # PHP dependencies
└── package.json            # Node dependencies

The app/ directory holds PHP logic — service providers, view composers, and filters. The resources/views/ directory contains Blade templates. Compiled assets land in public/, which is the only directory WordPress actually serves to visitors.

Acorn: The Laravel-WordPress Bridge

Acorn is the package that makes Laravel features available inside WordPress. It provides the service container, configuration system, and console commands that Sage depends on. Without Acorn, Blade templating, view composers, and service providers would not function.

Acorn is installed via Composer as a dependency of Sage. It exposes a wp acorn CLI that you will use for tasks like caching compiled views and optimizing autoloaded classes:

wp acorn optimize          # Cache config, routes, views
wp acorn view:cache        # Pre-compile all Blade views
wp acorn view:clear        # Clear compiled views

These commands matter for deployment — running wp acorn optimize after deploying ensures views are pre-compiled and the config cache is warm, reducing first-request latency in production.

Bud.js Build Configuration

Bud.js handles all asset compilation. The configuration lives in bud.config.js at the theme root. A typical setup looks like this:

export default async (app) => {
  app
    .entry('app', ['@scripts/app', '@styles/app'])
    .entry('editor', ['@scripts/editor', '@styles/editor'])
    .assets(['images'])
    .setPublicPath('/app/themes/sage/public/');
};

The entry() calls define bundles — app for the frontend, editor for the WordPress block editor. The setPublicPath() must match where your compiled assets are accessible on the server, which depends on whether you deploy Sage as part of a full Bedrock project or as a standalone theme.

Key build commands:

yarn build                 # Production build with minification and hashing
yarn dev                   # Development build with source maps

Deployment Considerations

How you deploy Sage depends on your WordPress setup.

Full Roots stack (Bedrock + Sage): The theme lives inside web/app/themes/sage/ within the Bedrock project. You deploy the entire repository, and your build pipeline handles both Composer dependencies at the project root and Node dependencies within the theme directory. This is the recommended approach — see the Bedrock deployment guide for the full picture.

Theme-only deployment: If you are adding Sage to an existing WordPress installation without Bedrock, you deploy just the theme directory to wp-content/themes/sage/. The build pipeline runs inside the theme folder, and you need to ensure Composer autoloading and Acorn are properly configured at the theme level.

In either case, the public/ directory containing compiled assets must be included in the deployment. The node_modules/ directory should be excluded — it is only needed during the build step.

Deploying Sage with DeployHQ

DeployHQ handles the build and deployment pipeline so your server never needs Node.js or Composer installed. Use a .deploybuild.yaml file at the root of your repository to define the build steps.

For a Bedrock project with Sage:

build:
  - composer install --no-dev --optimize-autoloader
  - cd web/app/themes/sage && yarn install --frozen-lockfile && yarn build

For a standalone Sage theme:

build:
  - composer install --no-dev --optimize-autoloader
  - yarn install --frozen-lockfile
  - yarn build

Set up excluded paths in your DeployHQ project settings to keep development files off the server:

node_modules/
.github/
.bud/

Post-Deploy Commands

Add SSH commands in DeployHQ to run after each deployment:

cd /path/to/wordpress && wp acorn optimize
cd /path/to/wordpress && wp cache flush

The wp acorn optimize command pre-compiles Blade views and caches configuration. The cache flush ensures WordPress does not serve stale data after a deployment.

Enable automatic deployments in DeployHQ by connecting your repository. Every push to your deployment branch will trigger the build pipeline, compile assets, deploy files, and run post-deploy commands without manual intervention.

Getting Started

If you are starting a new project, begin with the full Roots stack: install Bedrock first, then require Sage as a theme via Composer. This gives you the cleanest project structure and the most straightforward deployment path.

For existing WordPress sites, install Sage into your wp-content/themes/ directory using Composer, run yarn install && yarn build, and activate the theme through the WordPress admin.

Either way, connect your repository to DeployHQ, configure the build pipeline with the .deploybuild.yaml examples above, and you will have automated deployments running within minutes.

Browse the full collection of deployment guides for other frameworks and platforms, or reach out if you need help configuring your pipeline.

If you need assistance, contact us at support@deployhq.com or reach out on X (@deployhq).