@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.

All told, these are the extensions which are installed as peers of @roots/sage:

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-config",
    "@roots/bud-tailwindcss/stylelint-config",
  ],
  rules: {
    "color-no-invalid-hex": true,
  },
};

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

Managing theme.json

You can manage WordPress' theme.json config file from the context of your bud config using bud.wptheme.

Enabling theme.json support

In order to emit the file you will need to enable the feature:

bud.wpjson.enable();

Managing generic theme.json values

You can use setOption from the bud.js extensions API to set theme.json values:

bud.wpjson.setOption("customTemplates", []).enable();

Managing the settings field

Most theme.json configuration centers around the settings property. You can modify these values using a fluent container interface exposed by bud.wpjson.settings.

bud.wptheme
  .settings((theme) =>
    theme
      .set("typography.customFontSizes", true)
      .set("typography.fontWeight", false)
      .merge("spacing.units", ["px", "%", "em"])
  )
  .enable();

Using tailwindcss config values

If you use @roots/bud-tailwindcss in your project there are several opt-in config functions that allow you to generate theme.json values directly from your tailwind config.

wpjson.useTailwindColors()

Convert theme.colors to a theme.json palette.

bud.wpjson.useTailwindColors().enable();

wpjson.useTailwindFontSize()

Emits values from theme.fontSize as the typography.fontSizes property of theme.json.

bud.wpjson.useTailwindFontSize().enable();

wpjson.useTailwindFontFamily()

Emits values from theme.fontFamily as the typography.fontFamilies property of theme.json.

bud.wpjson.useTailwindFontFamily().enable();

Limiting values to those defined in theme.extend

You can pass true to any of the the above functions to limit the values emitted to those defined under tailwind's theme.extend key.

bud.wpjson.useTailwindColors(true).enable();

In combination

You can use any of these methods in combination:

bud.wpjson
  .useTailwindColors()
  .useTailwindFontSize()
  .useTailwindFontFamily()
  .setOption("typography.fontWeight", false)
  .enable();

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",
  ],
};

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.