# gatsby-plugin-sass

> Gatsby plugin to handle SCSS/Sass files

Latest version **6.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-plugin-sass
pnpm add gatsby-plugin-sass
yarn add gatsby-plugin-sass
bun add gatsby-plugin-sass
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: no vulnerabilities; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 6.16.0 |
| Published | 2026-01-26 |
| First published | 2017-04-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18.0.0 <26 |
| Dependencies | 3 |
| Unpacked size | 65.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 55939 |
| Author | Daniel Farrell |
| Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, fk, tylerbarnes, daniellewgatsby |
| Keywords | gatsby, gatsby-plugin, sass, scss |

## Links

- npm: https://www.npmjs.com/package/gatsby-plugin-sass
- Repository: https://github.com/gatsbyjs/gatsby
- Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sass#readme
- Issues: https://github.com/gatsbyjs/gatsby/issues
- npm.io page: https://npm.io/package/gatsby-plugin-sass

## Dependencies (3)

- [sass-loader](https://npm.io/package/sass-loader.md) ^10.4.1
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13
- [resolve-url-loader](https://npm.io/package/resolve-url-loader.md) ^3.1.5

## Recent versions

- 6.16.0 (latest) — 2026-01-26
- 6.17.0-next.0 (next) — 2025-11-27
- 6.17.0-react19.1 (react19) — 2025-11-26
- 6.13.0-alpha-alt-image-cdn.44 (alt-image-cdn) — 2023-11-03
- 6.9.0-image-cdn-configurable.4 (image-cdn-configurable) — 2023-04-11
- 4.15.0 (latest-v3) — 2022-12-07
- 5.25.0 (latest-v4) — 2022-12-07
- 6.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22
- 5.24.1-alpha-wordpress-image-err.27 (wordpress-image-err) — 2022-11-09
- 5.14.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12
- 6.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12
- 5.25.0-alpha-image-cdn-pathprefix.48 (image-cdn-pathprefix) — 2022-10-07
- 5.23.0-alpha-image-cdn-enc.40 (image-cdn-enc) — 2022-09-16
- 5.23.0-alpha-a5-peer.70 (alpha-a5-peer) — 2022-09-14
- 5.23.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08
- … 570 more at https://npm.io/package/gatsby-plugin-sass/versions

## README

# gatsby-plugin-sass

Provides drop-in support for Sass/SCSS stylesheets

## Install

`npm install sass gatsby-plugin-sass`

## How to use

1. Include the plugin in your `gatsby-config.js` file.

```javascript:title=gatsby-config.js
plugins: [`gatsby-plugin-sass`]
```

2. Write your stylesheets in Sass/SCSS and require or import them as normal.

```scss:title=src/index.scss
html {
  background-color: rebeccapurple;
  p {
    color: white;
  }
}
```

```javascript:title=gatsby-browser.js
import "./src/index.scss"
```

## Other options

If you need to pass options to Sass use the plugins options, see [`node-sass`](https://github.com/sass/node-sass)/[`dart-sass`](https://github.com/sass/dart-sass) docs
for all available options.

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sass`,
    options: {
      sassOptions: {
        includePaths: ["absolute/path/a", "absolute/path/b"],
        ...
      }
    },
  },
]
```

If you need to override the default options passed into [`css-loader`](https://github.com/webpack-contrib/css-loader).
**Note:** Gatsby is using `css-loader@^5.0.0`.

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sass`,
    options: {
      cssLoaderOptions: {
        camelCase: false,
      },
    },
  },
]
```

### additionalData

Prepends Sass code before the actual entry file. In this case, the `sass-loader` will not override the data option but just prepend the entry's content. You might use this to prepend things like environmental variables (as Sass variables) or even prepend a global Sass import to be used in other Sass files (functions, mixins, variables, etc.).

See [webpack's sass-loader documentation](https://webpack.js.org/loaders/sass-loader/#additionaldata) for reference.

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sass`,
    options: {
      additionalData: "$env: " + process.env.NODE_ENV + ";",
    },
  },
]
```

### Alternative Sass Implementations

By default, the Dart implementation of Sass (`sass`) is used. To use the implementation written in Node (`node-sass`), you can install `node-sass` instead of `sass` and pass it into the options as the implementation:

```shell
npm install node-sass
```

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sass`,
    options: {
      implementation: require("node-sass"),
    },
  },
]
```

### Sass Precision

`sass` intentionally doesn't have support for setting a custom `precision`. `node-sass` defaults to [5 digits of precision](https://github.com/sass/node-sass#precision). If you want some other level of precision (e.g. if you use Bootstrap), you may configure it as follows:

#### Bootstrap 4

See [Bootstrap's documentation on theming](https://getbootstrap.com/docs/4.3/getting-started/theming/#sass) for reference.

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sass`,
    options: {
      implementation: require("node-sass"),
      postCssPlugins: [somePostCssPlugin()],
      sassOptions: {
        precision: 6,
      },
    },
  },
]
```

#### Bootstrap 3 (with `bootstrap-sass`)

See [`bootstrap-sass`](https://github.com/twbs/bootstrap-sass/blob/master/README.md#sass-number-precision) for reference.

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sass`,
    options: {
      implementation: require("node-sass"),
      postCssPlugins: [somePostCssPlugin()],
      sassOptions: {
        precision: 8,
      },
    },
  },
]
```

### With CSS Modules

Using CSS Modules requires no additional configuration. Simply prepend `.module` to the extension. For example: `app.scss` -> `app.module.scss`.
Any file with the `module` extension will use CSS Modules. CSS modules are imported as ES Modules to support treeshaking. You'll need to import styles as: `import { yourClassName, anotherClassName } from './app.module.scss'`

## Sass & CSS Modules file Regexes

To override the file regex for Sass or CSS modules,

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sass`,
    options: {
      // Override the file regex for Sass
      sassRuleTest: /\.global\.s(a|c)ss$/,
      // Override the file regex for CSS modules
      sassRuleModulesTest: /\.mod\.s(a|c)ss$/,
    },
  },
]
```

### PostCSS plugins

PostCSS is also included to handle some default optimizations like autoprefixing
and common cross-browser flexbox bugs. Normally you don't need to think about it, but if
you'd prefer to add additional postprocessing to your Sass output you can specify plugins
in the plugin options.

## Relative paths & `url()`

This plugin resolves `url()` paths relative to the entry SCSS/Sass file not – as might be expected – the location relative to the declaration. Under the hood, it makes use of [`sass-loader`](https://github.com/webpack-contrib/sass-loader/blob/master/README.md#problems-with-url) and this is documented in the [readme](https://github.com/webpack-contrib/sass-loader/blob/master/README.md#problems-with-url).

Using [`resolve-url-loader`](https://github.com/bholloway/resolve-url-loader) provides a workaround, if you want to use relative url just install the plugin and then add it to your Sass plugin options configuration.

First:

```shell
npm install resolve-url-loader --save-dev
```

And then:

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: "gatsby-plugin-sass",
    options: {
      useResolveUrlLoader: true,
    },
  },
]
```

You can also configure `resolve-url-plugin` providing some options (see [plugin documentation](https://github.com/bholloway/resolve-url-loader) for all options):

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: "gatsby-plugin-sass",
    options: {
      useResolveUrlLoader: {
        options: {
          debug: true,
        },
      },
    },
  },
]
```

**Please note:** Adding `resolve-url-loader` will use `sourceMap: true` on `sass-loader` (as it is required for the plugin to work), you can then activate/deactivate source-map for Sass files in the plugin:

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: "gatsby-plugin-sass",
    options: {
      useResolveUrlLoader: {
        options: {
          sourceMap: true, //default is false
        },
      },
    },
  },
]
```

## Breaking changes history

<!-- Please keep the breaking changes list ordered with the newest change at the top -->

### v3.0.0

- `sass-loader` is updated to v10 which adds support for `node-sass@^5.0.0` but also switches the default `implementation` to `sass`. webpack also recommends using `sass` so this is reflected in the documentation here, too. In the [deprecation notice of node-sass](https://sass-lang.com/blog/libsass-is-deprecated#how-do-i-migrate) it is noted that switching from `node-sass` to `sass` is straightforward as both packages use the same JavaScript API.
- All options for both [`node-sass`](https://github.com/sass/node-sass#options) & [`sass`](https://github.com/sass/dart-sass/blob/master/README.md#javascript-api) are moved into the `sassOptions` object
- You're now able to override the `importLoaders` option. If you have this in your options but don't intend to override it, you'll need to remove it

### v2.0.0

- `node-sass` is moved to a peer dependency. Installing the package
  alongside `gatsby-plugin-sass` is now required. Use `npm install node-sass`

- support Gatsby v2 only

---
_Source: https://npm.io/package/gatsby-plugin-sass · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._