diff --git a/README.md b/README.md index ac8633a..8f8b869 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ A [PostCSS] plugin to use [CSS Modules] everywhere. Not only at the client side. -[PostCSS]: https://github.com/postcss/postcss -[ci-img]: https://travis-ci.org/css-modules/postcss-modules.svg -[ci]: https://travis-ci.org/css-modules/postcss-modules -[CSS Modules]: https://github.com/css-modules/css-modules +[postcss]: https://github.com/postcss/postcss +[ci-img]: https://travis-ci.org/css-modules/postcss-modules.svg +[ci]: https://travis-ci.org/css-modules/postcss-modules +[css modules]: https://github.com/css-modules/css-modules Sponsored by Evil Martians @@ -14,66 +14,65 @@ A [PostCSS] plugin to use [CSS Modules] everywhere. Not only at the client side. What is this? For example, you have the following CSS: ```css - /* styles.css */ :global .page { - padding: 20px; + padding: 20px; } .title { - composes: title from "./mixins.css"; - color: green; + composes: title from "./mixins.css"; + color: green; } .article { - font-size: 16px; + font-size: 16px; } /* mixins.css */ .title { - color: black; - font-size: 40px; + color: black; + font-size: 40px; } .title:hover { - color: red; + color: red; } - ``` + After the transformation it will become like this: ```css ._title_116zl_1 { - color: black; - font-size: 40px; + color: black; + font-size: 40px; } ._title_116zl_1:hover { - color: red; + color: red; } .page { - padding: 20px; + padding: 20px; } ._title_xkpkl_5 { - color: green; + color: green; } ._article_xkpkl_10 { - font-size: 16px; + font-size: 16px; } ``` And the plugin will give you a JSON object for transformed classes: + ```json { "title": "_title_xkpkl_5 _title_116zl_1", - "article": "_article_xkpkl_10", + "article": "_article_xkpkl_10" } ``` - ## Usage ### Saving exported classes @@ -84,11 +83,11 @@ use the `getJSON` callback. For example, save data about classes into a correspo ```js postcss([ - require('postcss-modules')({ + require("postcss-modules")({ getJSON: function(cssFileName, json, outputFileName) { - var path = require('path'); - var cssName = path.basename(cssFileName, '.css'); - var jsonFileName = path.resolve('./build/' + cssName + '.json'); + var path = require("path"); + var cssName = path.basename(cssFileName, ".css"); + var jsonFileName = path.resolve("./build/" + cssName + ".json"); fs.writeFileSync(jsonFileName, JSON.stringify(json)); } }) @@ -104,13 +103,13 @@ this behaviour using the `scopeBehaviour` option: ```js postcss([ - require('postcss-modules')({ - scopeBehaviour: 'global' // can be 'global' or 'local', + require("postcss-modules")({ + scopeBehaviour: "global" // can be 'global' or 'local', }) ]); ``` -To define paths for global modules, use the `globalModulePaths` option. +To define paths for global modules, use the `globalModulePaths` option. It is an array with regular expressions defining the paths: ```js @@ -125,14 +124,14 @@ To generate custom classes, use the `generateScopedName` callback: ```js postcss([ - require('postcss-modules')({ + require("postcss-modules")({ generateScopedName: function(name, filename, css) { - var path = require('path'); - var i = css.indexOf('.' + name); - var line = css.substr(0, i).split(/[\r\n]/).length; - var file = path.basename(filename, '.css'); + var path = require("path"); + var i = css.indexOf("." + name); + var line = css.substr(0, i).split(/[\r\n]/).length; + var file = path.basename(filename, ".css"); - return '_' + file + '_' + line + '_' + name; + return "_" + file + "_" + line + "_" + name; } }) ]); @@ -143,8 +142,19 @@ Or just pass an interpolated string to the `generateScopedName` option ```js postcss([ - require('postcss-modules')({ - generateScopedName: '[name]__[local]___[hash:base64:5]', + require("postcss-modules")({ + generateScopedName: "[name]__[local]___[hash:base64:5]" + }) +]); +``` + +It's possible to add custom hash to generate more unique classes using the `hashPrefix` option (like in [css-loader](https://webpack.js.org/loaders/css-loader/#hashprefix)): + +```js +postcss([ + require("postcss-modules")({ + generateScopedName: "[name]__[local]___[hash:base64:5]", + hashPrefix: "prefix" }) ]); ``` @@ -155,13 +165,14 @@ If you need, you can pass a custom loader (see [FileSystemLoader] for example): ```js postcss([ - require('postcss-modules')({ - Loader: CustomLoader, + require("postcss-modules")({ + Loader: CustomLoader }) ]); ``` You can also pass any needed root path: + ```js postcss([ require('postcss-modules')({ @@ -175,6 +186,7 @@ postcss([ If you need, you can pass the options `{ camelCase: true }` to transform classes: CSS: + ```css .post-title { color: red; @@ -182,6 +194,7 @@ CSS: ``` JSON: + ```json { "post-title": "._post-title_116zl_1", @@ -189,8 +202,8 @@ JSON: } ``` - ## Integration with templates + The plugin only transforms CSS classes to CSS modules. But you probably want to integrate these CSS modules with your templates. Here are some examples. @@ -204,70 +217,84 @@ Assume you've saved project's CSS modules in `cssModules.json`: } ``` - ### Pug (ex-Jade) + Let's say you have a Pug template `about.jade`: + ```jade h1(class=css.title) postcss-modules article(class=css.article) A PostCSS plugin to use CSS Modules everywhere ``` Render it: + ```js -var jade = require('jade'); -var cssModules = require('./cssModules.json'); -var html = jade.compileFile('about.jade')({css: cssModules}); +var jade = require("jade"); +var cssModules = require("./cssModules.json"); +var html = jade.compileFile("about.jade")({ css: cssModules }); console.log(html); ``` And you'll get the following HTML: + ```html

postcss-modules

-
A PostCSS plugin to use CSS Modules everywhere
+
+ A PostCSS plugin to use CSS Modules everywhere +
``` - ### HTML + For HTML transformation we'll use [PostHTML](https://github.com/posthtml/posthtml) and [PostHTML CSS Modules](https://github.com/maltsev/posthtml-css-modules): + ```bash npm install --save posthtml posthtml-css-modules ``` Here is our template `about.html`: + ```html

postcss-modules

-
A PostCSS plugin to use CSS Modules everywhere
+
+ A PostCSS plugin to use CSS Modules everywhere +
``` Transform it: + ```js -var fs = require('fs'); -var posthtml = require('posthtml'); -var posthtmlCssModules = require('posthtml-css-modules'); -var template = fs.readFileSync('./about.html', 'utf8'); - -posthtml([posthtmlCssModules('./cssModules.json')]) - .process(template) - .then(function (result) { - console.log(result.html); - }); +var fs = require("fs"); +var posthtml = require("posthtml"); +var posthtmlCssModules = require("posthtml-css-modules"); +var template = fs.readFileSync("./about.html", "utf8"); + +posthtml([posthtmlCssModules("./cssModules.json")]) + .process(template) + .then(function(result) { + console.log(result.html); + }); ``` -(for using other build systems please check [the documentation of PostHTML](https://github.com/posthtml/posthtml/blob/master/README.md)) +(for using other build systems please check [the documentation of PostHTML](https://github.com/posthtml/posthtml/blob/master/README.md)) And you'll get the following HTML: + ```html

postcss-modules

-
A PostCSS plugin to use CSS Modules everywhere
+
+ A PostCSS plugin to use CSS Modules everywhere +
``` - ## May I see the plugin in action? + Sure! Take a look at the [example](https://github.com/outpunk/postcss-modules-example). See [PostCSS] docs for examples for your environment and don't forget to run + ``` npm install --save-dev postcss-modules ``` -[FileSystemLoader]: https://github.com/css-modules/css-modules-loader-core/blob/master/src/file-system-loader.js +[filesystemloader]: https://github.com/css-modules/css-modules-loader-core/blob/master/src/file-system-loader.js