@ecomfe/class-names-loader

class-names-loader

Webpack loader to transform style into classNames bindings.

Inspired by itsmepetrov/classnames-loader and have a total written to introduce features and breaking changes like:

1. Written in TypeScript.
2. Support style-loader's esModule format only.
3. Compatible both default export and named export.
4. Drop support for IE < 9 to minimize output code.
5. Produce ES module code to enable optimizations like module concatenation.

We will keep active maintain.

Install

npm install -D class-names-loader

Auto binding

This loader is to bind a CSS modules enabled style-loader output into a classnames compatible function, received class names are mapped to CSS modules transformed ones:

import c from './index.css';

// May renders as `<div class="title-0f2bd">
<div className={c('title')} />

This function is also a mapping object from raw class names to transformed ones, so c.title is identical to c('title').

Also it behaves like classnames and accept more complex arguments like c('title', {emphasis: props.isHeading}, props.className). Any class names not in CSS file are rended as is, c('some-class') returns "some-class".

Usage

A traditional webpack configuration looks like:

{
    module: {
        rules: [
            {
                test: /\.css$/,
                use: [
                    {
                        loader: 'class-names-loader',
                        options: {
                            // options
                        },
                    },
                    {
                        loader: 'style-loader',
                        modules: true,
                    },
                    {
                        loader: 'css-loader',
                        modules: true,
                    },
                ],
            },
        ],
    },
}

style-loader >= 2 enables esModule option by default, and it must be enabled when combine with class-names-loader.

Options

interface Options {
    // Custom classnames module path, by default it imports `classnames`
    classNamesModule?: string;
    // Use named import from style-loader
    namedImport?: boolean;
}

Custom classnames

By default we require classnames module to be installed and import it, you can also install a custom module and pass it's module path to classNameModule option.

This is especially useful when you create a custom build tool and want to encapsulate classnames inside this tool:

// Build tool with class-names-loader and classnames installed locally
{
    loader: require.resolve('class-names-loader'),
    options: {
        classNamesModule: require.resolve('classnames'),
    },
}

Named import

If you have namedExport option enabled in style-loader, you should also enable namedImport option to make it compatible.

Changelog

2.0.0 (2021-04-30)

⚠ BREAKING CHANGES

• Require webpack@5 as peer

Bug Fixes

• class name assign to function may fail in earlier browsers (387e94f)