"readme": "# postcss-modules\n\nA [PostCSS] plugin to use [CSS Modules] everywhere. Not only at the client side.\n\n[postcss]: https://github.com/postcss/postcss\n[css modules]: https://github.com/css-modules/css-modules\n\n## What is this?\n\nFor example, you have the following CSS:\n\n```css\n/* styles.css */\n:global .page {\n\tpadding: 20px;\n}\n\n.title {\n\tcomposes: title from \"./mixins.css\";\n\tcolor: green;\n}\n\n.article {\n\tfont-size: 16px;\n}\n\n/* mixins.css */\n.title {\n\tcolor: black;\n\tfont-size: 40px;\n}\n\n.title:hover {\n\tcolor: red;\n}\n```\n\nAfter the transformation it will become like this:\n\n```css\n._title_116zl_1 {\n\tcolor: black;\n\tfont-size: 40px;\n}\n\n._title_116zl_1:hover {\n\tcolor: red;\n}\n\n.page {\n\tpadding: 20px;\n}\n\n._title_xkpkl_5 {\n\tcolor: green;\n}\n\n._article_xkpkl_10 {\n\tfont-size: 16px;\n}\n```\n\nAnd the plugin will give you a JSON object for transformed classes:\n\n```json\n{\n\t\"title\": \"_title_xkpkl_5 _title_116zl_1\",\n\t\"article\": \"_article_xkpkl_10\"\n}\n```\n\n## Usage\n\n### Saving exported classes\n\nBy default, a JSON file with exported classes will be placed next to corresponding CSS.\nBut you have a freedom to make everything you want with exported classes, just\nuse the `getJSON` callback. For example, save data about classes into a corresponding JSON file:\n\n```js\npostcss([\n\trequire(\"postcss-modules\")({\n\t\tgetJSON: function (cssFileName, json, outputFileName) {\n\t\t\tvar path = require(\"path\");\n\t\t\tvar cssName = path.basename(cssFileName, \".css\");\n\t\t\tvar jsonFileName = path.resolve(\"./build/\" + cssName + \".json\");\n\t\t\tfs.writeFileSync(jsonFileName, JSON.stringify(json));\n\t\t},\n\t}),\n]);\n```\n\n`getJSON` may also return a `Promise`.\n\n### Generating scoped names\n\nBy default, the plugin assumes that all the classes are local. You can change\nthis behaviour using the `scopeBehaviour` option:\n\n```js\npostcss([\n\trequire(\"postcss-modules\")({\n\t\tscopeBehaviour: \"global\", // can be 'global' or 'local',\n\t}),\n]);\n```\n\nTo define paths for global modules, use the `globalModulePaths` option.\nIt is an array with regular expressions defining the paths:\n\n```js\npostcss([\n require('postcss-modules')({\n globalModulePaths: [/path\\/to\\/legacy-styles/, /another\\/paths/],\n });\n]);\n```\n\nTo generate custom classes, use the `generateScopedName` callback:\n\n```js\npostcss([\n\trequire(\"postcss-modules\")({\n\t\tgenerateScopedName: function (name, filename, css) {\n\t\t\tvar path = require(\"path\");\n\t\t\tvar i = css.indexOf(\".\" + name);\n\t\t\tvar line = css.substr(0, i).split(/[\\r\\n]/).length;\n\t\t\tvar file = path.basename(filename, \".css\");\n\n\t\t\treturn \"_\" + file + \"_\" + line + \"_\" + name;\n\t\t},\n\t}),\n]);\n```\n\nOr just pass an interpolated string to the `generateScopedName` option\n(More details [here](https://github.com/webpack/loader-utils#interpolatename)):\n\n```js\npostcss([\n\trequire(\"postcss-modules\")({\n\t\tgenerateScopedName: \"[name]__[local]___[hash:base64:5]\",\n\t}),\n]);\n```\n\nIt'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)):\n\n```js\npostcss([\n\trequire(\"postcss-modules\")({\n\t\tgenerateScopedName: \"[name]__[local]___[hash:base64:5]\",\n\t\thashPrefix: \"prefix\",\n\t}),\n]);\n```\n\n### Exporting globals\n\nIf you need to export global names via the JSON object along with the local ones, add the `exportGlobals` option:\n\n```js\npostcss([\n\trequire(\"postcss-modules\")({\n\t\texportGlobals: true,\n\t}),\n]);\n```\n\n### Loading source files\n\nIf you need, you can pass a custom loader (see [FileSystemLoader] for example):\n\n```js\npostcss([\n\trequire(\"postcss-modules\")({\n\t\tLoader: CustomLoader,\n\t}),\n]);\n```\n\nYou can also pass any needed root path:\n\n```js\npostcss([\n require('postcss-modules')({\n root: 'C:\\\\',\n });\n]);\n```\n\n### localsConvention\n\nType: `String | (originalClassName: string, generatedClassName: string, inputFile: string) => className: (string|string[])`\nDefault: `null`\n\nStyle of exported classnames, the keys in your json.\n\n| Name | Type | Description |\n|:---------------------:| :--------: |:-------------------------------------------------------------------------------------------------|\n| **`'camelCase'`** | `{String}` | Class names will be camelized, the original class name will not to be removed from the locals |\n| **`'camelCaseOnly'`** | `{String}` | Class names will be camelized, the original class name will be removed from the locals |\n| **`'dashes'`** | `{String}` | Only dashes in class names will be camelized |\n| **`'dashesOnly'`** | `{String}` | Dashes in class names will be camelized, the original class name will be removed from the locals |\n| **`'all'`** | `{String}` | Apply camelCase, dashes, and the orignional naming convention |\n| **`'none'`** | `{String}` | Only use the orignional naming convention with out locals |\n\nIn lieu of a string, a custom function can generate the exported class names.\n\n### Resolve path alias\n\nYou can rewrite paths for `composes/from` by using the `resolve` option.\nIt's useful when you need to resolve custom path alias.\n\nParameters:\n\n- `file` — a module we want to resolve\n- `importer` — the file that imports the module we want to resolve\n\nReturn value: `string | null | Promise<string | null>`\n\n```js\npostcss([\n\trequire(\"postcss-modules\")({\n \tresolve: function (file, importer) {\n\t\t\treturn path.resolve(\n\t\t\t\tpath.dirname(importer),\n\t\t\t\tfile.replace(/^@/, process.cwd()\n\t\t\t);\n \t},\n \t}),\n]);\n```\n\n## Integration with templates\n\nThe plugin only transforms CSS classes to CSS modules.\nBut you probably want to integrate these CSS modules with your templates.\nHere are some examples.\n\nAssume you've saved project's CSS modules in `cssModules.json`:\n\n```json\n{\n\t\"title\": \"_title_xkpkl_5 _title_116zl_1\",\n\t\"article\": \"_article_xkpkl_10\"\n}\n```\n\n### Pug (ex-Jade)\n\nLet's say you have a Pug template `about.jade`:\n\n```jade\nh1(class=css.title) postcss-modules\narticle(class=css.article) A PostCSS plugin to use CSS Modules everywhere\n```\n\nRender it:\n\n```js\nvar jade = require(\"jade\");\nvar cssModules = require(\"./cssModules.json\");\nvar html = jade.compileFile(\"about.jade\")({ css: cssModules });\nconsole.log(html);\n```\n\nAnd you'll get the following HTML:\n\n```html\n<h1 class=\"_title_xkpkl_5 _title_116zl_1\">postcss-modules</h1>\n<article class=\"_article_xkpkl_10\">\n\tA PostCSS plugin to use CSS Modules everywhere\n</article>\n```\n\n### HTML\n\nFor HTML transformation we'll use [PostHTML](https://github.com/posthtml/posthtml) and [PostHTML CSS Modules](https://github.com/maltsev/posthtml-css-modules):\n\n```bash\nnpm install --save posthtml posthtml-css-modules\n```\n\nHere is our template `about.html`:\n\n```html\n<h1 css-module=\"title\">postcss-modules</h1>\n<article css-module=\"article\">\n\tA PostCSS plugin to use CSS Modules everywhere\n</article>\n```\n\nTransform it:\n\n```js\nvar fs = require(\"fs\");\nvar posthtml = require(\"posthtml\");\nvar posthtmlCssModules = require(\"posthtml-css-modules\");\nvar template = fs.readFileSync(\"./about.html\", \"utf8\");\n\nposthtml([posthtmlCssModules(\"./cssModules.json\")])\n\t.process(template)\n\t.then(function (result) {\n\t\tconsole.log(result.html);\n\t});\n```\n\n(for using other build systems please check [the documentation of PostHTML](https://github.com/posthtml/posthtml/blob/master/readme.md))\n\nAnd you'll get the following HTML:\n\n```html\n<h1 class=\"_title_xkpkl_5 _title_116zl_1\">postcss-modules</h1>\n<article class=\"_article_xkpkl_10\">\n\tA PostCSS plugin to use CSS Modules everywhere\n</article>\n```\n\n## May I see the plugin in action?\n\nSure! Take a look at the [example](https://github.com/outpunk/postcss-modules-example).\n\nSee [PostCSS] docs for examples for your environment and don't forget to run\n\n```\nnpm install --save-dev postcss postcss-modules\n```\n\n[filesystemloader]: https://github.com/css-modules/css-modules-loader-core/blob/master/src/file-system-loader.js\n\n## Sponsors\n\n- Dmitry Olyenyov\n",
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments