Rename CSS Selectors (RCS)

Note: Please make sure your files are not minified/uglified. Do that after processing it with rename-css-selectors

This module renames all CSS selectors in the given files. It will collect all selectors from the given CSS files. Do not worry about your selectors, rcs will do it for you.

You can also use a config file with the combination of generateMapping and loadMapping, if you already had other projects with the same classes. So all your projects have the same minified selector names - always.

Contents

• Installation
• Usage
• Before/After
• RCS Config
• Methods
• LICENSE

Installation

Install with npm or yarn

npm install --save rename-css-selectors

or

yarn add rename-css-selectors

Usage

Async:

const rcs = require('rename-css-selectors')

// if you have some generated mappings - load them!
// you can also specify the string although it does not exist yet.
rcs.loadMapping('./renaming_map.json')

// first you have to process the css files
// to get a list of variables you want to minify
// options is optional
rcs.processCss('**/*.css', options, err => {
    // all css files are now saved, renamed and stored in the selectorLibrary

    // now it is time to process all other files
    rcs.process([ '**/*.js', '**/*.html' ], options, err => {
        // that's it

        // maybe you want to add the new selectors to your previous generated mappings
        // do not worry, your old settings are still here, in case you used `loadMapping`
        rcs.generateMapping('./', { overwrite: true }, err => {
            // the mapping file is now saved
        })
    })
})

Sync:

const rcs = require('rename-css-selectors')

rcs.loadMapping('./renaming_map.json')

try {
    rcs.processCssSync('**/*.css', options)
    rcs.processSync([ '**/*.js', '**/*.html' ], options)
    rcs.generateMappingSync('./', { overwrite: true })
} catch (error) {
    console.log(error)
}

Before/After

• CSS
• HTML
• JS
• Others

CSS

Before

.selector {
    ...
}

.another-selector {
    ...
}

After

.e {
    ...
}

.t {
    ...
}

HTML

The CSS from before is used

Before

...
<div class="selector column">...</div>
<span class="another-selector"></span>
...

After

...
<div class="e column">...</div>
<span class="t"></span>
...

JS

Before

...
$('.selector').addClass('column')
document.getElementsByClassName('another-selector')

After

.column is never triggered, because it never appeared in CSS

...
$('.e').addClass('column')
document.getElementsByClassName('t')

Others

Every file can be triggered...

RCS config

Just create a .rcsrc in your project root or you can add everything in your package.json with the value rcs

• Example
• Exclude
• Include from other projects

Example

The .rcsrc or the a own config file:

{
    "exclude": [
        "js",
        "flexbox"
    ]
}

The package.json:

{
    "name": "Your application name",
    "rcs": {
        "exclude": [
            "js",
            "flexbox"
        ]
    }
}

Exclude Classes and IDs

exclude

What if you are using something such as Modernizr and you do not want to minify some selectors?

Let's exclude 4 classes and id's: js, flexbox, canvas and svg

{
    "exclude": [
        "js",
        "flexbox",
        "canvas",
        "svg"
    ]
}

Methods

• processCss
• processJs
• process
• generateMapping
• loadMapping
• includeConfig

processCss

processCss(src[, options], callback)

Store all matched selectors into the library and saves the new generated file with all renamed selectors.

Sync: processCssSync

Options:

• overwrite (boolean): ensures that it does not overwrite the same file accidently. Default is false
• cwd (string): the working directory in which to seach. Default is process.cwd()
• newPath (string): in which folder the new files should go. Default is rcs
• flatten (boolean): flatten the hierarchie - no subfolders. Default is false
• prefix (string): prefix all triggered selectors. Default is undefined
• suffix (string): suffix all triggered selectors. Default is undefined
• preventRandomName (boolean): does not rename the selectors (good for prefixing/suffixing). Default is false
• ignoreAttributeSelector (boolean): set to true it will not care about CSS attribute selectors e.g.: [class*="selector"]. Default is false

Example:

const rcs = require('rename-css-selectors')

rcs.processCss('**/*.css', options, err => {
    if (err) return console.error(err)

    console.log('Successfully wrote new files and stored values')
})

processJs

process(src[, options], callback)

Important! processCss should run first, otherwise there are no minified selectors

Sync: processJsSync

Options:

• overwrite (boolean): ensures that it does not overwrite the same file accidently. Default is false
• cwd (string): the working directory in which to seach. Default is process.cwd()
• newPath (string): in which folder the new files should go. Default is rcs
• flatten (boolean): flatten the hierarchie - no subfolders. Default is false
• jsx (boolean): if the file is a react jsx file. Default is false

Example:

const rcs = require('rename-css-selectors')

rcs.processJs('**/*.js', options, err => {
    if (err) return console.error(err)

    console.log('Successfully wrote new javascript files')
})

process

process(src[, options], callback)

Important! processCss should run first, otherwise there are no minified selectors

Note: If you replace JavaScript files, you might overwrite words within a string which is not supposed to be a css selector

Matches all strings " " or ' ' and replaces all matching words which are the same as the stored css values.

Sync: processSync

Options:

• overwrite (boolean): ensures that it does not overwrite the same file accidently. Default is false
• cwd (string): the working directory in which to seach. Default is process.cwd()
• newPath (string): in which folder the new files should go. Default is rcs
• flatten (boolean): flatten the hierarchie - no subfolders. Default is false

Example:

const rcs = require('rename-css-selectors')

// the same for html or other files
rcs.process('**/*.js', options, err => {
    if (err) return console.error(err)

    console.log('Successfully wrote new files')
})

generateMapping

generateMapping(pathLocation[, options], callback)

Note: if you are using the options either cssMapping or cssMappingMin must be set to true. Both to true at the same time are not valid.

Generates mapping files: all minified, all original selectors or both. They are stored as object in a variable. The file is named as renaming_map.json or renaming_map_min.json.

Options:

• cssMapping (string | boolean): writes renaming_map.json. If it is a string, the string is the new file name. Default is true
• cssMappingMin (string | boolean): writes renaming_map_min.json. If it is a string, the string is the new file name. Default is false
• extended (boolean): instead of a string it writes an object with meta information. Default is false
• json (boolean): writes a json instead of a js. Default is true`
• overwrite (boolean): if it should overwrite the existing mapping. Default is false

const rcs = require('rename-css-selectors')

// the same for html or other files
rcs.generateMapping('./mappings', options, err => {
    if (err) return console.error(err)

    console.log('Successfully wrote mapping files')
}

Output in renaming_map_min.js:

var CSS_NAME_MAPPING_MIN = {
    '.e': 'any-class',
    '.t': 'another-class'
};

loadMapping

loadMapping(pathToMapping[, options])

Note: If you include a file, it MUST be the json generated mapping.

Loads the previous generated mapping. This ensures that all your projects have all the time the same renamed selectors.

Options:

• origValues (boolean): Wether the cssMappingMin (false) or cssMapping (true) should get loaded. Default is true

const rcs = require('rename-css-selectors')

// loadMapping is synchronous
// the first parameter can be either a string to the file
// or the json object directly
rcs.loadMapping('./renaming_map.json', options)

rcs.process('**/*.html', err => {
    ...
})

includeConfig

includeConfig([pathLocation])

All available configs here

RCS will lookup first for a .rcsrc of the current directory. If there is no such file, it will lookup for a package.json with a "rcsrc": {} in it. You can also write any path in the parameters and write your own config file. This function is synchronous.

const rcs = require('rename-css-selectors')

rcs.includeConfig()

LICENSE

MIT © Jan Peer Stöcklmair