@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

You can add blade template files to entrypoints as if they were javascript modules.

export default async (bud) => {
  bud.entry({
    app: ["@scripts/app", "@styles/app"],
    editor: ["@scripts/editor", "@styles/editor"],
    index: ["@views/index"],
  });
};

Any modules referenced with the @asset directive will be included in the compilation.

If you wanted to include all blade templates, you could do so with bud.glob.

export default async (bud) => {
  bud.entry({
    app: [
      "@scripts/app",
      "@styles/app",
      ...(await bud.glob(`@views/**/*.blade.php`)),
    ],
    editor: ["@scripts/editor", "@styles/editor"],
  });
};

Adding scripts and styles to blade templates

You may include client scripts and styles directly in blade templates using directives. This is different than other community packages because the code is extracted and ran through the compiler This means you can write postcss, sass, typescript, etc.

@extends('layouts.app')

@section('content')
  <img src=@asset('images/404.png?as=webp') />
  <img src=@asset('images/404.png?as=webp&width=200') />
  <div id="target-el"></div>
@endsection

@js
import {render} from '@scripts/render'

ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('target-el')
);
@endjs

@css
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

body {
  @apply bg-blue-500;
}
@endcss

Current supported extensions: js, ts, css, scss, vue.

Note that in order to use ts, scss or vue you will need to have installed a bud extension that supports that language or framework.

Disable processing of blade templates

If you are not using this feature and wish to disable it, you can do so:

export default async (bud: Bud) => {
  bud.sage.processBladeTemplates(false);
};

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

Bud is an open source project and completely free to use.

However, the amount of effort needed to maintain and develop new features and projects within the Roots ecosystem is not sustainable without proper financial backing. If you have the capability, please consider sponsoring Roots.