Provides drop-in support for scoped and unscoped SASS/SCSS stylesheets
npm install --save node-sass gatsby-plugin-sass-scoped
or
yarn add node-sass gatsby-plugin-sass-scoped
- Include the plugin in your
gatsby-config.js
file.
plugins: [`gatsby-plugin-sass-scoped`]
- Write your stylesheets in Sass/SCSS and attached
.scoped
to the file name to identify it scoped/unscoped and require or import them as normal.
.wrapper {
max-width: 1200px;
}
// Unscoped
import("./component/index.scss")
// Scoped
import("./component/index.scoped.scss")
If you need to pass options to Sass use the plugins options, see node-sass/dart-sass docs for all available options.
plugins: [
{
resolve: `gatsby-plugin-sass-scoped`,
options: {
includePaths: ["absolute/path/a", "absolute/path/b"],
...
},
},
]
If you need to override the default options passed into css-loader
:
plugins: [
{
resolve: `gatsby-plugin-sass-scoped`,
options: {
cssLoaderOptions: {
camelCase: false,
},
},
},
]
By default the node implementation of Sass (node-sass
) is used. To use the implementation written in Dart (dart-sass
), you can install sass
instead of node-sass
and pass it into the options as the implementation:
npm install --save-dev sass
plugins: [
{
resolve: `gatsby-plugin-sass-scoped`,
options: {
implementation: require("sass"),
},
},
]
SASS defaults to 10 digits of precision. If you want some other level of precision (e.g. if you use Bootstrap), you may configure it as follows:
See Bootstrap's documentation on theming for reference.
plugins: [
{
resolve: `gatsby-plugin-sass-scoped`,
options: {
postCssPlugins: [somePostCssPlugin()],
precision: 6,
},
},
]
See bootstrap-sass
for reference.
plugins: [
{
resolve: `gatsby-plugin-sass-scoped`,
options: {
postCssPlugins: [somePostCssPlugin()],
precision: 8,
},
},
]
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.
To override the file regex for SASS or CSS modules,
plugins: [
{
resolve: `gatsby-plugin-sass-scoped`,
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 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.
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 and this is documented in the readme.
Using 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:
npm install resolve-url-loader --save-dev
And then:
plugins: [
{
resolve: "gatsby-plugin-sass-scoped",
options: {
useResolveUrlLoader: true,
},
},
]
You can also configure resolve-url-plugin providing some options (see plugin documentation for all options):
plugins: [
{
resolve: "gatsby-plugin-sass-scoped",
options: {
useResolveUrlLoader: {
options: {
debug: true,
},
},
},
},
]
NOTE that 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:
plugins: [
{
resolve: "gatsby-plugin-sass-scoped",
options: {
useResolveUrlLoader: {
options: {
sourceMap: true, //default is false
},
},
},
},
]
- support Gatsby v2 only