Skip to content

Latest commit

 

History

History
204 lines (156 loc) · 6.96 KB

README.md

File metadata and controls

204 lines (156 loc) · 6.96 KB
Raw

npm node deps chat

Style Loader

Adds CSS to the DOM by injecting a <style> tag

Install

npm install style-loader --save-dev

Usage

Documentation: Using loaders

Simple API

require("style-loader!raw-loader!./file.css");
// => add rules in file.css to document

It's recommended to combine it with the css-loader: require("style-loader!css-loader!./file.css").

It's also possible to add a URL instead of a CSS string:

require("style-loader/url!file-loader!./file.css");
// => add a <link rel="stylesheet"> to file.css to document

Local scope CSS

(experimental)

When using local scope CSS the module exports the generated identifiers:

var style = require("style-loader!css-loader!./file.css");
style.placeholder1 === "z849f98ca812bc0d099a43e0f90184"

Reference-counted API

var style = require("style-loader/useable!css-loader!./file.css");
style.use(); // = style.ref();
style.unuse(); // = style.unref();

Styles are not added on require, but instead on call to use/ref. Styles are removed from page if unuse/unref is called exactly as often as use/ref.

Note: Behavior is undefined when unuse/unref is called more often than use/ref. Don't do that.

Options

insertAt

By default, the style-loader appends <style> elements to the end of the style target, which is the <head> tag of the page unless specified by insertInto. This will cause CSS created by the loader to take priority over CSS already present in the target. To insert style elements at the beginning of the target, set this query parameter to 'top', e.g. require('../style.css?insertAt=top').

insertInto

By default, the style-loader inserts the <style> elements into the <head> tag of the page. If you want the tags to be inserted somewhere else, e.g. into a ShadowRoot, you can specify a CSS selector for that element here, e.g. require('../style.css?insertInto=#host::shadow>#root').

singleton

If defined, the style-loader will re-use a single <style> element, instead of adding/removing individual elements for each required module. Note: this option is on by default in IE9, which has strict limitations on the number of style tags allowed on a page. You can enable or disable it with the singleton query parameter (?singleton or ?-singleton).

convertToAbsoluteUrls

If convertToAbsoluteUrls and sourceMaps are both enabled, relative urls will be converted to absolute urls right before the css is injected into the page. This resolves an issue where relative resources fail to load when source maps are enabled. You can enable it with the convertToAbsoluteUrls query parameter (?convertToAbsoluteUrls).

attrs

If defined, style-loader will attach given attributes with their values on <style> / <link> element. Usage:

require('style-loader?{attrs:{id: "style-tag-id"}}!style.css');

// will create style tag <style id="style-tag-id">

Usage in url mode:

require('style-loader/url?{attrs:{prop: "value"}}!file-loader!style.css')

// will create link tag <link rel="stylesheet" type="text/css" href="[path]/style.css" prop="value">

base

This setting is primarily used as a workaround for css clashes when using one or more DllPlugin's. base allows you to prevent either the app's css (or DllPlugin2's css) from overwriting DllPlugin1's css by specifying a css module id base which is greater than the range used by DllPlugin1 e.g.:

  • webpack.dll1.config.js
{
  test: /\.css$/,
  use: [ 
    'style-loader',
    'css-loader'
  ]
}
  • webpack.dll2.config.js
{
  test: /\.css$/,
  use: [ 
    { loader: 'style-loader', options: { base: 1000 } },
    'css-loader'
  ]
}
  • webpack.app.config.js
{
  test: /\.css$/,
  use: [ 
    { loader: 'style-loader', options: { base: 2000 } },
    'css-loader'
  ]
}

Recommended configuration

By convention the reference-counted API should be bound to .useable.css and the simple API to .css (similar to other file types, i.e. .useable.less and .less).

So the recommended configuration for webpack is:

{
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
        ],
      },
      {
        test: /\.useable\.css$/,
        use: [
          {
            loader: "style-loader/useable"
          },
          { loader: "css-loader" },
        ],
      },
    ],
  },
}

Note about source maps support and assets referenced with url: when style loader is used with ?sourceMap option, the CSS modules will be generated as Blobs, so relative paths don't work (they would be relative to chrome:blob or chrome:devtools). In order for assets to maintain correct paths setting output.publicPath property of webpack configuration must be set, so that absolute paths are generated. Alternatively you can enable the convertToAbsoluteUrls option mentioned above.

Contributing

Don't hesitate to create a pull request. Every contribution is appreciated. In development you can start the tests by calling npm test.

Maintainers


Tobias Koppers
Kees Kluskens

LICENSE

MIT