Sage is a WordPress starter theme built by [Roots](https://roots.io/) 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](https://www.deployhq.com/guides/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](https://www.deployhq.com/signup). ## 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: ```bash 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: ```javascript 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: ```bash 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](https://www.deployhq.com/guides/bedrock) 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](https://www.deployhq.com/signup) handles the build and deployment pipeline so your server never needs Node.js or Composer installed. Use a [`.deploybuild.yaml`](https://www.deployhq.com/support/build-pipelines/deploybuild-dot-yaml) file at the root of your repository to define the build steps. For a Bedrock project with Sage: ```yaml build: - composer install --no-dev --optimize-autoloader - cd web/app/themes/sage && yarn install --frozen-lockfile && yarn build ``` For a standalone Sage theme: ```yaml 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: ```bash 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](https://www.deployhq.com/guides/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](https://www.deployhq.com/signup), 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](https://www.deployhq.com/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](mailto:support@deployhq.com) or reach out on [X (@deployhq)](https://x.com/deployhq).