# css-modules-require-hook

> A require hook to compile CSS Modules on the fly

Latest version **4.2.3** (published 2018-01-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install css-modules-require-hook
pnpm add css-modules-require-hook
yarn add css-modules-require-hook
bun add css-modules-require-hook
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.2.3 |
| Published | 2018-01-08 |
| First published | 2015-08-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/css-modules-require-hook) |
| Module format | CommonJS |
| Node | >= 4 |
| Dependencies | 12 |
| Known vulnerabilities | 0 (+6 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 483 |
| Author | Alexey Litvinov |
| Maintainers | sullenor |
| Keywords | css-modules, require, hook |

## Links

- npm: https://www.npmjs.com/package/css-modules-require-hook
- Repository: https://github.com/css-modules/css-modules-require-hook
- Issues: https://github.com/css-modules/css-modules-require-hook/issues
- npm.io page: https://npm.io/package/css-modules-require-hook

## Dependencies (12)

- [debug](https://npm.io/package/debug.md) ^2.2.0
- [lodash](https://npm.io/package/lodash.md) ^4.3.0
- [postcss](https://npm.io/package/postcss.md) ^6.0.1
- [seekout](https://npm.io/package/seekout.md) ^1.0.1
- [generic-names](https://npm.io/package/generic-names.md) ^1.0.1
- [glob-to-regexp](https://npm.io/package/glob-to-regexp.md) ^0.3.0
- [icss-replace-symbols](https://npm.io/package/icss-replace-symbols.md) ^1.0.2
- [postcss-modules-scope](https://npm.io/package/postcss-modules-scope.md) ^1.0.0
- [postcss-modules-values](https://npm.io/package/postcss-modules-values.md) ^1.1.1
- [postcss-modules-extract-imports](https://npm.io/package/postcss-modules-extract-imports.md) ^1.0.0
- [postcss-modules-resolve-imports](https://npm.io/package/postcss-modules-resolve-imports.md) ^1.3.0
- [postcss-modules-local-by-default](https://npm.io/package/postcss-modules-local-by-default.md) ^1.0.1

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 4.2.3 (latest) — 2018-01-08
- 4.2.2 (next) — 2017-09-10
- 4.1.0 (beta) — 2017-08-10
- 4.2.1 — 2017-09-10
- 4.2.0 — 2017-09-10
- 4.0.6 — 2017-03-20
- 4.1.0-beta — 2017-03-05
- 4.0.5 — 2016-10-03
- 4.0.4 — 2016-10-03
- 4.0.3 — 2016-09-20
- 4.0.2 — 2016-08-18
- 4.0.1 — 2016-05-29
- 4.0.0 — 2016-03-07
- 3.0.0 — 2016-02-24
- 3.0.0-beta — 2016-02-23
- … 21 more at https://npm.io/package/css-modules-require-hook/versions

## README

css-modules-require-hook
========================

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/). See the example: [demo](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](http://glenmaddern.com/articles/css-modules) by Glen Maddern.

## Features

Compiling in runtime, [universal](https://medium.com/@mjackson/universal-javascript-4761051b7ae9) usage.


## Requirements

To use this tool we require [Node.js v0.12.x](https://github.com/nodejs/node) (or higher).

## Installation

```bash
$ 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:

```javascript
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:

```javascript
// cmrh.conf.js
module.exports = {
  generateScopedName: '[name]__[local]___[hash:base64:5]',
};
```

```javascript
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`.


```javascript
// server.js
import csshook from 'css-modules-require-hook/preset' // import hook before routes
import routes from '/shared/views/routes'

// create server, etc
```

```javascript
// 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:

```bash
$ 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

```javascript
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

```javascript
var hook = require('css-modules-require-hook');

hook({
  generateScopedName: '[name]__[local]___[hash:base64:5]',
});
```

### Using Stylus as a preprocessor

```javascript
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.

```javascript
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:

```javascript
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.

```javascript
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.

```javascript
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](https://github.com/postcss/postcss/blob/master/docs/api.md#processorprocesscss-opts). It can be usefull if you want to set the custom parser, for example: [postcss-less](https://github.com/gilt/postcss-less).

```javascript
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](https://github.com/webpack/css-loader#camel-case).

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](https://github.com/css-modules/postcss-modules-extract-imports) plugin's `createImportedName` option.

### `generateScopedName` string|function

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.
You may also use a string pattern similar to the webpack's [css-loader](https://github.com/webpack/css-loader#local-scope).

```javascript
hook({
  generateScopedName: '[name]__[local]___[hash:base64:5]'
});
```

or

```javascript
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](https://github.com/css-modules/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](https://github.com/css-modules/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` `array` — default value is `'index.css'`.
- `resolve.preserveSymlinks` `boolean` — default value is `false`.

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](https://github.com/css-modules/css-modulesify)) from different working directories.


## Debugging

[debug](https://www.npmjs.com/package/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](https://github.com/KenPowers/css-modules-electron)

## License

> The MIT License

---
_Source: https://npm.io/package/css-modules-require-hook · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._