sass-resources-loader

What is sass-resources-loader?

The sass-resources-loader npm package is a Webpack loader that allows you to inject shared Sass resources (such as variables, mixins, and functions) into every Sass file in your project without needing to manually import them in each file. This can help maintain consistency and reduce redundancy in your stylesheets.

What are sass-resources-loader's main functionalities?

Injecting Global Sass Resources

This feature allows you to inject global Sass resources into every Sass file in your project. By specifying the path to your resources file in the `resources` option, you ensure that variables, mixins, and functions defined in that file are available in all your Sass files without needing to import them manually.

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          'sass-loader',
          {
            loader: 'sass-resources-loader',
            options: {
              resources: './path/to/resources.scss'
            }
          }
        ]
      }
    ]
  }
};

Multiple Resource Files

This feature allows you to specify multiple resource files to be injected into every Sass file. By providing an array of file paths in the `resources` option, you can include multiple sets of variables, mixins, and functions, making them globally available throughout your project.

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          'sass-loader',
          {
            loader: 'sass-resources-loader',
            options: {
              resources: [
                './path/to/variables.scss',
                './path/to/mixins.scss'
              ]
            }
          }
        ]
      }
    ]
  }
};

Using with Different Loaders

This feature demonstrates how to use sass-resources-loader in conjunction with other loaders like `postcss-loader`. This allows you to integrate global Sass resources while still taking advantage of other CSS processing tools in your Webpack configuration.

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          'postcss-loader',
          'sass-loader',
          {
            loader: 'sass-resources-loader',
            options: {
              resources: './path/to/resources.scss'
            }
          }
        ]
      }
    ]
  }
};

Other packages similar to sass-resources-loader

sass-loader

sass-loader is a Webpack loader that compiles Sass to CSS. While it does not provide the same functionality for injecting global resources as sass-resources-loader, it is often used in conjunction with it to handle the actual Sass compilation.

style-resources-loader

style-resources-loader is another Webpack loader that can inject shared resources into your stylesheets. It supports multiple preprocessors including Sass, Less, and Stylus, making it more versatile if you are working with different CSS preprocessors.

postcss-import

postcss-import is a PostCSS plugin that allows you to inline the content of imported files. While it is not specific to Sass, it can be used to achieve similar results by inlining shared resources into your CSS files.

README

sass-resources-loader

This loader will load your SASS resources into every required SASS module. So you can use your shared variables, mixins and functions across all SASS styles without manually loading them in each file.

• Made to work with CSS Modules!
• This loader is not limited to Sass resources. It supposedly works with less, post-css, etc. per issue 31.
• Supports Webpack 4
• Supports Sass @use syntax. You must use Dart Sass (sass, not node-sass npm package). See the hoistUseStatements option.

About

This project is maintained by the software consulting firm ShakaCode. We focus on Ruby on Rails applications with React front-ends, often using TypeScript or ReasonML. We also build Gatsby sites. See our recent work for examples of what we do. Feel free to contact Justin Gordon, [e-mail], for more information.

Slack Room: Click for a Slack invite.

---

Installation

Get it via npm:

npm install sass-resources-loader

Usage

Create your file (or files) with resources, which are snippets of Sass that you want available to places like CSS modules Sass:

/* resources.scss */

$section-width: 700px;

@mixin section-mixin {
  margin: 0 auto;
  width: $section-width;
}

Options

Name	Type	Default	Description
resources	{String|String[]}	undefined	Resources to include in files
hoistUseStatements	{Boolean}	false	If true, entry file @use imports will be hoisted. This means the @use statements will go above the inclusion of resources.

Option Examples

resources

Specify resources, contents of these will be prepended to each file.

If file example/a.scss has content of $my-variable: #fff, we could do this

{
    loader: 'sass-resources-loader',
    options: {
        resources: 'example/a.scss'
    }
}

This would output the following:

// Entry file

$my-variable: #fff;

// Entry file's contents go here

hoistUseStatements

Tells the compiler if an existing @use statement is found in entry file, it should be hoisted to the top. The reason is that @use must go before most other declarations, except variable declarations, per the docs.

If our entry file has the following content

// Entry file
@use 'my/definitions/file';
@use 'my/other/definitions/file';

// Entry file's contents go here

and our resource file contains this

$my-variable: #fff;

@mixin some-mixin {
    color: #000;
}

Then the output, with hoistUseStatements set to true would be the following. Note that the @use statements are above the inclusion of resources.

// Entry file
@use 'my/definitions/file';
@use 'my/other/definitions/file';

// Resources
$my-variable: #fff;

@mixin some-mixin {
    color: #000;
}

// Rest of entry file's content goes here

You can also use this multi-line syntax:

@use 'config' with (
    $text-color: #FAFAFA
);

See ./test/scss/hoist-multiline.scss for an example.

As mentioned in the docs for Sass @use, you don't need to hoist if your "resources" only contains variable definitions.

If you get the error:

SassError: @use rules must be written before any other rules.

then you need to use the hoistUseStatements: true option.

Tips

• Do not include anything that will be actually rendered in CSS, because it will be added to every imported Sass file.
• Avoid using Sass import rules inside resources files as it slows down incremental builds. Add imported files directly in sassResources array in webpack config instead. If you concerned about location of your resources index, you might want to check out the solution outlined in this comment.
• If you still want to use Sass import rules make sure your paths are relative to the file they defined in (basically, your file with resources), except the ones started with ~ (~ is resolved to node_modules folder).

Apply loader in webpack config (v1.x.x & v2.x.x are supported) and provide path to the file with resources:

/* Webpack@2: webpack.config.js */

module: {
  rules: [
    // Apply loader
    {
      test: /\.scss$/,
      use: [
        'style-loader',
        'css-loader',
        'postcss-loader',
        'sass-loader',
        {
          loader: 'sass-resources-loader',
          options: {
            // Provide path to the file with resources
            resources: './path/to/resources.scss',

            // Or array of paths
            resources: [
              './path/to/vars.scss',
              './path/to/mixins.scss',
              './path/to/functions.scss'
            ]
          },
        },
      ],
    },
  ],
},

/* Webpack@1: webpack.config.js */

module: {
  loaders: [
    // Apply loader
    { test: /\.scss$/, loader: 'style!css!sass!sass-resources' },
  ],
},

// Provide path to the file with resources
sassResources: './path/to/resources.scss',

// Or array of paths
sassResources: ['./path/to/vars.scss', './path/to/mixins.scss'],

NOTE: If webpackConfig.context is not defined, process.cwd() will be used to resolve files with resource.

Now you can use these resources without manually loading them:

/* component.scss */

.section {
  @include section-mixin; // <--- `section-mixin` is defined here
}

import React from 'react';
import css from './component.scss';

// ...

render() {
  return (
    <div className={css.section} />
  );
}

Glob pattern matching

You can specify glob patterns to match your all of your files in the same directory.

// Specify a single path
resources: './path/to/resources/**/*.scss', // will match all files in folder and subdirectories
// or an array of paths
resources: [ './path/to/resources/**/*.scss', './path/to/another/**/*.scss' ]

Note that sass-resources-loader will resolve your files in order. If you want your variables to be accessed across all of your mixins you should specify them in first place.

resources: [ './path/to/variables/vars.scss', './path/to/mixins/**/*.scss' ]

Examples and Related Libraries

• react-webpack-rails-tutorial, live example at www.reactrails.com.
• bootstrap-loader

Example of Webpack 4 Config for Vue

  module: {
    rules: [
      {
        test: /\.vue$/,
        use: 'vue-loader'
      },
      {
        test: /\.css$/,
        use: [
          { loader: 'vue-style-loader' },
          { loader: 'css-loader', options: { sourceMap: true } },
        ]
      },
      {
        test: /\.scss$/,
        use: [
          { loader: 'vue-style-loader' },
          { loader: 'css-loader', options: { sourceMap: true } },
          { loader: 'sass-loader', options: { sourceMap: true } },
          { loader: 'sass-resources-loader',
            options: {
              sourceMap: true,
              resources: [
                resolveFromRootDir('src/styles/variables.scss'),
              ]
            }
          }
        ]
      }
    ]
  }

VueJS webpack template(vue-cli@2)

If you wish to use this loader in the VueJS Webpack template you need to add the following code in build/utils.js after line 42 :

if (loader === 'sass') {
  loaders.push({
    loader: 'sass-resources-loader',
    options: {
      resources: 'path/to/your/file.scss',
    },
  });
}

VueJS webpack template(vue-cli@3)

If you are using vue-cli@3, you need create a vue.config.js file in your project root(next to package.json). Then, add the following code :

// vue.config.js
module.exports = {
  chainWebpack: config => {
    const oneOfsMap = config.module.rule('scss').oneOfs.store
    oneOfsMap.forEach(item => {
      item
        .use('sass-resources-loader')
        .loader('sass-resources-loader')
        .options({
          // Provide path to the file with resources
          resources: './path/to/resources.scss',

          // Or array of paths
          resources: ['./path/to/vars.scss', './path/to/mixins.scss', './path/to/functions.scss']
        })
        .end()
    })
  }
}

Contributing

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

See Contributing to get started.

License

sass-resources-loader is available under MIT. See LICENSE for more details.

Changelog

[2.2.5] - 2022-04-14

• Update async to v3.2.3. #154 by Ian Hutchinson.