Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@madyankin
madyankin committed Jan 8, 2020
1 parent b40de24 commit 6baf65b
Showing 1 changed file with 87 additions and 60 deletions.
147 changes: 87 additions & 60 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

<a href="https://evilmartians.com/?utm_source=postcss-modules">
<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
Expand All @@ -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
Expand All @@ -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));
}
})
Expand All @@ -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
Expand All @@ -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;
}
})
]);
Expand All @@ -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"
})
]);
```
Expand All @@ -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')({
Expand All @@ -175,22 +186,24 @@ postcss([
If you need, you can pass the options `{ camelCase: true }` to transform classes:

CSS:

```css
.post-title {
color: red;
}
```

JSON:

```json
{
"post-title": "._post-title_116zl_1",
"postTitle": "._post-title_116zl_1"
}
```


## 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.
Expand All @@ -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
<h1 class="_title_xkpkl_5 _title_116zl_1">postcss-modules</h1>
<article class="_article_xkpkl_10">A PostCSS plugin to use CSS Modules everywhere</article>
<article class="_article_xkpkl_10">
A PostCSS plugin to use CSS Modules everywhere
</article>
```


### 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
<h1 css-module="title">postcss-modules</h1>
<article css-module="article">A PostCSS plugin to use CSS Modules everywhere</article>
<article css-module="article">
A PostCSS plugin to use CSS Modules everywhere
</article>
```

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
<h1 class="_title_xkpkl_5 _title_116zl_1">postcss-modules</h1>
<article class="_article_xkpkl_10">A PostCSS plugin to use CSS Modules everywhere</article>
<article class="_article_xkpkl_10">
A PostCSS plugin to use CSS Modules everywhere
</article>
```


## 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

0 comments on commit 6baf65b

Please sign in to comment.