npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@kitten-team/babel-plugin-react-css-modules

v1.0.0

Published

Transforms styleName to className using compile time CSS module resolution.

Downloads

6

Readme

babel-plugin-react-css-modules

GitSpo Mentions Travis build status NPM version Canonical Code Style Gitter Twitter Follow

Transforms styleName to className using compile time CSS module resolution.

In contrast to react-css-modules, babel-plugin-react-css-modules has a lot smaller performance overhead (0-10% vs +50%; see Performance) and a lot smaller size footprint (less than 2kb vs 17kb react-css-modules + lodash dependency).

CSS Modules

CSS Modules are awesome! If you are not familiar with CSS Modules, it is a concept of using a module bundler such as webpack to load CSS scoped to a particular document. CSS module loader will generate a unique name for each CSS class at the time of loading the CSS document (Interoperable CSS to be precise). To see CSS Modules in practice, webpack-demo.

In the context of React, CSS Modules look like this:

import React from 'react';
import styles from './table.css';

export default class Table extends React.Component {
  render () {
    return <div className={styles.table}>
      <div className={styles.row}>
        <div className={styles.cell}>A0</div>
        <div className={styles.cell}>B0</div>
      </div>
    </div>;
  }
}

Rendering the component will produce a markup similar to:

<div class="table__table___32osj">
  <div class="table__row___2w27N">
    <div class="table__cell___1oVw5">A0</div>
    <div class="table__cell___1oVw5">B0</div>
  </div>
</div>

and a corresponding CSS file that matches those CSS classes.

Awesome!

However, there are several disadvantages of using CSS modules this way:

  • You have to use camelCase CSS class names.
  • You have to use styles object whenever constructing a className.
  • Mixing CSS Modules and global CSS classes is cumbersome.
  • Reference to an undefined CSS Module resolves to undefined without a warning.

babel-plugin-react-css-modules automates loading of CSS Modules using styleName property, e.g.

import React from 'react';
import './table.css';

export default class Table extends React.Component {
  render () {
    return <div styleName='table'>
      <div styleName='row'>
        <div styleName='cell'>A0</div>
        <div styleName='cell'>B0</div>
      </div>
    </div>;
  }
}

Using babel-plugin-react-css-modules:

  • You are not forced to use the camelCase naming convention.

  • You do not need to refer to the styles object every time you use a CSS Module.

  • There is clear distinction between global CSS and CSS modules, e.g.

    <div className='global-css' styleName='local-module'></div>

Difference from react-css-modules

react-css-modules introduced a convention of using styleName attribute to reference CSS module. react-css-modules is a higher-order React component. It is using the styleName value to construct the className value at the run-time. This abstraction frees a developer from needing to reference the imported styles object when using CSS modules (What's the problem?). However, this approach has a measurable performance penalty (see Performance).

babel-plugin-react-css-modules solves the developer experience problem without impacting the performance.

Performance

The important metric here is the "Difference from the base benchmark". "base" is defined as using React with hardcoded className values. The lesser the difference, the bigger the performance impact.

Note: This benchmark suite does not include a scenario when babel-plugin-react-css-modules can statically construct a literal value at the build time. If a literal value of the className is constructed at the compile time, the performance is equal to the base benchmark.

|Name|Operations per second (relative margin of error)|Sample size|Difference from the base benchmark| |---|---|---|---| |Using className (base)|9551 (±1.47%)|587|-0%| |react-css-modules|5914 (±2.01%)|363|-61%| |babel-plugin-react-css-modules (runtime, anonymous)|9145 (±1.94%)|540|-4%| |babel-plugin-react-css-modules (runtime, named)|8786 (±1.59%)|527|-8%|

Platform info:

  • Darwin 16.1.0 x64
  • Node.JS 7.1.0
  • V8 5.4.500.36
  • NODE_ENV=production
  • Intel(R) Core(TM) i7-4870HQ CPU @ 2.50GHz × 8

View the ./benchmark.

Run the benchmark:

git clone [email protected]:gajus/babel-plugin-react-css-modules.git
cd ./babel-plugin-react-css-modules
npm install
npm run build
cd ./benchmark
npm install
NODE_ENV=production ./test

How does it work?

  1. Builds index of all stylesheet imports per file (imports of files with .css or .scss extension).
  2. Uses postcss to parse the matching CSS files into a lookup of CSS module references.
  3. Iterates through all JSX element declarations.
  4. Parses the styleName attribute value into anonymous and named CSS module references.
  5. Finds the CSS class name matching the CSS module reference:
    • If styleName value is a string literal, generates a string literal value.
    • If styleName value is a jSXExpressionContainer, uses a helper function (getClassName) to construct the className value at the runtime.
  6. Removes the styleName attribute from the element.
  7. Appends the resulting className to the existing className value (creates className attribute if one does not exist).

Configuration

Configure the options for the plugin within your .babelrc as follows:

{
  "plugins": [
    ["react-css-modules", {
      "option": "value"
    }]
  ]
}

Options

|Name|Type|Description|Default| |---|---|---|---| |context|string|Must match webpack context configuration. css-loader inherits context values from webpack. Other CSS module implementations might use different context resolution logic.|process.cwd()| |exclude|string|A RegExp that will exclude otherwise included files e.g., to exclude all styles from node_modules exclude: 'node_modules'| |filetypes|?FiletypesConfigurationType|Configure postcss syntax loaders like sugarss, LESS and SCSS and extra plugins for them. || |generateScopedName|?GenerateScopedNameConfigurationType|Refer to Generating scoped names. If you use this option, make sure it matches the value of localIdentName in webpack config. See this issue |[path]___[name]__[local]___[hash:base64:5]| |removeImport|boolean|Remove the matching style import. This option is used to enable server-side rendering.|false| |webpackHotModuleReloading|boolean|Enables hot reloading of CSS in webpack|false| |handleMissingStyleName|"throw", "warn", "ignore"|Determines what should be done for undefined CSS modules (using a styleName for which there is no CSS module defined). Setting this option to "ignore" is equivalent to setting errorWhenNotFound: false in react-css-modules. |"throw"| |attributeNames|?AttributeNameMapType|Refer to Custom Attribute Mapping|{"styleName": "className"}| |skip|boolean|Whether to apply plugin if no matching attributeNames found in the file|false| |autoResolveMultipleImports|boolean|Allow multiple anonymous imports if styleName is only in one of them.|false|

Missing a configuration? Raise an issue.

Note: The default configuration should work out of the box with the css-loader.

Option types (flow)

type FiletypeOptionsType = {|
  +syntax: string,
  +plugins?: $ReadOnlyArray<string | $ReadOnlyArray<[string, mixed]>>
|};

type FiletypesConfigurationType = {
  [key: string]: FiletypeOptionsType
};

type GenerateScopedNameType = (localName: string, resourcePath: string) => string;

type GenerateScopedNameConfigurationType = GenerateScopedNameType | string;

type AttributeNameMapType = {
  [key: string]: string
};

Configurate syntax loaders

To add support for different CSS syntaxes (e.g. SCSS), perform the following two steps:

  1. Add the postcss syntax loader as a development dependency:
npm install postcss-scss --save-dev
  1. Add a filetypes syntax mapping to the Babel plugin configuration. For example for SCSS:
"filetypes": {
  ".scss": {
    "syntax": "postcss-scss"
  }
}

And optionally specify extra plugins:

"filetypes": {
  ".scss": {
    "syntax": "postcss-scss",
    "plugins": [
      "postcss-nested"
    ]
  }
}

NOTE: postcss-nested is added as an extra plugin for demonstration purposes only. It's not needed with postcss-scss because SCSS already supports nesting.

Postcss plugins can have options specified by wrapping the name and an options object in an array inside your config:

  "plugins": [
    ["postcss-import-sync2", {
      "path": ["src/styles", "shared/styles"]
    }],
    "postcss-nested"
  ]

Custom Attribute Mapping

You can set your own attribute mapping rules using the attributeNames option.

It's an object, where keys are source attribute names and values are destination attribute names.

For example, the <NavLink> component from React Router has a activeClassName attribute to accept an additional class name. You can set "attributeNames": { "activeStyleName": "activeClassName" } to transform it.

The default styleName -> className transformation will not be affected by an attributeNames value without a styleName key. Of course you can use { "styleName": "somethingOther" } to change it, or use { "styleName": null } to disable it.

Installation

When babel-plugin-react-css-modules cannot resolve CSS module at a compile time, it imports a helper function (read Runtime styleName resolution). Therefore, you must install babel-plugin-react-css-modules as a direct dependency of the project.

npm install babel-plugin-react-css-modules --save

React Native

If you'd like to get this working in React Native, you're going to have to allow custom import extensions, via a rn-cli.config.js file:

module.exports = {
  getAssetExts() {
    return ["scss"];
  }
}

Remember, also, that the bundler caches things like plugins and presets. If you want to change your .babelrc (to add this plugin) then you'll want to add the --reset-cache flag to the end of the package command.

Demo

git clone [email protected]:gajus/babel-plugin-react-css-modules.git
cd ./babel-plugin-react-css-modules/demo
npm install
npm start
open http://localhost:8080/

Conventions

Anonymous reference

Anonymous reference can be used when there is only one stylesheet import.

Format: CSS module name.

Example:

import './foo1.css';

// Imports "a" CSS module from ./foo1.css.
<div styleName="a"></div>;

Named reference

Named reference is used to refer to a specific stylesheet import.

Format: [name of the import].[CSS module name].

Example:

import foo from './foo1.css';
import bar from './bar1.css';

// Imports "a" CSS module from ./foo1.css.
<div styleName="foo.a"></div>;

// Imports "a" CSS module from ./bar1.css.
<div styleName="bar.a"></div>;

Example transpilations

Anonymous styleName resolution

When styleName is a literal string value, babel-plugin-react-css-modules resolves the value of className at the compile time.

Input:

import './bar.css';

<div styleName="a"></div>;

Output:

import './bar.css';

<div className="bar___a"></div>;

Named styleName resolution

When a file imports multiple stylesheets, you must use a named reference.

Have suggestions for an alternative behaviour? Raise an issue with your suggestion.

Input:

import foo from './foo1.css';
import bar from './bar1.css';

<div styleName="foo.a"></div>;
<div styleName="bar.a"></div>;

Output:

import foo from './foo1.css';
import bar from './bar1.css';

<div className="foo___a"></div>;
<div className="bar___a"></div>;

Runtime styleName resolution

When the value of styleName cannot be determined at the compile time, babel-plugin-react-css-modules inlines all possible styles into the file. It then uses getClassName helper function to resolve the styleName value at the runtime.

Input:

import './bar.css';

<div styleName={Math.random() > .5 ? 'a' : 'b'}></div>;

Output:

import _getClassName from '@kitten-team/babel-plugin-react-css-modules/dist/browser/getClassName';
import foo from './bar.css';

const _styleModuleImportMap = {
  foo: {
    a: 'bar__a',
    b: 'bar__b'
  }
};

<div styleName={_getClassName(Math.random() > .5 ? 'a' : 'b', _styleModuleImportMap)}></div>;

Limitations

Have a question or want to suggest an improvement?

FAQ

How to migrate from react-css-modules to babel-plugin-react-css-modules?

Follow the following steps:

  • Remove react-css-modules.
  • Add babel-plugin-react-css-modules.
  • Configure .babelrc (see Configuration).
  • Remove all uses of the cssModules decorator and/or HoC.

If you are still having problems, refer to one of the user submitted guides:

How to reference multiple CSS modules?

react-css-modules had an option allowMultiple. allowMultiple allows multiple CSS module names in a styleName declaration, e.g.

<div styleName='foo bar' />

This behaviour is enabled by default in babel-plugin-react-css-modules.

How to live reload the CSS?

babel-plugin-react-css-modules utilises webpack Hot Module Replacement (HMR) to live reload the CSS.

To enable live reloading of the CSS:

Note:

This enables live reloading of the CSS. To enable HMR of the React components, refer to the Hot Module Replacement - React guide.

Note:

This is a webpack specific option. If you are using babel-plugin-react-css-modules in a different setup and require CSS live reloading, raise an issue describing your setup.

I get a "Cannot use styleName attribute for style name '[X]' without importing at least one stylesheet." error

First, ensure that you are correctly importing the CSS file following the conventions.

If you are correctly importing but using different CSS (such as SCSS), this is likely happening because your CSS file wasn't able to be successfully parsed. You need to configure a syntax loader.

I get a "Could not resolve the styleName '[X]' error but the class exists in the CSS included in the browser.

First, verify that the CSS is being included in the browser. Remove from styleName the reference to the CSS class that's failing and view the page. Search through the <style> tags that have been added to the <head> and find the one related to your CSS module. Copy the code into your editor and search for the class name.

Once you've verified that the class is being rendered in CSS, the likely cause is that the babel-plugin-react-css-modules is unable to find your CSS class in the parsed code. If you're using different CSS (such as SCSS), verify that you have configured a syntax loader.

However, if you're using a syntaxes such as postcss-scss or postcss-less, they do not compile down to CSS. So if you are programmatically building a class name (see below), webpack will be able to generate the rendered CSS from SCSS/LESS, but babel-plugin-react-css-modules will not be able to parse the SCSS/LESS.

A SCSS example:

$scales: 10, 20, 30, 40, 50;

@each $scale in $scales {
  .icon-#{$scale} {
    width: $scale;
    height: $scale;
  }
  }

babel-plugin-react-css-modules will not receive icon-10 or icon-50, but icon-#{$scale}. That is why you receive the error that styleName "icon-10" cannot be found.