Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Compiles Sass to CSS

License

NotificationsYou must be signed in to change notification settings

webpack/sass-loader

npmnodetestscoveragediscussionsizediscord-invite

sass-loader

Loads a Sass/SCSS file and compiles it to CSS.

Getting Started

To begin, you'll need to installsass-loader:

npm install sass-loader sass webpack --save-dev

or

yarn add -D sass-loader sass webpack

or

pnpm add -D sass-loader sass webpack

Note

To enable CSS processing in your project, you need to installstyle-loader andcss-loader vianpm i style-loader css-loader.

sass-loader requires you to install eitherDart Sass,Node Sass on your own (more documentation can be found below) orSass Embedded.

This allows you to control the versions of all your dependencies and to choose which Sass implementation to use.

Note

We highly recommend usingSass Embedded orDart Sass.

Warning

Node Sass does not work withYarn PnP and doesn't support@use rule.

Chain thesass-loader with thecss-loader and thestyle-loader to immediately apply all styles to the DOM, or with themini-css-extract-plugin to extract it into a separate file.

Then add the loader to your webpack configuration. For example:

app.js

import"./style.scss";

style.scss

$body-color:red;body {color:$body-color;}

webpack.config.js

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:[// Creates `style` nodes from JS strings"style-loader",// Translates CSS into CommonJS"css-loader",// Compiles Sass to CSS"sass-loader",],},],},};

Finally runwebpack via your preferred method (e.g., via CLI or an npm script).

Thestyle (new API, by default since 16 version) andoutputStyle (old API) options inproduction mode

Forproduction mode, thestyle (new API, by default since 16 version) andoutputStyle (old API) options default tocompressed unless otherwise specified insassOptions.

Resolvingimport anduse at-rules

Webpack provides anadvanced mechanism to resolve files.

Thesass-loader uses Sass's custom importer feature to pass all queries to the webpack resolving engine, enabling you to import your Sass modules fromnode_modules.

@import"bootstrap";

Using~ is deprecated and should be removed from your code, but we still support it for historical reasons.

Why can you remove it? The loader will first try to resolve@import as a relative path. If it cannot be resolved, then the loader will try to resolve@import insidenode_modules.

Prepending module paths with a~ tells webpack to search throughnode_modules.

@import"~bootstrap";

It's important to prepend the path with only~, because~/ resolves to the home directory.

Webpack needs to distinguish betweenbootstrap and~bootstrap because CSS and Sass files have no special syntax for importing relative files.

Writing@import "style.scss" is the same as@import "./style.scss";

Problems withurl(...)

Since Sass implementations don't provideurl rewriting, all linked assets must be relative to the output.

  • If you pass the generated CSS on to thecss-loader, all URLs must be relative to the entry-file (e.g.main.scss).
  • If you're just generating CSS without passing it to thecss-loader, URLs must be relative to your web root.

You might be surprised by this first issue, as it is natural to expect relative references to be resolved against the.sass/.scss file in which they are specified (like in regular.css files).

Thankfully there are two solutions to this problem:

  • Add the missing URL rewriting using theresolve-url-loader. Place it beforesass-loader in the loader chain.

  • Library authors usually provide a variable to modify the asset path.bootstrap-sass for example, has an$icon-font-path.

Options

implementation

Type:

typeimplementation=object|string;

Default:sass

The specialimplementation option determines which implementation of Sass to use.

By default, the loader resolves the implementation based on your dependencies.Just add the desired implementation to yourpackage.json (sass,sass-embedded, ornode-sass package) and install dependencies.

Example where thesass-loader uses thesass (dart-sass) implementation:

package.json

{"devDependencies": {"sass-loader":"^7.2.0","sass":"^1.22.10"  }}

Example where thesass-loader uses thenode-sass implementation:

package.json

{"devDependencies": {"sass-loader":"^7.2.0","node-sass":"^5.0.0"  }}

Example where thesass-loader uses thesass-embedded implementation:

package.json

{"devDependencies": {"sass-loader":"^7.2.0","sass":"^1.22.10"  },"optionalDependencies": {"sass-embedded":"^1.70.0"  }}

Note

UsingoptionalDependencies means thatsass-loader can fallback tosass when running on an operating system not supported bysass-embedded

Be aware of the order thatsass-loader will resolve the implementation:

  1. sass-embedded
  2. sass
  3. node-sass

You can specify a specific implementation by using theimplementation option, which accepts one of the above values.

object

For example, to always useDart Sass, you'd pass:

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{// Prefer `dart-sass`, even if `sass-embedded` is availableimplementation:require("sass"),},},],},],},};

string

For example, to use Dart Sass, you'd pass:

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{// Prefer `dart-sass`, even if `sass-embedded` is availableimplementation:require.resolve("sass"),},},],},],},};

sassOptions

Type:

typesassOptions=|import("sass").LegacyOptions<"async">|((content:string|Buffer,loaderContext:LoaderContext,meta:any,)=>import("sass").LegacyOptions<"async">);

Default: defaults values for Sass implementation

Options forDart Sass orNode Sass implementation.

Note

Thecharset option istrue by default fordart-sass. We strongly discourage setting this tofalse because webpack doesn't support files other thanutf-8.

Note

Thesyntax (new API, by default since 16 version) andindentedSyntax (old API) option isscss for thescss extension,indented for thesass extension, andcss for thecss extension.

Note

Options such asdata andfile are unavailable and will be ignored.

ℹ We strongly discourage changing thesourceMap (new API, by default since 16 version),outFile (old API),sourceMapContents (old API),sourceMapEmbed (old API), andsourceMapRoot (old API) options becausesass-loader sets these automatically when thesourceMap option istrue.

Note

Access to theloader context inside the custom importer can be done using thethis.webpackLoaderContext property.

There is a slight difference between the options forsass (dart-sass) andnode-sass.

Please consult their respective documentation before using them:

object

Use an object for the Sass implementation setup.

webpack.config.js

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{sassOptions:{style:"compressed",loadPaths:["absolute/path/a","absolute/path/b"],},},},],},],},};

function

Allows configuring the Sass implementation with different options based on the loader context.

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{sassOptions:(loaderContext)=>{// More information about available properties https://webpack.js.org/api/loaders/const{ resourcePath, rootContext}=loaderContext;constrelativePath=path.relative(rootContext,resourcePath);if(relativePath==="styles/foo.scss"){return{loadPaths:["absolute/path/c","absolute/path/d"],};}return{loadPaths:["absolute/path/a","absolute/path/b"],};},},},],},],},};

sourceMap

Type:

typesourceMap=boolean;

Default: depends on thecompiler.devtool value

Enables/disables generation of source maps.

By default generation of source maps depends on thedevtool option.All values enable source map generation excepteval andfalse.

ℹ Iftrue, thesourceMap (new API, by default since 16 version),outFile (old API),sourceMapContents (old API),sourceMapEmbed (old API), andsourceMapRoot (old API) fromsassOptions will be ignored.

webpack.config.js

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader",{loader:"css-loader",options:{sourceMap:true,},},{loader:"sass-loader",options:{sourceMap:true,},},],},],},};

ℹ In some rare casesnode-sass can output invalid source maps (this is anode-sass bug).

In order to avoid this, you can try to updatenode-sass to the latest version, or you can try to set withinsassOptions theoutputStyle option tocompressed.

webpack.config.js

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{sourceMap:true,sassOptions:{outputStyle:"compressed",},},},],},],},};

additionalData

Type:

typeadditionalData=|string|((content:string|Buffer,loaderContext:LoaderContext)=>string);

Default:undefined

PrependsSass/SCSS code before the actual entry file.In this case, thesass-loader will not override thedata option but justprepend the entry's content.

This is especially useful when some of your Sass variables depend on the environment:

string

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{additionalData:`$env:${process.env.NODE_ENV};`,},},],},],},};

function

Sync
module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{additionalData:(content,loaderContext)=>{// More information about available properties https://webpack.js.org/api/loaders/const{ resourcePath, rootContext}=loaderContext;constrelativePath=path.relative(rootContext,resourcePath);if(relativePath==="styles/foo.scss"){return`$value: 100px;${content}`;}return`$value: 200px;${content}`;},},},],},],},};
Async
module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{additionalData:async(content,loaderContext)=>{// More information about available properties https://webpack.js.org/api/loaders/const{ resourcePath, rootContext}=loaderContext;constrelativePath=path.relative(rootContext,resourcePath);if(relativePath==="styles/foo.scss"){return`$value: 100px;${content}`;}return`$value: 200px;${content}`;},},},],},],},};

webpackImporter

Type:

typewebpackImporter=boolean;

Default:true

Enables/disables the default webpack importer.

This can improve performance in some cases, though use it with caution because aliases and@import at-rules starting with~ will not work.You can pass your ownimporter to solve this (seeimporter docs).

webpack.config.js

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{webpackImporter:false,},},],},],},};

warnRuleAsWarning

Type:

typewarnRuleAsWarning=boolean;

Default:true

Treats the@warn rule as a webpack warning.

style.scss

$known-prefixes: webkit, moz, ms, o;@mixinprefix($property,$value,$prefixes) {@each$prefixin$prefixes {@ifnotindex($known-prefixes,$prefix) {@warn"Unknown prefix#{$prefix}.";    }-#{$prefix}-#{$property}:$value;  }#{$property}:$value;}.tilt {// Oops, we typo'd "webkit" as "wekbit"!@includeprefix(transform,rotate(15deg), wekbit ms);}

The presented code will throw a webpack warning instead of logging.

To ignore unnecessary warnings you can use theignoreWarnings option.

webpack.config.js

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{warnRuleAsWarning:true,},},],},],},};

api

Type:

typeapi="legacy"|"modern"|"modern-compiler";

Default:"modern" forsass (dart-sass) andsass-embedded, or"legacy" fornode-sass

Allows you to switch between thelegacy andmodern APIs. You can find more informationhere. Themodern-compiler option enables the modern API with support forShared Resources.

Note

Usingmodern-compiler andsass-embedded together significantly improves performance and decreases build time. We strongly recommend their use. We will enable them by default in a future major release.

Warning

The Sass options are different for thelegacy andmodern APIs. Please look atdocs to learn how to migrate to the modern options.

webpack.config.js

module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader","css-loader",{loader:"sass-loader",options:{api:"modern-compiler",sassOptions:{// Your sass options},},},],},],},};

How to enable@debug output

By default, the output of@debug messages is disabled.Add the following towebpack.config.js to enable them:

module.exports={stats:{loggingDebug:["sass-loader"],},// ...};

Examples

Extracts CSS into separate files

For production builds, it's recommended to extract the CSS from your bundle to enable parallel loading of CSS/JS resources.

There are four recommended ways to extract a stylesheet from a bundle:

webpack.config.js

constMiniCssExtractPlugin=require("mini-css-extract-plugin");module.exports={module:{rules:[{test:/\.s[ac]ss$/i,use:[// fallback to style-loader in developmentprocess.env.NODE_ENV!=="production"            ?"style-loader"            :MiniCssExtractPlugin.loader,"css-loader","sass-loader",],},],},plugins:[newMiniCssExtractPlugin({// Options similar to the same options in webpackOptions.output// both options are optionalfilename:"[name].css",chunkFilename:"[id].css",}),],};

webpack.config.js

constpath=require("node:path");module.exports={entry:[path.resolve(__dirname,"./src/scss/app.scss")],module:{rules:[{test:/\.js$/,exclude:/node_modules/,use:[],},{test:/\.scss$/,exclude:/node_modules/,type:"asset/resource",generator:{filename:"bundle.css",},use:["sass-loader"],},],},};

3.extract-loader (simpler, but specialized on the css-loader's output)

4.file-loader (deprecated--should only be used in webpack v4)

webpack.config.js

constpath=require("node:path");module.exports={entry:[path.resolve(__dirname,"./src/scss/app.scss")],module:{rules:[{test:/\.js$/,exclude:/node_modules/,use:[],},{test:/\.scss$/,exclude:/node_modules/,use:[{loader:"file-loader",options:{outputPath:"css/",name:"[name].min.css"},},"sass-loader",],},],},};

(source:https://stackoverflow.com/a/60029923/2969615)

Source maps

Enables/disables generation of source maps.

To enable CSS source maps, you'll need to pass thesourceMap option to both thesass-loaderand thecss-loader.

webpack.config.js

module.exports={devtool:"source-map",// any "source-map"-like devtool is possiblemodule:{rules:[{test:/\.s[ac]ss$/i,use:["style-loader",{loader:"css-loader",options:{sourceMap:true,},},{loader:"sass-loader",options:{sourceMap:true,},},],},],},};

If you want to edit the original Sass files inside Chrome,there's a good blog post.Checkouttest/sourceMap for a working example.

Contributing

We welcome all contributions!If you're new here, please take a moment to review our contributing guidelines before submitting issues or pull requests.

CONTRIBUTING

License

MIT

[8]ページ先頭
©2009-2025 Movatter.jp