diff --git a/packages/gatsby-plugin-sass/README.md b/packages/gatsby-plugin-sass/README.md index 767fe24298ea8..7c33f9c5b92da 100644 --- a/packages/gatsby-plugin-sass/README.md +++ b/packages/gatsby-plugin-sass/README.md @@ -116,9 +116,62 @@ 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](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) may provide a workaround, but at present this is not in the build and implementation would demand customization. +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: + +```javascript + npm install resolve-url-loader --save-dev + or + yarn add resolve-url-loader --dev +``` + +And then: + +```javascript +plugins: [ + { + resolve: "gatsby-plugin-sass", + options: { + useResolveUrlLoader: true, + }, + }, +] +``` + +You can also configure resolve-url-plugin providing some options (see plugin documentation for all options https://github.com/bholloway/resolve-url-loader): + +```javascript +plugins: [ + { + resolve: "gatsby-plugin-sass", + 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: + +```javascript +plugins: [ + { + resolve: "gatsby-plugin-sass", + options: { + useResolveUrlLoader: { + options: { + sourceMap: true, //default is false + }, + }, + }, + }, +] +``` ## Breaking changes history diff --git a/packages/gatsby-plugin-sass/src/gatsby-node.js b/packages/gatsby-plugin-sass/src/gatsby-node.js index 0d2122a8aca7d..6bf325ba2f8b9 100644 --- a/packages/gatsby-plugin-sass/src/gatsby-node.js +++ b/packages/gatsby-plugin-sass/src/gatsby-node.js @@ -2,7 +2,7 @@ import resolve from "./resolve" exports.onCreateWebpackConfig = ( { actions, stage, rules, plugins, loaders }, - { cssLoaderOptions = {}, postCssPlugins, ...sassOptions } + { cssLoaderOptions = {}, postCssPlugins, useResolveUrlLoader, ...sassOptions } ) => { const { setWebpackConfig } = actions const PRODUCTION = stage !== `develop` @@ -11,7 +11,7 @@ exports.onCreateWebpackConfig = ( const sassLoader = { loader: resolve(`sass-loader`), options: { - sourceMap: !PRODUCTION, + sourceMap: useResolveUrlLoader ? true : !PRODUCTION, ...sassOptions, }, } @@ -27,6 +27,12 @@ exports.onCreateWebpackConfig = ( sassLoader, ], } + if (useResolveUrlLoader && !isSSR) { + sassRule.use.splice(-1, 0, { + loader: `resolve-url-loader`, + options: useResolveUrlLoader.options ? useResolveUrlLoader.options : {}, + }) + } const sassRuleModules = { test: /\.module\.s(a|c)ss$/, use: [