@roots/sage

@roots/sage preset for @roots/bud

Installation

Install @roots/sage to your project.

Yarn:

yarn add @roots/sage --dev

npm:

npm install @roots/sage --save-dev

Included extensions

The @roots/sage extension depends on @roots/bud-preset-wordpress which in turn depends on @roots/bud-preset-recommend.

These are the packages which are installed as peers and registered by the @roots/sage main extension:

Using with eslint

Install the @roots/bud-eslint and the [@roots/eslint-config] preset package:

yarn add @roots/bud-eslint @roots/eslint-config --dev

Then, in your theme directory create a eslint.config.cjs file and include the Sage default eslint config:

module.exports = {
  root: true,
  extends: ["@roots/eslint-config/sage"],
};

Using with stylelint

Install the @roots/bud-stylelint extension:

yarn add @roots/bud-stylelint --dev

Next, in your theme directory create a .stylelintrc.js file and include the Sage default stylelint config:

module.exports = {
  extends: ["@roots/sage/stylelint", "@roots/bud-tailwindcss/stylelint"],
  rules: {
    "color-no-invalid-hex": true,
  },
};

If you aren't using @roots/bud-tailwindcss you may remove the @roots/bud-tailwindcss/stylelint value from extends.

Using with sass

Install the @roots/bud-sass extension:

yarn add @roots/bud-sass --dev

If using stylelint you will need to configure it for sass:

module.exports = {
  extends: [
    "@roots/sage/stylelint-config",
    "@roots/bud-sass/stylelint-config",
    "@roots/bud-tailwindcss/stylelint-config",
  ],
};

Handling blade @asset directives

It is probable that you have assets which are only referenced in the context of blade template files. However, by default bud.js ignores the Sage views directory. This means that bud.js will not build assets which are used only in blade template files.

The standard way of handling this predicament has been by calling bud.assets on the resources/images directory, which informs the compiler that it should include those files in the compilation.

However, as an alternative, you can opt-in to the processing of blade templates using bud.sage.copyBladeAssets. Once enabled, files referenced in blade templates using the @assets directive will be extracted and included in the compilation without the need for copying them.

export default async (bud) => {
  bud.sage.copyBladeAssets();
};

The possible downside of this approach is that it may be slower than simply copying the directory contents, especially if you have a large number of blade partials. Conversely, if you had a very large number of images in your assets directory it could significantly reduce build times. It is very project dependent and thus opt-in.

That said, compilation speed isn't the full story, and the results of this process are cached so subsequent builds and dev server builds are not really effected much either way. There are other reasons you may want to consider processing blade partials as part of your build step -- namely image optimization.

With @roots/bud-imagemin installed enabling this feature allows you to manipulate images using URL query parameters:

<div class=foo>
  <img src=@asset('images/example.png?as=webp&width=200&height=200') alt="Example image" />
</div>

This may very well turn out to be worth trading a few extra seconds for!

Contributing

Contributions are welcome from everyone.

We have contribution guidelines to help you get started.

License

@roots/sage is licensed under MIT.

Community

Keep track of development and community news.

• Join us on Roots Slack by becoming a GitHub sponsor
• Participate on the Roots Discourse
• Follow @rootswp on Twitter
• Read and subscribe to the Roots Blog
• Subscribe to the Roots Newsletter

Sponsors

Help support our open-source development efforts by becoming a patron.