postcss-custom-properties-transformer

PostCSS plugin to transform CSS custom properties

_{If you like this project, please star it & follow me to see what other cool projects I'm working on! ❤️}

🙋‍♂️ Why?

Transform CSS custom properties to...

• 🔥 Scope to package Namespace them to your library to prevent collision with other custom properties
• 👌 Scope to file Scope to a file to prevent collision with other files
• 🐥 Minify Shorten long custom properties via hashing
• 🤬 Obfuscate Mangle custom-property names to deter reverse-engineering

🚀 Install

npm i -D postcss postcss-custom-properties-transformer

🚦 Quick Setup

Add postcss-custom-properties-transformer to your PostCSS configuration (eg. postcss.config.js) and pass in a transformer function.

⚠️ This plugin doesn't validate custom properties as browsers seem to validate them differently. As per the spec, custom properties is "defined as any valid identifier that starts with two dashes". An "identifier" can contain "only the characters [a-zA-Z0-9] and ISO 10646 characters U+0080 and higher, plus the hyphen (-) and the underscore (_); they cannot start with a digit, two hyphens, or a hyphen followed by a digit".

module.exports = {
     plugins: [

+        // Insert above plugins that read custom properties
+        require('postcss-custom-properties-transformer')({
+            transformer({ property }) {
+                // Prefixing all custom properties with 'APP-'
+                return 'APP-' + property;
+            }
+        }),

         require('postcss-preset-env')()
     ]
};

👨🏻‍🏫 Examples

Namespace with package meta

If you have a CSS library, you can scope your custom properties to every release so that multiple versions of the library used in the same app doesn't yield any collisions.

const pkg = require('./package.json')
require('postcss-custom-properties-transformer')({
    transformer({ property }) {
        return `${pkg.name}-${pkg.version}-${property}`;
    }
})

Hash custom properties

If you want to hash your custom properties to shorten/obfuscate them, pass in a hashing algorithm of your choice.

This demo uses a 6-character truncated MD5 hash; MD5 and the SHA-family has statistically good uniform distribution and can be truncated.

However, note that the shorter the hash, the higher the collision rate. There will be a warning if a collision is detected.

const crypto = require('crypto');
const md5 = string => crypto.createHash('md5').update(string).digest('hex');

require('postcss-custom-properties-transformer')({
    transformer({ property }) {
        return md5(property).slice(0, 6);
    }
})

Advanced transformations

If you want to do something more complex—such as discriminate between global and local custom properties (eg. theme variables).

require('postcss-custom-properties-transformer')({
    transformer({ property }) {
        if (property.startsWith('theme-')) {
            return property;
        }
        return hash(property);
    }
})

⚙️ Options

• transformer(data) <Function>
  • data <Object>
    • property <String> - The custom property name that's being transformed. The -- prefix is omitted
    • filepath <String> - The path to the file where the custom property is being transformed
    • css <String> - The entire CSS code of the file