@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

Usage

Documentation for this package is available on bud.js.org. It may include additional context and information not available in this README.

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"],
  rules: {
    "color-no-invalid-hex": true,
  },
};

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 tailwindcss in your project there are several opt-in helpers that allow you to generate theme.json values directly from your tailwind config.

:::caution

This only works if the values are literally expressed in your config. Your config is not processed by postcss before theme.json is emitted.

:::

wpjson.useTailwindColors

Convert theme.extends.colors to a theme.json palette.

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

wpjson.useTailwindFontSize()

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

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

wpjson.useTailwindFontFamily()

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

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

In combination

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

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.