diff --git a/README.md b/README.md index aa9e75d2..7b29c651 100644 --- a/README.md +++ b/README.md @@ -1,231 +1,32 @@ # css loader for webpack -## installation +I forked this module because I use it with SASS and webpack prerendering. Thus, modules didn't work and I kept getting this error message because the class names were different on the frontend than the ones in the backend: -`npm install css-loader --save-dev` - -## Usage - -[Documentation: Using loaders](http://webpack.github.io/docs/using-loaders.html) - -``` javascript -var css = require("css!./file.css"); -// => returns css code from file.css, resolves imports and url(...) -``` - -`@import` and `url(...)` are interpreted like `require()` and will be resolved by the css-loader. -Good loaders for requiring your assets are the [file-loader](https://github.com/webpack/file-loader) -and the [url-loader](https://github.com/webpack/url-loader) which you should specify in your config (see below). - -To be compatible with existing css files (if not in CSS Module mode): -* `url(image.png)` => `require("./image.png")` -* `url(~module/image.png)` => `require("module/image.png")` - -### Example config - -This webpack config can load css files, embed small png images as Data Urls and jpg images as files. - -``` javascript -module.exports = { - module: { - loaders: [ - { test: /\.css$/, loader: "style-loader!css-loader" }, - { test: /\.png$/, loader: "url-loader?limit=100000" }, - { test: /\.jpg$/, loader: "file-loader" } - ] - } -}; -``` - -### 'Root-relative' urls - -For urls that start with a `/`, the default behavior is to not translate them: -* `url(/image.png)` => `url(/image.png)` - -If a `root` query parameter is set, however, it will be prepended to the url -and then translated: - -With a config like: - -``` javascript - loaders: [ - { test: /\.css$/, loader: "style-loader!css-loader?root=." }, - ... - ] -``` - -The result is: - -* `url(/image.png)` => `require("./image.png")` - -Using 'Root-relative' urls is not recommended. You should only use it for legacy CSS files. - -### Local scope - -By default CSS exports all class names into a global selector scope. This is a feature which offer a local selector scope. - -The syntax `:local(.className)` can be used to declare `className` in the local scope. The local identifiers are exported by the module. - -With `:local` (without brackets) local mode can be switched on for this selector. `:global(.className)` can be used to declare an explicit global selector. With `:global` (without brackets) global mode can be switched on for this selector. - -The loader replaces local selectors with unique identifiers. The choosen unique identifiers are exported by the module. - -Example: - -``` css -:local(.className) { background: red; } -:local .className { color: green; } -:local(.className .subClass) { color: green; } -:local .className .subClass :global(.global-class-name) { color: blue; } -``` - -is transformed to - -``` css -._23_aKvs-b8bW2Vg3fwHozO { background: red; } -._23_aKvs-b8bW2Vg3fwHozO { color: green; } -._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 { color: green; } -._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name { color: blue; } -``` - -and the identifiers are exported: - -``` js -exports.locals = { - className: "_23_aKvs-b8bW2Vg3fwHozO", - subClass: "_13LGdX8RMStbBE9w-t0gZ1" -} -``` - -Camelcasing is recommended for local selectors. They are easier to use in the importing javascript module. - -`url(...)` URLs in block scoped (`:local .abc`) rules behave like requests in modules: - * `./file.png` instead of `file.png` - * `module/file.png` instead of `~module/file.png` - - -You can use `:local(#someId)`, but this is not recommended. Use classes instead of ids. - -You can configure the generated ident with the `localIdentName` query parameter (default `[hash:base64]`). Example: `css-loader?localIdentName=[path][name]---[local]---[hash:base64:5]` for easier debugging. - -Note: For prerendering with extract-text-webpack-plugin you should use `css-loader/locals` instead of `style-loader!css-loader` **in the prerendering bundle**. It doesn't embed CSS but only exports the identifier mappings. - -### CSS Modules - -See [CSS Modules](https://github.com/css-modules/css-modules). - -The query parameter `modules` enables the **CSS Modules** spec. (`css-loader?modules`) - -This enables Local scoped CSS by default. (You can switch it off with `:global(...)` or `:global` for selectors and/or rules.) - -### Composing CSS classes - -When declaring a local class name you can compose a local class from another local class name. - -``` css -:local(.className) { - background: red; - color: yellow; -} - -:local(.subClass) { - composes: className; - background: blue; -} ``` - -This doesn't result in any change to the CSS itself but exports multiple class names: - -``` js -exports.locals = { - className: "_23_aKvs-b8bW2Vg3fwHozO", - subClass: "_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO" -} -``` - -and CSS is transformed to: - -``` css -._23_aKvs-b8bW2Vg3fwHozO { - background: red; - color: yellow; -} - -._13LGdX8RMStbBE9w-t0gZ1 { - background: blue; -} +Warning: React attempted to reuse markup in a container but the checksum was invalid. This generally means that you are using server rendering and the markup generated on the server was not what the client was expecting. React injected new markup to compensate which works but you have lost many of the benefits of server rendering. Instead, figure out why the markup being generated is different on the client or server: ``` -### Importing local class names +So I fixed it by adding 1 new parameter to localIdentName: `sourceHash`. -To import a local class name from another module: +## Usage -``` css -:local(.continueButton) { - composes: button from "library/button.css"; - background: red; -} -``` +Use `[sourceHash]` or `[sourceHash:keyLen]` to make css-loader generate the same classes for the same localName and source code combination. -``` css -:local(.nameEdit) { - composes: edit highlight from "./edit.css"; - background: red; -} -``` +## Example -To import from multiple modules use multiple `composes:` rules. - -``` css -:local(.className) { - composes: edit hightlight from "./edit.css"; - composes: button from "module/button.css"; - composes: classFromThisModule; - background: red; -} ``` +const CSS_LOADER_PARAMS = `modules&localIdentName=${DEBUG ? '[dir]--[local]--[sourceHash:5]' : '[sourceHash]&minimize'}`; -### SourceMaps - -To include SourceMaps set the `sourceMap` query param. - -`require("css-loader?sourceMap!./file.css")` - -I. e. the extract-text-webpack-plugin can handle them. - -They are not enabled by default because they expose a runtime overhead and increase in bundle size (JS SourceMap do not). In addition to that relative paths are buggy and you need to use an absolute public path which include the server url. - -### importing and chained loaders +// Frontend +loader: `style!css?${CSS_LOADER_PARAMS}&sourceMap!autoprefixer!${SASS_LOADER}` -The query parameter `importLoaders` allow to configure which loaders should be applied to `@import`ed resources. - -`importLoaders` (int): That many loaders after the css-loader are used to import resources. - -Examples: - -``` js -require("style-loader!css-loader?importLoaders=1!autoprefixer-loader!...") -// => imported resources are handled this way: -require("css-loader?importLoaders=1!autoprefixer-loader!...") - -require("style-loader!css-loader!stylus-loader!...") -// => imported resources are handled this way: -require("css-loader!...") +// Prerendered +loader: `css/locals?${CSS_LOADER_PARAMS}!autoprefixer!${SASS_LOADER}` ``` -This may change in the future, when the module system (i. e. webpack) supports loader matching by origin. - -### Minification - -By default the css-loader minimizes the css if specified by the module system. - -In some cases the minification is destructive to the css, so you can provide some options to it. clean-css is used for minification and you find a [list of options here](https://github.com/jakubpawlowicz/clean-css#how-to-use-clean-css-programmatically). Just provide them as query parameter: i. e. `require("css-loader?-restructuring&compatibility")` to disable restructuring and enable compatibility mode. - -You can also disable or enforce minification with the `minimize` query parameter. - -`require("css-loader?minimize!./file.css")` (enforced) +## Docs -`require("css-loader?-minimize!./file.css")` (disabled) +[Original Docs](https://github.com/webpack/css-loader) ## License diff --git a/lib/getLocalIdent.js b/lib/getLocalIdent.js index 7321669d..b441ddff 100644 --- a/lib/getLocalIdent.js +++ b/lib/getLocalIdent.js @@ -2,14 +2,41 @@ MIT License http://www.opensource.org/licenses/mit-license.php Author Tobias Koppers @sokra */ +var crypto = require('crypto'); +var path = require('path'); + var loaderUtils = require("loader-utils"); -module.exports = function getLocalIdent(loaderContext, localIdentName, localName, options) { + +var DIR_REGEX = /dir(.*)dir/; +var SOURCE_HASH_REGEX = /\[(sourceHash.*)\]/; + +module.exports = function getLocalIdent(inputSource, loaderContext, localIdentName, localName, options) { var request = loaderContext.options && typeof loaderContext.options.context === "string" ? loaderUtils.stringifyRequest({ context: loaderContext.options.context }, loaderUtils.getRemainingRequest(loaderContext)) : loaderContext.request; options.content = localName + " " + request; options.context = loaderContext.options && typeof loaderContext.options.context === "string" ? loaderContext.options.context : loaderContext.context; localIdentName = localIdentName.replace(/\[local\]/gi, localName); + + var sourceHashMatch = localIdentName.match(SOURCE_HASH_REGEX); + if (sourceHashMatch && sourceHashMatch[1]) { + var hashLen = sourceHashMatch[1].split(':')[1] || 32; + var sourceHash = crypto.createHash("md5").update(localName + inputSource).digest("hex"); + localIdentName = localIdentName.replace(SOURCE_HASH_REGEX, sourceHash.substr(0, hashLen)); + } + + var replaceWithDir = false; + if (localIdentName.indexOf("[dir]") !== -1) { + localIdentName = localIdentName.replace("[dir]", "dir[path]dir"); + replaceWithDir = true; + } + var hash = loaderUtils.interpolateName(loaderContext, localIdentName, options); + + if (replaceWithDir) { + var dirName = path.basename(hash.match(DIR_REGEX)[1]); + hash = hash.replace(DIR_REGEX, dirName); + } + return hash.replace(/[^a-zA-Z0-9\-_]/g, "-").replace(/^([^a-zA-Z_])/, "_$1"); }; diff --git a/lib/processCss.js b/lib/processCss.js index e7c8a04b..3ecfb6cf 100644 --- a/lib/processCss.js +++ b/lib/processCss.js @@ -150,7 +150,7 @@ module.exports = function processCss(inputSource, inputMap, options) { }), modulesScope({ generateScopedName: function(exportName) { - return getLocalIdent(options.loaderContext, localIdentName, exportName, { + return getLocalIdent(inputSource, options.loaderContext, localIdentName, exportName, { regExp: localIdentRegExp }); }