@roots/bud-sass

Sass support for @roots/bud projects.

---

Installation

Install @roots/bud-sass to your project.

Yarn:

yarn add @roots/bud-sass --dev

npm:

npm install @roots/bud-sass --save-dev

Basic usage

After installation, sass will automatically preprocess any .scss or .sass modules in your project with sass.

Additionally, if @roots/bud-postcss is available, postcss will be applied to your .scss and .sass source files.

If you are using @roots/bud-preset-recommend, @roots/bud-preset-wordpress, or @roots/sage then postcss is automatically applied.

Global imports

Use the bud.sass.importGlobal function to ensure a module is made available throughout your sass stylesheets, regardless of scope.

bud.sass.importGlobal("@src/styles/variables");

If you have more than one stylesheet to import, you may use an array:

bud.sass.importGlobal([
  "@src/styles/variables",
  "@src/styles/mixins",
  "@src/styles/functions",
]);

Global values

Use the bud.sass.registerGlobal function to ensure global styles are made available throughout your sass stylesheets, regardless of scope.

This function differs from bud.sass.importGlobal in that it can be passed arbitrary values.

bud.sass.registerGlobal("$foo: rgba(0, 0, 0, 1);");

If you want to divide these values up using an array, you may do so.

bud.sass.registerGlobal([
  "$foo: rgba(0, 0, 0, 1);",
  "$bar: rgba(255, 255, 255, 1);",
]);

URL imports

When using @roots/bud-sass, you will find that the url() function is not working as expected. This is because the url() function is relative to the target file, not the source file and Sass does not support url rewriting.

A few options are available to work around this.

Strategies

prefix with ~

The ~ prefix is a convention used to indicate that the path should be resolved by webpack. It works with aliases.

Let's say you have an alias set up for @fonts:

url(~@fonts/muh-font.woff)

use an absolute path

bud.js will resolve absolute paths to whatever you have set as the @src directory.

url(/fonts/muh-font.woff)

use a relative path

This is the simplest option to understand and the most annoying to maintain. It is on you to ensure that the relative path is correct.

url(../fonts/muh-font.woff)

Contributing

Contributions are welcome from everyone.

We have contribution guidelines to help you get started.

License

@roots/bud-sass 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.