Awesome
css-modules-require-hook
The require hook compiles CSS Modules in runtime. This is similar to Babel's babel/register. See the example: demo.
What is CSS Modules
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 by Glen Maddern.
Features
Compiling in runtime, universal usage.
Requirements
To use this tool we require Node.js v0.12.x (or higher).
Installation
$ npm i css-modules-require-hook
Usage
Now, there are two ways to attach hook: manually or using preset file.
The first one allows you to pass options manually after module was required. Example:
const hook = require('css-modules-require-hook');
hook({
generateScopedName: '[name]__[local]___[hash:base64:5]',
});
// const styles = require('./icon.css');
The second one allows you to move options to the separate file cmrh.conf.js
. Config file should be located in the same directory where executor is or in its ancestor directories. In that case hook will be attached right after the css-modules-require-hook/preset
module will be required. Example:
// cmrh.conf.js
module.exports = {
generateScopedName: '[name]__[local]___[hash:base64:5]',
};
require('css-modules-require-hook/preset');
// const styles = require('./icon.css');
Using with babel-node / ES6 Imports
You will need to create a cmrh.conf.js
file within the directory as you are importing css-modules-require-hook
.
// server.js
import csshook from 'css-modules-require-hook/preset' // import hook before routes
import routes from '/shared/views/routes'
// create server, etc
// cmrh.conf.js
module.exports = {
// Same scope name as in webpack build
generateScopedName: '[name]__[local]___[hash:base64:5]',
}
Development mode
Usually, Node.js caches all the require
calls by default. In order to invalidate cache for the purpose of development you should set the environment variable NODE_ENV
to development
. For example:
$ NODE_ENV=development node server.js
Still you can use devMode
option (see below) to override behavior which is imposed by environment variable.
Adding custom PostCSS plugins
var hook = require('css-modules-require-hook');
var cssnext = require('cssnext');
hook({
prepend: [
// adding CSS Next plugin
cssnext(),
],
});
Specify custom pattern to build generic names
var hook = require('css-modules-require-hook');
hook({
generateScopedName: '[name]__[local]___[hash:base64:5]',
});
Using Stylus as a preprocessor
var hook = require('css-modules-require-hook');
var stylus = require('stylus');
hook({
extensions: ['.styl'],
preprocessCss: function (css, filename) {
return stylus(css)
.set('filename', filename)
.render();
},
});
// var styles = require('./demo.styl');
Tuning (options)
To adjust the require hook you need to provide params to the exported function.
var hook = require('css-modules-require-hook');
hook({
// append: [],
// generateScopedName: function () {},
// or any other options
// see the list below
});
devMode
boolean
Helps you to invalidate cache of all require
calls. Usually used for the development purpose. Also overrides behavior, imposed by NODE_ENV
environment variable. For example:
hook({
devMode: false,
});
extensions
array
Attach the require hook to additional file extensions (for example ['.scss']
).
ignore
function|regex|string
Provides possibility to exclude particular files from processing. Supports glob and regular expressions syntax. Also you may provide custom function.
preprocessCss
function
In rare cases you may want to precompile styles, before they will be passed to the PostCSS pipeline. You should use synchronous transformations, since require
function is synchronous.
hook({
/**
* @param {string} css
* @param {string} filepath Absolute path to the file
* @return {string}
*/
preprocessCss: function (css, filepath) {
return css;
}
});
processCss
function
In rare cases you may want to get compiled styles in runtime, so providing this option helps.
hook({
/**
* @param {string} css
* @param {string} filepath Absolute path to the file
*/
processCss: function (css, filepath) { /* */ }
});
processorOpts
object
Provides possibility to pass custom options to the LazyResult instance. It can be usefull if you want to set the custom parser, for example: postcss-less.
const hook = require('css-modules-require-hook');
const lessParser = require('postcss-less').parse;
hook({
extensions: '.less',
processorOpts: {parser: lessParser},
});
camelCase boolean|string
Camelizes exported class names. Similar to css-loader?camelCase.
Available options: true
, dashes
, only
, dashesOnly
.
append
array
Appends custom plugins to the end of the PostCSS pipeline. Since the require
function is synchronous, you should provide synchronous plugins only.
prepend
array
Prepends custom plugins to the beginning of the PostCSS pipeline. Since the require
function is synchronous, you should provide synchronous plugins only.
use
array
Provides the full list of PostCSS plugins to the pipeline. Providing this cancels append
, prepend
, createImportedName
, generateScopedName
options. Synchronous plugins only.
createImportedName
function
Short alias for the postcss-modules-extract-imports plugin's createImportedName
option.
generateScopedName
string|function
Short alias for the postcss-modules-scope plugin's option. Helps you to specify the custom way to build generic names for the class selectors. You may also use a string pattern similar to the webpack's css-loader.
hook({
generateScopedName: '[name]__[local]___[hash:base64:5]'
});
or
hook({
/**
* @param {string} name Usually a class name
* @param {string} filepath
* @param {string} css
* @return {string}
*/
generateScopedName: function (name, filepath, css) {
return name;
}
});
hashPrefix
string
Short alias for the generic-names helper option. Provides additional hash uniqueness. Might be useful for projects with several stylesheets sharing a same name.
mode
string
Short alias for the postcss-modules-local-by-default plugin's option.
resolve
object
Changes the way the paths of ICSS imports will be resolved (@value a from './b.css'
and composes a from './b.css'
). Supports:
resolve.alias
object
resolve.extensions
array
— default value is['.css']
.resolve.modules
array
resolve.mainFile
string
— default value is'index.css'
.resolve.preserveSymlinks
boolean
— default value isfalse
.
See the detailed description at: https://github.com/css-modules/postcss-modules-resolve-imports#options
rootDir
string
Provides 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) from different working directories.
Debugging
debug package is used for debugging. So to turn it on simply specify the DEBUG environment variable:
DEBUG=css-modules:fetch
— to see resolved paths to the files.DEBUG=css-modules:preset
— to see whether config was found or not.DEBUG=css-modules:setup
— to see the new options list.DEBUG=css-modules:*
— to see everything.
Links
- Electron support: css-modules-electron
License
The MIT License