diff --git a/packages/gatsby-plugin-sass/README.md b/packages/gatsby-plugin-sass/README.md index 83ad3d828bc8d..2a7cb87e8e087 100644 --- a/packages/gatsby-plugin-sass/README.md +++ b/packages/gatsby-plugin-sass/README.md @@ -64,6 +64,23 @@ plugins: [ ] ``` +### 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: diff --git a/packages/gatsby-plugin-sass/src/__tests__/__snapshots__/gatsby-node.js.snap b/packages/gatsby-plugin-sass/src/__tests__/__snapshots__/gatsby-node.js.snap index 41deb873c2b55..31a5f203cd130 100644 --- a/packages/gatsby-plugin-sass/src/__tests__/__snapshots__/gatsby-node.js.snap +++ b/packages/gatsby-plugin-sass/src/__tests__/__snapshots__/gatsby-node.js.snap @@ -17,6 +17,7 @@ exports[`gatsby-plugin-sass Stage: build-html / No options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -30,6 +31,7 @@ exports[`gatsby-plugin-sass Stage: build-html / No options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -69,6 +71,7 @@ exports[`gatsby-plugin-sass Stage: build-html / PostCss plugins 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -82,6 +85,7 @@ exports[`gatsby-plugin-sass Stage: build-html / PostCss plugins 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -121,6 +125,7 @@ exports[`gatsby-plugin-sass Stage: build-html / Sass options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object { "includePaths": Array [ "absolute/path/a", @@ -139,6 +144,7 @@ exports[`gatsby-plugin-sass Stage: build-html / Sass options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object { "includePaths": Array [ "absolute/path/a", @@ -183,6 +189,7 @@ exports[`gatsby-plugin-sass Stage: build-html / css-loader options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -196,6 +203,7 @@ exports[`gatsby-plugin-sass Stage: build-html / css-loader options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -235,6 +243,7 @@ exports[`gatsby-plugin-sass Stage: build-html / css-loader use commonjs 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -248,6 +257,7 @@ exports[`gatsby-plugin-sass Stage: build-html / css-loader use commonjs 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -287,6 +297,7 @@ exports[`gatsby-plugin-sass Stage: build-html / sass rule modules test options 1 Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -300,6 +311,7 @@ exports[`gatsby-plugin-sass Stage: build-html / sass rule modules test options 1 Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -339,6 +351,7 @@ exports[`gatsby-plugin-sass Stage: build-html / sass rule test options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -352,6 +365,7 @@ exports[`gatsby-plugin-sass Stage: build-html / sass rule test options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -392,6 +406,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / No options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -407,6 +422,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / No options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -447,6 +463,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / PostCss plugins 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -462,6 +479,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / PostCss plugins 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -502,6 +520,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / Sass options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object { "includePaths": Array [ "absolute/path/a", @@ -522,6 +541,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / Sass options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object { "includePaths": Array [ "absolute/path/a", @@ -567,6 +587,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / css-loader options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -582,6 +603,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / css-loader options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -622,6 +644,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / css-loader use commonjs 1` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -637,6 +660,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / css-loader use commonjs 1` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -677,6 +701,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / sass rule modules test opt Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -692,6 +717,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / sass rule modules test opt Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -732,6 +758,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / sass rule test options 1`] Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -747,6 +774,7 @@ exports[`gatsby-plugin-sass Stage: build-javascript / sass rule test options 1`] Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -787,6 +815,7 @@ exports[`gatsby-plugin-sass Stage: develop / No options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -802,6 +831,7 @@ exports[`gatsby-plugin-sass Stage: develop / No options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -842,6 +872,7 @@ exports[`gatsby-plugin-sass Stage: develop / PostCss plugins 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -857,6 +888,7 @@ exports[`gatsby-plugin-sass Stage: develop / PostCss plugins 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -897,6 +929,7 @@ exports[`gatsby-plugin-sass Stage: develop / Sass options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object { "includePaths": Array [ "absolute/path/a", @@ -917,6 +950,7 @@ exports[`gatsby-plugin-sass Stage: develop / Sass options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object { "includePaths": Array [ "absolute/path/a", @@ -962,6 +996,7 @@ exports[`gatsby-plugin-sass Stage: develop / css-loader options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -977,6 +1012,7 @@ exports[`gatsby-plugin-sass Stage: develop / css-loader options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1017,6 +1053,7 @@ exports[`gatsby-plugin-sass Stage: develop / css-loader use commonjs 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1032,6 +1069,7 @@ exports[`gatsby-plugin-sass Stage: develop / css-loader use commonjs 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1072,6 +1110,7 @@ exports[`gatsby-plugin-sass Stage: develop / sass rule modules test options 1`] Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1087,6 +1126,7 @@ exports[`gatsby-plugin-sass Stage: develop / sass rule modules test options 1`] Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1127,6 +1167,7 @@ exports[`gatsby-plugin-sass Stage: develop / sass rule test options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1142,6 +1183,7 @@ exports[`gatsby-plugin-sass Stage: develop / sass rule test options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1181,6 +1223,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / No options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1194,6 +1237,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / No options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1233,6 +1277,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / PostCss plugins 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1246,6 +1291,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / PostCss plugins 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1285,6 +1331,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / Sass options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object { "includePaths": Array [ "absolute/path/a", @@ -1303,6 +1350,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / Sass options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object { "includePaths": Array [ "absolute/path/a", @@ -1347,6 +1395,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / css-loader options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1360,6 +1409,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / css-loader options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1399,6 +1449,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / css-loader use commonjs 1`] = Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1412,6 +1463,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / css-loader use commonjs 1`] = Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1451,6 +1503,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / sass rule modules test options Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1464,6 +1517,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / sass rule modules test options Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1503,6 +1557,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / sass rule test options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, @@ -1516,6 +1571,7 @@ exports[`gatsby-plugin-sass Stage: develop-html / sass rule test options 1`] = ` Object { "loader": "/node_modules/sass-loader/dist/cjs.js", "options": Object { + "additionalData": undefined, "sassOptions": Object {}, "sourceMap": undefined, }, diff --git a/packages/gatsby-plugin-sass/src/__tests__/gatsby-node.js b/packages/gatsby-plugin-sass/src/__tests__/gatsby-node.js index 74a9e2554a293..51fa2fbcaf325 100644 --- a/packages/gatsby-plugin-sass/src/__tests__/gatsby-node.js +++ b/packages/gatsby-plugin-sass/src/__tests__/gatsby-node.js @@ -73,6 +73,7 @@ describe(`pluginOptionsSchema`, () => { it(`should provide meaningful errors when fields are invalid`, async () => { const expectedErrors = [ `"implementation" must be of type object`, + `"additionalData" must be one of [string, object]`, `"cssLoaderOptions" must be of type object`, `"postCssPlugins" must be an array`, `"sassRuleTest" must be of type object`, @@ -99,6 +100,7 @@ describe(`pluginOptionsSchema`, () => { ] const { errors } = await testPluginOptionsSchema(pluginOptionsSchema, { + additionalData: 123, implementation: `This should be a require() thing`, postCssPlugins: `This should be an array of postCss plugins`, cssLoaderOptions: `This should be an object of css-loader options`, @@ -132,6 +134,7 @@ describe(`pluginOptionsSchema`, () => { it(`should validate the schema`, async () => { const { isValid } = await testPluginOptionsSchema(pluginOptionsSchema, { + additionalData: `$test: #000;`, implementation: require(`../gatsby-node.js`), cssLoaderOptions: { camelCase: false }, postCssPlugins: [require(`autoprefixer`)], diff --git a/packages/gatsby-plugin-sass/src/gatsby-node.js b/packages/gatsby-plugin-sass/src/gatsby-node.js index dc8bd2f05be7b..e752aca9e11e9 100644 --- a/packages/gatsby-plugin-sass/src/gatsby-node.js +++ b/packages/gatsby-plugin-sass/src/gatsby-node.js @@ -11,6 +11,7 @@ exports.onCreateWebpackConfig = ( sassOptions = {}, // eslint-disable-next-line no-unused-vars plugins, + additionalData = undefined, ...sassLoaderOptions } ) => { @@ -22,6 +23,7 @@ exports.onCreateWebpackConfig = ( options: { sourceMap: useResolveUrlLoader ? true : undefined, sassOptions, + additionalData, ...sassLoaderOptions, }, } @@ -94,6 +96,11 @@ exports.pluginOptionsSchema = function ({ Joi }) { .description( `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` ), + additionalData: Joi.alternatives() + .try(Joi.string(), Joi.function()) + .description( + `Prepends Sass/SCSS 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. Learn more at: https://webpack.js.org/loaders/sass-loader/#additionaldata` + ), cssLoaderOptions: Joi.object({}) .unknown(true) .description(