From 9f33845389c1a93fc76590a89e6348aa277f22ae Mon Sep 17 00:00:00 2001 From: Alexey Litvinov Date: Wed, 2 Sep 2015 21:36:06 +0300 Subject: [PATCH 1/2] overview --- README.md | 85 +++++++++++++++++++++---------------------------------- 1 file changed, 32 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index edb7747..0b15aa2 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,59 @@ css-modules-require-hook ======================== -Automatically compiles a CSS Module to a low-level interchange format called ICSS or [Interoperable CSS](https://github.com/css-modules/icss). +Summary -One of the ways you can compile [CSS Modules](https://github.com/css-modules/css-modules) to the ICSS format is through the require hook. The require hook will bind itself to node's require and automatically compile files on the fly. This is similar to Babel's [babel/register](https://babeljs.io/docs/usage/require/). +## What is CSS Modules -## Requirements +Summary -To use this tool we require postcss and few plugins to be installed on your project. See the list below: +## Features -- `"postcss": "4.x"` -- `"postcss-modules-extract-imports": "0.x"` -- `"postcss-modules-local-by-default": "0.x"` -- `"postcss-modules-scope": "0.x"` - -## Install - -```bash -$ npm i css-modules-require-hook -``` +Compiling in runtime, universal apps ## Usage -```javascript -require('css-modules-require-hook'); -``` - -## Available options - -Providing additional options allows you to get advanced experience. See the variants below. - -```javascript -var hook = require('css-modules-require-hook'); -hook({ /* options */ }); -``` - -### `rootDir` option - -Aliases are `root`, `d`. - -Absolute path to your project's root directory. This is optional but providing it will result in better generated classnames. It can be obligatory, if you run require hook and build tools, like [css-modulesify](https://github.com/css-modules/css-modulesify) from different working directories. - -### `use` option +### Requirements -Alias is `u`. +To use this tool we require [Node.js](https://github.com/nodejs/node) v0.12.x (or higher) and several modules to be installed. -Custom list of plugins. This is optional but helps you to extend list of basic [postcss](https://github.com/postcss/postcss) plugins. Also helps to specify options for particular plugins. +- [postcss](https://github.com/postcss/postcss) version 4 or higher +- [postcss-modules-extract-imports](https://github.com/css-modules/postcss-modules-extract-imports) +- [postcss-modules-local-by-default](https://github.com/css-modules/postcss-modules-local-by-default) +- [postcss-modules-scope](https://github.com/css-modules/postcss-modules-scope) -### `createImportedName` option +### Installation -Alias for the `createImportedName` option from the [postcss-modules-extract-imports](https://github.com/css-modules/postcss-modules-extract-imports) plugin. This is optional. Won't work if you `use` option. +```bash +$ npm i css-modules-require-hook +``` -### `generateScopedName` option +### Tuning (options) -Custom function to generate class names. This is optional. Alias for the `generateScopedName` option from the [postcss-modules-scope](https://github.com/css-modules/postcss-modules-scope) plugin. Won't work if you `use` option. + * `function` **createImportedName** — short alias for the [postcss-modules-extract-imports](https://github.com/css-modules/postcss-modules-extract-imports) plugin's `createImportedName` option. + * `function` **generateScopedName** — short alias for the [postcss-modules-scope](https://github.com/css-modules/postcss-modules-scope) plugin's option. Helps you to specify the custom way to build generic names for the class selectors. + * `function` **processCss** — in rare cases you may want to get compiled styles in runtime, so providing this option helps. + * `string` **rootDir** — absolute path to the project directory. Providing this will result in better generated class names. It can be obligatory, if you run require hook and build tools (like [css-modulesify](https://github.com/css-modules/css-modulesify)) from different working directories. + * `string` **to** — provides `to` option to the [LazyResult instance](https://github.com/postcss/postcss/blob/master/docs/api.md#processorprocesscss-opts). + * `array` **use** — custom subset of postcss plugins. -### `mode` option +### Examples -Alias for the `mode` option from the [postcss-modules-local-by-default](https://github.com/css-modules/postcss-modules-local-by-default) plugin. This is optional. Won't work if you `use` option. +Basically you need to require this plugin before other requires for your styles will occur. -## Examples +```javascript +require('css-modules-require-hook'); +// ... +``` -If you want to add custom functionality, for example [CSS Next](http://cssnext.io/setup/#as-a-postcss-plugin) plugin, you should provide the `use` option. +In rare cases you may want to tune the require hook for better experience. ```javascript var hook = require('css-modules-require-hook'); +var path = require('path'); hook({ - use: [ - // adding CSS Next plugin - require('cssnext')(), - - // adding basic css-modules plugins - require('postcss-modules-extract-imports'), - require('postcss-modules-local-by-default'), - require('postcss-modules-scope') - ] + // setting root to the parent directory + rootDir: path.join(__dirname, '..') }); ``` From 9d44f83e016a5fe0d22fa168fb6ee5c614637121 Mon Sep 17 00:00:00 2001 From: Alexey Litvinov Date: Thu, 3 Sep 2015 22:00:54 +0300 Subject: [PATCH 2/2] short description and basic examples --- README.md | 47 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 42 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0b15aa2..6991bf2 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ css-modules-require-hook ======================== -Summary +The require hook compiles [CSS Modules](https://github.com/css-modules/css-modules) in runtime. This is similar to Babel's [babel/register](https://babeljs.io/docs/usage/require/). ## What is CSS Modules -Summary +A **CSS Module** is a CSS file in which all class names and animation names are scoped locally by default. Learn more in the article [CSS Modules - Welcome to the Future](http://glenmaddern.com/articles/css-modules) by Glen Maddern. ## Features -Compiling in runtime, universal apps +Compiling in runtime, [universal](https://medium.com/@mjackson/universal-javascript-4761051b7ae9) usage. ## Usage ### Requirements -To use this tool we require [Node.js](https://github.com/nodejs/node) v0.12.x (or higher) and several modules to be installed. +To use this tool we require [Node.js v0.12.x](https://github.com/nodejs/node) (or higher) and several modules to be installed. - [postcss](https://github.com/postcss/postcss) version 4 or higher - [postcss-modules-extract-imports](https://github.com/css-modules/postcss-modules-extract-imports) @@ -40,10 +40,29 @@ $ npm i css-modules-require-hook ### Examples Basically you need to require this plugin before other requires for your styles will occur. +For example: + +*icon.css* +```css +.icon +{ + composes: fa fa-hand-peace-o from 'font-awesome/css/font-awesome.css'; +} +``` +*server.js* ```javascript require('css-modules-require-hook'); -// ... + +var styles = require('./icon.css'); +var html = ''; +// send it somehow :) +``` + +You'll get: + +```html +' ``` In rare cases you may want to tune the require hook for better experience. @@ -57,3 +76,21 @@ hook({ rootDir: path.join(__dirname, '..') }); ``` + +If you want to add any postcss plugins to the pipeline - you should use the `use` option. + +```javascript +var hook = require('css-modules-require-hook'); + +hook({ + use: [ + // adding CSS Next plugin + require('cssnext')(), + + // adding basic css-modules plugins + require('postcss-modules-extract-imports'), + require('postcss-modules-local-by-default'), + require('postcss-modules-scope') + ] +}); +```