Intro➤Motivation➤Features➤Installation➤Usage➤Configuration➤Extra➤Releases➤Contributing

• 📅05-05-2023 📌Beta Version 1.5.0
• 💻NajibRachid 🟣ANMOON 🏢 XHUB

PostCSS plugin that helps you protect your CSS code by obfuscating class names and ids. with customizable configuration.

This plugin provides obfuscation capabilities to your CSS files by replacing class and id selectors with prefixed, simplified or randomly generated strings. This can help to protect your CSS code from reverse engineering and unauthorized copying, while also reducing the file size of your CSS files. plugin offers advanced customizable configuration.

Turn this into this:

• Protecting Intellectual Property, Licensing and Distribution: make it hard for others from stealing your design or using it without your permission.
• Protect against Web scraping, data mining or any malicious activities like stealing data or content: make it hard extracting data from websites automatically using software tools, which use class names & ids.
• Minfiy Your code even more: obsfucation/uglify can slightly reduce file size and improve its performance.

• No 3rd parties, Dependencies. Just vanilla Nodejs code.
• Quicker then you think.
• Postcss plugin, hence its intended to work with any build tool or task runner.
• Advanced Customizable configuration (Control is yours).
• Supports all files: .html, .js, .php, .vue, ... you name it.
• Supports a wide range of CSS frameworks (Tailwidcss, bootstrap, Bulma).

# npm
npm install postcss-obfuscator --save-dev

# yarn
yarn add postcss-obfuscator --dev

First, you need to add postcss-obfuscator to your PostCSS configuration. For example, if you're using postcss-cli, you can add it to your postcss.config.js file:

//postcss.config.js 
module.exports = {
  plugins: [
    require('postcss-obfuscator')({
      /* options */
    })
  ]
}

You can also make you own custome separate script like so:

First install postcss:

#npm
npm i postcss --save-dev

#yarn
yarn add postcss --dev

Then require postcss and postcss-obfuscator plugin in your script:

//postcss-obfuscate.js 
const postcss = require("postcss");
const obfuscator = require("postcss-obfuscator");

postcss([obfuscator({
    /* options */
})])
  .process(css)
  .then((result) => {
    console.log("Task Completed!", result);
  })
  .catch((error) => {
    console.error(error);
  });

The plugin has several options that you can configure to customize its behavior. Here are the available options:

• enable: Enable plugin, default is true.
• length: Random name length for both ids and classes, default is 5.
• classMethod: Obfuscation method for classes, options are: 'random', 'simple', 'none'. 'simple' will remove pronounced vowels and digits, 'none' will keep original name in case you want to just use prefixes or suffixes. deafult is 'random'.
• classPrefix: Prefix for class names, default is nothig.
• classSuffix: Suffix for class names, default is nothig.
• classIgnore: Array of classes to ignore from obfuscation. deafult is none.
• ids: Enable id Obfuscation, default is false.
• idMethod: Obfuscation method for ids, options are: 'random', 'simple', 'none', _deafult is 'random'.
• idPrefix: Prefix for id names, default is nothig.
• idSuffix: Suffix for id names, default is nothig.
• idIgnore: Array of ids to ignore from obfuscation. deafult is none.
• indicator: Indicator used to replace names. default is none.
• jsonsPath: Path and Name where to save obfuscation data default is: css-obfuscator.
• srcPath: Path for your source files, default is: src.
• desPath: Destination Path for obfuscated html/js/.. files, default is: out.
• extensions: Extesnions Array of files you want osbfucated ['.html', '.php', '.js', '.svelte'], default is '.html'.
• htmlExcludes: Files and paths to exclude from html obfuscation replacement, default is none.
• cssExcludes: Files and paths to exclude from css obfuscation, default is none.
• fresh: Create New obfuscation data List or use already existed one (to keep Production Cache or prevent data scrapping). deafult is false.
• multi: Generate obsfucated data file for each css file, default is false.
• differMulti: Generate differnt Raandom names for each file, default is false.
• formatJson: Format obfuscation data JSON file, default is false.
• showConfig: Show config on terminal when runinng, default is false.
• keepData: Keep or delete Data after osbfucation is finished? default is true.
• callBack: Callback function to call after obfuscation is done. default is an empty function

Here's the default donfiguration:

  const defaultOptions = {
    enable: true, // Enable plugin
    length: 5, // Random  name length.
    classMethod: 'random', // 'random', 'simple', 'none' obfuscation method for classes.
    classPrefix: "", // ClassName prefix.
    classSuffix: "", // ClassName suffix.
    classIgnore: [], // Class to ignore from obfuscation.
    ids: false, //  Obfuscate #IdNames.
    idMethod: 'random', // 'random', 'simple', 'none' obfuscation method for ids .
    idPrefix: "", // idName Prefix.
    idSuffix: "", // idName suffix.
    idIgnore: [], // Ids to ignore from obfuscation.
    indicator: null, // Indicator used to replace names.
    jsonsPath: "css-obfuscator", // Path and Name where to save obfuscation data.
    srcPath: "src", // Source of your files.
    desPath: "out", // Destination for obfuscated html/js/.. files.
    extensions: ['.html'], // Extesnion of files you want osbfucated ['.html', '.php', '.js', '.svelte'].
    htmlExcludes: [], // Files and paths to exclude from html obfuscation replacement.
    cssExcludes: [], // Files and paths to exclude from css obfuscation.
    fresh: false, // Create New obfuscation data List or use AlreadyExistedOne (to keep Production Cache or prevent data scrapping).
    multi: false, // Generate obsfucated data file for each css file.
    differMulti: false, // Generate differnt Raandom names for each file.
    formatJson: false, // Format obfuscation data JSON file.
    showConfig: false, // Show config on terminal when runinng.
    keepData: true,  // Keep or delete Data after osbfucation is finished?
    callBack: function () {} // Callback function to call after obfuscation is done.
  };

Then npm scripts can be something like this:

    "postcss": "postcss src/**/*.css  --dir build",
    "postcss:watch": "postcss src/**/*.css --dir build --watch"
    "obfuscate": "node postcss-obfuscate",  // for custome script.

1. Loop over all css files.
2. Uses Buildting function(regex) to find classes & ids.
3. Saves Ids & classes in a Json file key represting orginal Names. then genarates random names as values.
4. Creates new folder from source folder.
5. Loops throw files and replaces those keys with values from JSON File.

• Only CSS Supported so call the extension After your code was converted to css (Example: scss to css). Its generally better to call at as the last plugin.
• One of best practices is to avoid naming your ids & classes reserved words like html elemnts name or attributes. (same for JS & CSS).
• It uses builting function to find divs & css classes. so it may not work perfectly with advanced CSS selectors.
• I advice to keepData as deafult true and to use a diffrent build directory: using same directory will replace your files and you may loose orginal classes and ids names. you will get a warning for that.
• Postcss doesnt support nested dirctories by default. this is If u intend to work with the plugin's multi option.

To use based on environment mode variable you may do so like this:

const isDevMode = process.env.NODE_ENV === 'development'; // production

enable: isDevMode, // Force Run on Dev Env or when srcPath equals desPath.

Its Better to keep your source files as they are for easy development. Consider specifing another folder for build, if you choose your build directory to be same as source directory you will be replaced and you will loose your orginal files.

As mentioned this plugin uses Regex to replace all apperances of classes & ids on files with extension you specify (be it html, cs, js, ...). Generally if your classes names are unique and avoids reserved keywords, then you got nothing to worry about, otherwise, we got you covered just use the indicator option

   indicator: "@",

Now whenever you mention your ids or classes use like this: so it will only replace ones with the indicator around them.

<script>
 let anotherClass =  "@anotherClass@"
</script>
<div class="@myClass@">MyClass</div>

Postcss usually is runned automatically on dev and build: so its preferred to create a customer postcss script with the postcss-obfuscator plugin, a script to run only when you want to obfuscate and to make project ready for production.

But it can also be done like this:

1. the enable option: to enable it only in specific mode and to make sure tailwindcsss works fine in dev mode:

process.env.NODE_ENV = "development" //development //obfuscation //production
const isObfscMode = process.env.NODE_ENV === 'obfuscation'; 

//enable: isObfscMode,

2. the callBack option, a Callback function to call after obfuscation is done. that way once obfuscation is done you can config and prepare your project for production:

 callBack: function () {
	process.env.NODE_ENV = "production"; // to make sure postcss-obfuscator doesnt re-run.
 },

so basically you use callBack option to set the env mode back to production so that obsfucation will not run, and then config your app source folder to use out folder instead of src for production.

• In Beta Tests so far it working fine but we always working on improvements.
  • Tailwindcss.
  • Bootstrap.
  • Bulma.
  • And any other framwork you can think of.

  - Initial Version 1.0.0 : 18/02/2023
    - Project Setup.
    - Theory & prove of concept.
  - Initial Version 1.0.3 : 19/02/2023
    - Essential default confugration options (length, jsonPath, placeholder).
    - Settled on a no dependcies solution. built own parser.
    - Developing class finder function.
  - Initial Version 1.0.7 : 20/02/2023
    - Set confugration options.
    - Introduce Id obsfucation.
    - Add prefixers option.
    - Add suffixes option.
  - Initial Version 1.0.9 : 21/02/2023
    - Add srcPath option.
    - Add desPath option.
  - Initial Version 1.1.2 : 21/02/2023
    - Improving class finder method regex.
    - Add showConfig Option.
    - Add formatJson Option.
  - Alpha Version 1.1.5 : 22/02/2023
    - Introducing the Multi option.
    - Refactor & improve code performance.
    - Introduce CLI UI.
  - Alpha Version 1.1.8 : 23/02/2023
    - Introducing the fresh option.
    - Introducing the keepSame option.
    - Adding Logger & logs.
  - Alpha Version 1.2.2 : 24/02/2023
    - Introducing  the callback option.
    - Adding proccess stats/data log.
    - Use a copy method solution.
    - Improve Replace Regex (exclude HTML attributes).
  - Alpha Version 1.2.6 : 24/02/2023
    - Adding Indicator option.
    - deprecate keepSame option.
    - Introduce the differMulti option.
    - Make keepData true as default.
  - Alpha Version 1.3.2 : 25/02/2023
    - Add extensions options.
    - fix differMulti option Bug(class repeation).
    - Deprecate placeholder option.
    - Introducing ExcludeCss option.
    - Introducing ExcludeHTML option.
    - Fix Edge case (Css file count).
  - Alpha Version 1.3.4 : 26/02/2023
    - Fix Files Count (count diffrent extensions).
    - Improve simplify function (add random letter if <1).
  - Alpha Version 1.3.8 : 27/02/2023
    - Add idIgnore/classIgnore Option,
    - Add classMethod option (random/simplify/none).
    - Fix issue (delete data wrong path).
    - Fix bug (Find multiple Ids). 
  - Beta Version 1.4.0 : 28/02/2023
    - Improve Exclude Css Option allow Paths.
    - Improve Exclude HTML Option allow Paths.
  - Beta Version 1.4.1 : 01/03/2023
    - Fix Error copying directory: Invalid regular expression: /(?<!</?)\b(sm\:group-hover\)\b(?!=)/: Unterminated
group 
  - Beta Version 1.4.2 : 02/03/2023
     - Fix default replacement set default extensions to ['.html'].
  - Beta Version 1.4.5 : 03/03/2023
     - Fix tailwindcss replacement in html (remove backslash escape character before replace).
     - Fix tailwindcss css replacement. (remove dplicated escape charecter before dot "0.5").
     - Fix HTML Exact Match: e.g. (xl:bottom-0 and xl:bottom-0.5).
  - Beta Version 1.5.0 : 05/05/2023
    - Better Documentation(use cases).
    - Better Documentation(build & production).
    - Fine tuning for tailwindcss (#3 Using tailwindcss arbitrary values).
    - Typo folder name css-obfuscator.
  - [Agenda] Beta Version 1.x.x : xx/xx/2023
    - Draft for framework option.
    - Set Indicators Start & End.
    - Fix Files Path (make relative).
    - Add Force option (case: dev env or same Path).
    - Ask before preceding (If dev env or srcPath is desPath).
    - Improve custome script(postcss-obfuscator).
    - Internal Css feature.
    - Refactor tests.

Contributions are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository.

Tests included:

   npm test

This project is licensed under the MIT License. See the LICENSE file for more information. Feel free to use it in your own projects, or contribute to its development on GitHub.

Check Also: PostCSS-prepend | PostCSS-mobile-first

keywords: postcss, plugin, obfuscation, css, css classes, class renamer, postcss-rename-selectors, class prefixer, Postcss obfuscator, PostCSS obfuscation plugin, CSS obfuscation, Class name scrambling, CSS security, Obfuscate CSS code, Protect CSS code, Prevent CSS reverse-engineering, tailwindcss, tailwindcss classes list, tailwindcss classes array json, bootstrap, bootstrap classes array json, Scramble HTML classes, CSS anti-theft protection, code privacy, CSS code obfuscator, CSS class name encryption, anti web scraping, Anti-scraping tools, Anti-scraping technology, Web scraping prevention, Web crawling protection.