css-modules-require-hook

What is css-modules-require-hook?

The css-modules-require-hook package is a tool that allows you to use CSS Modules in Node.js by transforming CSS files into JavaScript objects. This is particularly useful for server-side rendering (SSR) and testing environments where you need to handle CSS files in a Node.js context.

What are css-modules-require-hook's main functionalities?

Basic Setup

This feature allows you to set up the css-modules-require-hook with a custom naming pattern for the generated CSS class names. The code sample demonstrates how to configure the hook and require a CSS file, which will be transformed into a JavaScript object.

const hook = require('css-modules-require-hook');

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

const styles = require('./styles.css');
console.log(styles);

Custom Preprocessor

This feature allows you to use a custom preprocessor like Sass. The code sample shows how to configure the hook to preprocess SCSS files using node-sass before transforming them into JavaScript objects.

const hook = require('css-modules-require-hook');
const sass = require('node-sass');

hook({
  extensions: ['.scss'],
  preprocessCss: (data, filename) => {
    return sass.renderSync({
      data,
      file: filename
    }).css;
  }
});

const styles = require('./styles.scss');
console.log(styles);

Custom CamelCase

This feature enables the conversion of CSS class names to camelCase in the resulting JavaScript object. The code sample demonstrates how to configure the hook to use camelCase and access the class names in camelCase format.

const hook = require('css-modules-require-hook');

hook({
  camelCase: true
});

const styles = require('./styles.css');
console.log(styles);
console.log(styles.someClassName); // Access class names in camelCase

Other packages similar to css-modules-require-hook

babel-plugin-react-css-modules

babel-plugin-react-css-modules is a Babel plugin that allows you to use CSS Modules in React components with a more seamless integration. Unlike css-modules-require-hook, which is used in a Node.js context, this plugin is specifically designed for use with Babel and React.

postcss-modules

postcss-modules is a PostCSS plugin that enables the use of CSS Modules. It provides more flexibility and can be integrated into a broader PostCSS setup, making it suitable for build processes that already use PostCSS. Unlike css-modules-require-hook, it is not limited to Node.js environments.

css-modules-loader-core

css-modules-loader-core is a low-level library for loading and processing CSS Modules. It provides the core functionality needed to implement CSS Modules in various environments. While css-modules-require-hook is a higher-level tool for Node.js, css-modules-loader-core offers more granular control and can be used to build custom solutions.

README

css-modules-require-hook

The require hook compiles CSS Modules in runtime. This is similar to Babel's babel/register.

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) and several modules to be installed.

• postcss version 5 or higher
• postcss-modules-values
• postcss-modules-extract-imports
• postcss-modules-local-by-default
• postcss-modules-scope

Installation

$ npm i css-modules-require-hook

Usage

In this section I've tried to cover the common cases of usage.

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.

Basic example

Basically to attach the require hook you need to require this module. If you need to adjust it see the tuning section below.

require('css-modules-require-hook');

// var styles = require('./icon.css');

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
});

append array

Appends custom plugins to the end of the PostCSS pipeline.

prepend array

Prepends custom plugins to the beginning of the PostCSS pipeline.

use array

Provides the full list of PostCSS plugins to the pipeline. Providing this cancels append, prepend, createImportedName, generateScopedName options.

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) { /* */ }
});

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']).

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.

to string

Provides to option to the LazyResult instance.

createImportedName function

Short alias for the postcss-modules-extract-imports plugin's createImportedName option.

generateScopedName 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;
  }
});

mode string

Short alias for the postcss-modules-local-by-default plugin's option.

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:setup — to see the new options list.
• DEBUG=css-modules:* — to see everything.

Links

• Electron support: css-modules-electron