Solving the problem of class name CSS conflicts in a React application using a webpack loader

Greetings, friends!

It all started with the fact that I intended to develop something so to speak for the soul. The React application had to be rendered on top of something else, for example, some website, the question arose that the CSS classes of my application might conflict with the existing infrastructure, well, of course I came to the conclusion that you need to implement prefixes for every seediest class, well, or wrap all the definitions in the class of my main container, I still chose the prefixes. But soon I was tired of them, they turned out so much that it all seemed empty copy-paste to me, and then I thought about creating my own loader for the webpack. As a result, work on it turned from a fly into an elephant, ideas overwhelmed me and as a result, my mind and hands created a monster that almost went out of my control.

I admit, during these weeks and a half of writing it, I am wildly tired of thinking, coding and documenting first in English, then translating from my clumsy English to a slightly less clumsy native language, I would rather have it already. But now I am a distinguished markdown programmer and a regular user.

So, I just needed a mechanism to replace the classname with my-app-classname, but in the end I’ll describe what I’ll describe in detail. I published the result of my work on npm.

For starters, perhaps someone will be interested in how to create your own webpack loader. Simple enough: create a folder, call it my-divine-loader, in it an index JS file and such code:

const {getOptions} = require('loader-utils'); module.exports = function(source) { //      //      this //  getOptions    ,    webpack.config.js return source; } 

Installation

NPM

 npm install --save classy-loader 

Example play

Link to Github repository

Adding a Webpack configuration

To begin with we will set the necessary settings.

 const classy = require('classy-loader'); classy.init({ attributeName: 'class', extraAttributeName: 'classes', globalPrefix: 'awesome-example-app', delimiter: '-', obfuscation: false, obfuscatedLength: 4, autoPrefixMode: false, prefixAutoResolving: false }); //... module: { rules: [ { test: /\.js$/, loaders: [ { loader: 'babel-loader', options: { //.... } }, { loader: 'classy-loader?parser=js' } ] }, { test: /\.s?css$/, loader: ExtractTextPlugin.extract( { fallback: 'style-loader', use: [ 'css-loader?root=...', 'sass-loader', 'classy-loader?parser=css' ] } ) } ] } //... 

As you can see from the example, the loader should be added after Babel and standard style loaders.

attributeName

The name of the DOM attribute of the elements that will be parsed by the loader.
It can be anything and will be converted to the standard attribute "className".
By default, this parameter is "class".

 render() { return ( <div class=".self"> ... </div> ) } 

or so

 render() { return ( <div whateverName=".self"> ... </div> ) } 

So "class" and "whateverName" are our attributeName names.
After processing by the loader, the code will look like this:

 render() { return ( <div className="awesome-example-app"> ... </div> ) } 

For the loader, "self" is a keyword that means our global or local prefix of the class name.

Specifically, in this case, we do not have a local prefix, so "self" will be equal to the global value.

extraAttributeName

The name of the attribute for React elements, which will be parsed in the same way, but not change its name.
It can also be used for the names of variables and keys of objects that need to be parsed.
By default it is "classes".

 render() { return ( <Button classes=".action-button awesome-button">  ! </Button> ) } let classes = ".some-class"; let object = { classes: ".some-other-class" }; 

At the output we get all the same attribute "classes":

 render() { return ( <Button classes="awesome-example-app-action-button awesome-button"> Do it! </Button> ) } let classes = "awesome-example-app-some-class"; let object = { classes: "awesome-example-app-some-other-class" }; 

globalPrefix

The prefix that will be added to the class names of the DOM elements.
Special syntax will tell the loader whether to add one of the prefixes or not.
By default, it is empty, so this means that no prefix will be added if no local prefix is ​​specified.

 render() { return ( <div class=".thing"> ... </div> ) } 

will become

 render() { return ( <div className="awesome-example-app-thing"> ... </div> ) } 

A dot means that the class name must have a prefix.
More about parser syntax is presented below.

delimiter

A character or word with which prefixes and class names will be combined.
The default is "-".

 render() { return ( <div class=".some-item"> ... </div> ) } 

So, if our "delimiter" is "_", the code will be like this:

 render() { return ( <div className="awesome-example-app_some-item"> ... </div> ) } 

prefixAutoResolving

If this parameter is set, the loader will try to determine the local prefix on its own.
By default it is not set.
There are three choices:

prefixAutoResolving: "content"

To begin with, the loader will try to find a string that contains:
export default (class | function) MySuperClassName

Then will search for:
export default connect (...) (MySuperClassName)

If not find:
class MySuperClassName

Well, in the end, take the first line with the following code:
function MySuperClassName

So "MySuperClassName" will be converted to the local prefix "my" + delimiter + "super" + delimiter + "class" + delimiter + "name".

For CSS files, the loader will look for data in the cache, which is populated when processing JS files.
If the cache contains information about the prefixes for the index file in the same directory,
they will be used, so JS and CSS will be synchronized.
You should have JS loaders in front of the CSS loaders so that the parser has the right cache.

 export default class MySuperButton extends React.Component { render() { return ( <div class=".self"> <span class=".inner"> .... </span> </div> ) } } 

will become

 export default class MySuperButton extends React.Component { render() { return ( <div className="awesome-example-app-my-super-button"> <span className="awesome-example-app-my-super-button-inner"> .... </span> </div> ) } } 

You can also set JS / CSS local prefixes using special directives.
More about them is written below.

prefixAutoResolving: "file"

The loader will form a local prefix from the names of the JS / CSS files:
"SuperItem.js" or "super-item.js" or "super_item.js"
will turn into the prefix "super" + delimiter + "item".
For this method, the files must be named the same so that they are synchronized.

prefixAutoResolving: "folder"

The loader will form a local prefix from directory names:
"SuperItem / index.js" or "super-item / some.js" or "super_item / any.js"
will become the prefix "super" + delimiter + "item".
The easiest way to synchronize JS / CSS, also your structure will be more understandable.

obfuscation

If set to true, the loader will obfuscate the class names in the JS and CSS files.
Be careful, all CSS classes will be changed anyway, and JS is only inside the "attributeName" and extraAttributeName attributes .
By default, this option is not active.

 render() { return ( <div class=".button small"> ... </div> ) } 

will become

 render() { return ( <div className="w4fq5wq dhet7s5"> ... </div> ) } 

obfuscatedLength

The length in characters up to which class names will be obfuscated.
The default value is "7".

So, if we have "obfuscatedLength" equal to 4

 render() { return ( <div className="ald8 jd6g"> ... </div> ) } 

autoPrefixMode

Loader will automatically add prefixes to our class names.
You will need to use a slightly different string format for class names.
By default, this option is disabled.

For example, this is a CSS class entry for non-autoprefix mode:
( "prefixAutoResolving" is set to "content")

 export default class Container extends React.Component { render() { return ( <div class=".self wide ..area"> <div class=".content content"> ... </div> </div> ) } } 

will be converted to

 export default class Container extends React.Component { render() { return ( <div className="awesome-example-app-container wide awesome-example-app-area"> <div class="awesome-example-app-container-content content"> ... </div> </div> ) } } 

Here the local prefix is ​​"awesome-example-app-container" (global prefix plus automatically added on behalf of the class "Container").
So in this mode you need to add points for prefixes: one for local and two for global.

And finally, an example of the description of CSS classes for auto-prefix mode
( "prefixAutoResolving" is set to "content")
As a result, we get the same thing as in the first case.

 export default class Container extends React.Component { render() { return ( <div class="self ..wide .area"> <div class="content ..content"> ... </div> </div> ) } } 

will also

 export default class Container extends React.Component { render() { return ( <div className="awesome-example-app-container wide awesome-example-app-area"> <div class="awesome-example-app-container-content content"> ... </div> </div> ) } } 

In this mode, you do not need to add a point for the local prefix; one must be added for the global and two for the names of the classes without the prefix.

In CSS files, everything works according to the same principles (you need to add the same number of points, so you will get a maximum of three points)

Non-autoprefix mode:

 /* ,      (    ) */ .with.addedPrefix.container; ..self { position: relative; &...area { background-color: #eee; border: 1px solid #aaa; } &.wide { width: 80%; } ..content { padding: 10px; &.content { padding-top: 0; } } } 

will be

 .awesome-example-app-container { position: relative; &.awesome-example-app-area { background-color: #eee; border: 1px solid #aaa; } &.wide { width: 80%; } .awesome-example-app-container-content { padding: 10px; &.content { padding-top: 0; } } } 

And the same for auto-prefix mode:

 /* ,      (    ) */ .with.addedPrefix.container; .self { position: relative; &..area { background-color: #eee; border: 1px solid #aaa; } &...wide { width: 80%; } .content { padding: 10px; &...content { padding-top: 0; } } } 

will give the same result

 .awesome-example-app-container { position: relative; &.awesome-example-app-area { background-color: #eee; border: 1px solid #aaa; } &.wide { width: 80%; } .awesome-example-app-container-content { padding: 10px; &.content { padding-top: 0; } } } 

Directives

JS directives

• with prefix 'some-prefix';

  
  Creates a local version of the global prefix that overrides it within one file.
  Two points will still add the standard global prefix defined in the config.
  

 //   // prefixAutoResolving: "content" // ...imports with prefix 'crazy-app'; export default class Container extends React.Component { render() { return ( <div class=".self"> <div class=".title ..bigger"> ... </div> <div class=".content"> ... </div> </div> ) } } 

will become

 // ...imports export default class Container extends React.Component { render() { return ( <div class="crazy-app-container"> <div class="crazy-app-container-title awesome-example-app-bigger"> ... </div> <div class="crazy-app-container-title"> ... </div> </div> ) } } 

And now the result for the case when "prefixAutoResolving" is set to false,
so we don't have an added local prefix,
only redefined global

 // ...imports export default class Container extends React.Component { render() { return ( <div class="crazy-app"> <div class="crazy-app-title awesome-example-app-bigger"> ... </div> <div class="crazy-app-title"> ... </div> </div> ) } } 

• with auto prefix 'some-prefix';

  
  Everything is the same as with the directive above, plus it sets the auto-prefix mode within this file.
  

• with addedPrefix 'some-additional-prefix';

  
  Specifies the added prefix for local use.
  This directive does something like the “prefixAutoResolving” parameter, so finding its loader will not automatically detect the prefix.
  

 //   // ...imports with addedPrefix 'dialog'; export default class Dialog extends React.Component { render() { return ( <div class=".self"> <div class=".title ..bigger"> ... </div> <div class=".content"> ... </div> </div> ) } } 

will be

 // ...imports export default class Dialog extends React.Component { render() { return ( <div class="awesome-example-app-dialog"> <div class="awesome-example-app-dialog-title awesome-example-app-bigger"> ... </div> <div class="awesome-example-app-dialog-content"> ... </div> </div> ) } } 

• with auto addedPrefix 'some-additional-prefix';

  
  All the same as for the directive above, plus sets the auto-prefix mode within the file.
  

• with auto prefix;

  
  Sets the auto-prefix mode within this file.
  

CSS directives

CSS directives do exactly the same thing and look very similar to JS versions,
the only difference is in the last directive, which is not for JS files

• .with.prefix.some-prefix;

  
  

• .with.auto.prefix.some-prefix;

  
  

• .with.addedPrefix.additional-prefix;

  
  

• .with.auto.addedPrefix.additional-prefix;

  
  

• .with.auto.prefix;

  
  

• .with.no.prefix;

  
  Instructs the loader not to add any prefixes, even if there is a ".." / "..."
  Two or three points will be perceived as one.
  

Syntax of CSS class string notation

 render() { return ( <div class="name .name ..name $name $$name prefix::name .$name ..$name"> ... </div> ) } 

name

Indicates the name of a class without prefixes in non-autoprefix mode.
Indicates the name of a class with a local prefix in auto-prefix mode.

 render() { return ( <div className="name"> ... </div> //and <div className="local-prefix-name"> ... </div> ) } 

.name

Indicates the name of a class with a local prefix in non-autoprefix mode.
Indicates the name of a class with a global prefix in auto-prefix mode.

 render() { return ( <div className="local-prefix-name"> ... </div> //and <div className="global-prefix-name"> ... </div> ) } 

..name

Indicates the name of a class with a global prefix in non-autoprefix mode.
Indicates the name of a class without prefixes in auto-prefix mode.

 render() { return ( <div className="global-prefix-name"> ... </div> //and <div className="name"> ... </div> ) } 

$ name

"Merjit" is a class name or an array of names from a variable.
The loader will automatically add the "import" of the module necessary for the "merging".
The variable should already contain the name / class names with prefixes or be obfuscated.

 render() { return ( <div className={classy(name)}> ... </div> ) } 

An example of how this works in principle:

In the parent component, use extraAttributeName: "classes"

 render() { return ( <Icon classes="..large green"> resize </Icon> ) } 

in the child (named Icon)

 with addedPrefix 'icon'; export default function Icon({classes, children}) { return ( <i class=".self $classes material-icons"> {children} </i> ) } 

so in the end we get

in parent:

 render() { return ( <Icon classes="awesome-example-app-large green"> resize </Icon> ) } 

in the component "Icon" import is automatically added

 import classy from 'classy-loader/classy'; export default function Icon({classes, children}) { return ( <i className={classy("awesome-example-app-icon", classes, "material-icons")}> {children} </i> ) } 

And so the code will look in the assembled "bundle":

 return _react2.default.createElement( 'i', _extends({ className: (0, _classy2.default)("awesome-example-app-icon", classes, "material-icons") }), children ); 

$$ name

The same as with the variable above, but tells the loader that the variable is a string, not an array or "undefined",
so that the loader does not use the merging function, however, if there are other variables of the form $ name, the function will still be used

 render() { return ( <div class="$classes"> <div class="$$className"> ... </div> </div> ) } 

will become

 render() { return ( <div className={classy(classes)}> <div className={className}> ... </div> </div> ) } 

prefix :: name

Adds a local (with respect to the child component) prefix to the class name.
Take the example of Icon above and slightly modify it.

 render() { return ( <Icon classes="..large green"> <span class="icon::thing"> resize </span> </Icon> ) } 

In principle, you can simply use the ".icon-thing" entry,
but the first option will connect them with the necessary separator.

 render() { return ( <Icon classes="..large green"> <span class="..icon-thing"> resize </span> </Icon> ) } 

So we will have this HTML

 <i className="awesome-example-app-icon awesome-example-app-large green material-icons"> <span class="awesome-example-app-icon-thing"> resize </span> </i> 

. $ name

Dynamic class name, local prefix plus variable value.
This is always a local prefix regardless of mode.

 with addedPrefix 'tab'; export default function Tab({classes, children, isActive}) { render() { let className = isActive ? 'active' : 'inactive'; return ( <div class=".self .$className $classes"> {children} </div> ) } } 

will be

 import classy from 'classy-loader/classy'; export default function Tab({classes, children, isActive}) { render() { let className = isActive ? 'active' : 'inactive'; return ( <div className={classy("awesome-example-app-tab", "awesome-example-app-tab-" + className, classes)}> {children} </div> ) } } 

.. $ name

Dynamic class name, global prefix plus variable value.
This is always a global prefix regardless of mode.

 with addedPrefix 'button'; export default class Button extends React.Component { render() { let className = 'active'; return ( <div classes=".self ..$className"> ... </div> ) } } 

will be

 export default class Button extends React.Component { render() { let className = 'active'; return ( <div className={"awesome-example-app-button awesome-example-app-" + className}> ... </div> ) } } 

It is impossible (or just hs how) obfuscate such a dynamic class
but for such purposes a special "fake" function $ classy has been introduced.
She creates a "map" of class names for the obfuscator.

Here is an example:

 let className = $classy(color, '..color-', ['red', 'green']); className = $classy(color, '.color-', ['blue', 'yellow']); className = $classy(number, '..', ['one', 'two']); className = $classy(quality, '.', ['good', 'bad']); className = $classy(name, '', ['John', 'Rick']); 

In non-autoprefix mode will be converted to:

 let className = { red: 'awesome-example-app-color-red', green: 'awesome-example-app-color-green' }[color]; className = { blue: 'awesome-example-app-button-color-blue', yellow: 'awesome-example-app-button-color-yellow' }[color]; className = { one: 'awesome-example-app-one', two: 'awesome-example-app-two' }[number]; className = { good: 'awesome-example-app-button-good', bad: 'awesome-example-app-button-bad' }[quality]; className = { John: 'John', Rick: 'Rick' }[name]; 

And in autoprefix mode will be:

 let className = { red: 'color-red', green: 'color-green' }[color]; className = { blue: 'awesome-example-app-color-blue', yellow: 'awesome-example-app-color-yellow' }[color]; className = { one: 'one', two: 'two' }[number]; className = { good: 'awesome-example-app-good', bad: 'awesome-example-app-bad' }[quality]; className = { John: 'awesome-example-app-button-John', Rick: 'awesome-example-app-button-Rick' }[name]; 

So the variable "className" will be the real name of the class, which can be obfuscated and look like:

 let className = { red: 'hby457r', green: 'fhelf76', blue: 'dh409gl', yellow: 'sl58sgf', orange: 'dl50gak', ... }[color]; 

Another way for these needs, but with different “patterns”:

 let className = $classy(colorValue, { red: "..red item::reddish", green: "..green ..greenish", ... }); 

Will give the code:

 let className = { red: 'awesome-example-app-red awesome-example-app-item-reddish', green: 'awesome-example-app-green awesome-example-app-greenish', ... }[colorValue]; 

Well, the last way you can use $ classy :

 with addedPrefix 'catalog'; // .... let className = $classy(".item item ..some-item $classes"); 

will become

 import classy from 'classy-loader/classy'; // .... let className = classy("awesome-example-app-catalog-item", "item", "awesome-example-app-some-item", classes); 

Conditional (ternary) CSS class entries

For a start, simple

 //    globalPrefix = 'app' //    autoPrefixMode = false //    addedPrefix = 'item' render() { let active = true; return ( <div class="name $active?active"> ... </div> <div class=".name $active?.active"> ... </div> <div class="$active?..active:..inactive"> ... </div> <div class="$active?$className:disabled"> ... </div> <div class="$!active?inactive"> ... </div> ) } 

will become

 render() { let active = true; return ( <div className={classy("name", active ? "active" : "")}> ... </div> <div className={classy("app-item-name", active ? "app-item-active" : "")}> ... </div> <div className={classy(active ? "app-active" : "app-inactive")}> ... </div> <div className={classy(active ? className : "disabled")}> ... </div> <div className={classy(!active ? "inactive" : "")} > ... </div> ) } 

You can add spaces between the characters "?" and ":"

 render() { return ( <div class="$active ? active : inactive"> ... </div> ) } 

But in the condition spaces are not allowed:

 render() { return ( <div class="$active === true ? active : inactive"> ... </div> ) } 

Such an entry will be converted to an incorrect view class name.

 render() { return ( <div className="1 === true active inactive"> ... </div> ) } 

If you so want to add spaces, wrap the condition in parentheses.

 render() { return ( <div class="$(active == 'something') ? active : inactive"> ... </div> ) } 

It is possible to specify only one "$" sign at the beginning of the condition,
for the remaining condition variables, the sign can be omitted

 render() { return ( <div class="$index==count-1 ? active : inactive"> ... </div> // or <div class="$( index == count - 1 ) ? active : inactive"> ... </div> ) } 

And finally the cherry on the cake

 render() { return ( <div class="$?active $?.active $?..active"> ... </div> ) } 

will be

 render() { return ( <div className={classy(active ? "active" : "", active ? "local-prefix-active" : "", active ? "global-prefix-active" : "")}> ... </div> ) } 

And with denial

 render() { return ( <div class="!$?active !$?.active !$?..active"> ... </div> ) } 

will be

 render() { return ( <div className={classy(!active ? "active" : "", !active ? "local-prefix-active" : "", !active ? "global-prefix-active" : "")}> ... </div> ) } 

Points work on the same principles as always, depending on the mode.

CSS syntax

For non-autoprefix mode

One point for real class names without prefixes.
Two dots for names with local prefix.
Three dots for names with global prefix.
"Self" is a keyword denoting a local or global prefix, if any, otherwise the class name will simply be self

 ..self { ..title { } ..content { } ...active { } .item { } } 

For auto-prefix mode

One point for class names with local prefix.
Two dots for names with global prefix.
Three points for real class names without prefixes.

 .self { .title { } .content { } ..active { } ...item { } } 

If the local prefix is ​​not defined, the global one will be used.

And now some CSS sugar

Sugar syntax example:

 .container { var .abs.w100.h200.bc-000.c-fff.fs15; } 

will be converted to:

 .container { position: absolute; width: 100px; height: 200px; background-color: #000; color: #fff; font-size: 15px; } 

You can also with spaces:

 .container { var .fix .l .r .t .b .z999 .o3; } 

will become

 .container { position: fixed; left: 0; right: 0; top: 0; bottom: 0; z-index: 999; opacity: 0.3; } 

The expression must begin with the key word "var" and end with a semicolon or a line break.

Full list of available abbreviations

Abbreviations for background images

It's all the more difficult, and first you need to determine the source (s) of files.
, , .
:

 .with.image.source '../../assets/images/'; .with.image.source './bg-images'; .with.image.source './images/gifs'; .with.image.source '../svgs'; 

:

 .item { var .png-arrow.jpg-bg.jpeg-line.png2-some-image; var .gif3-preloader.svg4-icon; } 

:

1. Expansion
2. ( , )
3. File name

:

 .item { background-image: url(../../assets/images/arrow.png); background-image: url(../../assets/images/bg.jpg); background-image: url(../../assets/images/line.jpeg); background-image: url(./bg-images/some-image.png); background-image: url(./images/gifs/preloader.gif); background-image: url(../svgs/icon.svg); } 

, .

:

In custody

, , , , - , . , , , . , , , . , !