Skip to content
  • Sage page

Compiling Assets

Bud is the primary project responsible for the asset workflow in Sage.

Bud is a wrapper for Webpack, and handles compiling stylesheets, checking for JavaScript errors, copying images and fonts, and concatenating and minifying files.

It also provides a fluent API that some find to be easier to interact with than Webpack itself.

Available build commands

  • yarn build — Build assets
  • yarn dev — Build assets when file changes are made, start dev session

Theme assets

What files are built and how is controlled from the bud.config.js file in the root of the theme.

In-depth discussion of how to configure Bud can be found in the Bud documentation, but Sage ships with a configuration that should provide a sufficient starting point—and depending on your use case, may not need any additional configuration.

The configuration will generate the following files:

  • app.css - The primary stylesheet for the theme.
  • app.js - The primary JavaScript file for the theme.
  • editor.css - Styles used by the editor when creating/editing posts.
  • editor.js - JavaScript for the block editor, i.e. block styles and variants.

It will also copy any files in the images or fonts directories under /resources/assets/ into the public directory with the other compiled files, but does not optimize or compress them.

Images in template files

Use the @asset directive to call images from template files:

<img src="@asset('images/example.jpg')">

Images in CSS

CSS files and images are sibling folders, so you can reference images in CSS:

.background {
  background-image: url("../images/image.jpg");

Assets in PHP

In your PHP, you can make use of the \Roots\asset() function, which is what powers the @asset directive.

$asset = \Roots\asset('images/example.jpg');

// The public URI of the asset
echo $asset;
echo $asset->uri();

// The server path of the asset
echo $asset->path();

// The contents of the asset 
echo $asset->contents();


Last updated

Support Roots

Help us continue to build and maintain our open source projects. We’re a small team of independent developers and every little bit helps.

Sponsor Roots on GitHub