newer-universal-style-loader/README.md

82 lines
2.9 KiB
Markdown
Raw Normal View History

2012-04-07 05:06:57 +04:00
# style loader for webpack
## Usage
2014-03-11 22:40:59 +04:00
[Documentation: Using loaders](http://webpack.github.io/docs/using-loaders.html)
2014-01-27 14:41:56 +04:00
### Simple API
2012-04-07 05:06:57 +04:00
``` javascript
2012-07-17 04:11:39 +04:00
require("style!raw!./file.css");
2012-04-07 05:06:57 +04:00
// => add rules in file.css to document
```
2014-01-27 14:41:56 +04:00
It's recommended to combine it with the [`css-loader`](https://github.com/webpack/css-loader): `require("style!css!./file.css")`.
2012-07-17 04:11:39 +04:00
2013-03-26 14:51:42 +04:00
It also possible to add a URL instead of a css string:
``` javascript
require("style/url!file!./file.css");
2014-10-23 16:31:22 +04:00
// => add a <link rel="stylesheet"> to file.css to document
2013-03-26 14:51:42 +04:00
```
2015-04-22 00:40:24 +03:00
### Placeholders
(experimental)
When using placeholders (see css-loader) the module exports the placeholders object:
``` js
var styles = require("style!css!./file.css");
style.placeholder1 === "z849f98ca812bc0d099a43e0f90184"
```
2014-01-27 14:41:56 +04:00
### Reference-counted API
``` javascript
var style = require("style/useable!css!./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.
2014-10-20 20:26:18 +04:00
### Options
#### `insertAt`
2015-10-19 21:54:35 +03:00
By default, the style-loader appends `<style>` elements to the end of the `<head>` tag of the page. This will cause CSS created by the loader to take priority over CSS already present in the document head. To insert style elements at the beginning of the head, set this query parameter to 'top', e.g. `require('../style.css?insertAt=top')`.
2014-10-20 20:26:18 +04:00
#### `singleton`
2015-06-19 02:00:39 +03:00
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`).
2014-10-20 20:26:18 +04:00
2014-03-01 19:50:30 +04:00
## 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:
``` javascript
{
module: {
loaders: [
{ test: /\.css$/, exclude: /\.useable\.css$/, loader: "style!css" },
{ test: /\.useable\.css$/, loader: "style/useable!css" }
]
}
}
```
**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 `Blob`s, 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.
## Install
`npm install style-loader`
2012-04-07 05:06:57 +04:00
## License
2014-03-01 19:50:30 +04:00
MIT (http://www.opensource.org/licenses/mit-license.php)