Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/privatenumber/postcss-custom-properties-transformer
PostCSS plugin to apply transformations to CSS custom properties (eg. mangling)
https://github.com/privatenumber/postcss-custom-properties-transformer
custom hash mangle minify plugin postcss properties transform
Last synced: 27 days ago
JSON representation
PostCSS plugin to apply transformations to CSS custom properties (eg. mangling)
- Host: GitHub
- URL: https://github.com/privatenumber/postcss-custom-properties-transformer
- Owner: privatenumber
- License: mit
- Created: 2020-09-09T04:04:48.000Z (over 4 years ago)
- Default Branch: develop
- Last Pushed: 2021-02-24T06:39:49.000Z (almost 4 years ago)
- Last Synced: 2024-12-16T02:05:30.257Z (about 1 month ago)
- Topics: custom, hash, mangle, minify, plugin, postcss, properties, transform
- Language: JavaScript
- Homepage:
- Size: 111 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# postcss-custom-properties-transformer [](https://npm.im/postcss-custom-properties-transformer) [](https://npm.im/postcss-custom-properties-transformer) [](https://packagephobia.now.sh/result?p=postcss-custom-properties-transformer)
PostCSS plugin to transform [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
If you like this project, please star it & [follow me](https://github.com/privatenumber) 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
```sh
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"](https://www.w3.org/TR/css-variables-1/#defining-variables). 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"](https://www.w3.org/TR/CSS22/syndata.html#value-def-identifier).
```diff
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.
```js
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](https://stackoverflow.com/questions/8184941/uniform-distribution-of-truncated-md5) 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.
```js
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).
```js
require('postcss-custom-properties-transformer')({
transformer({ property }) {
if (property.startsWith('theme-')) {
return property;
}
return hash(property);
}
})
```
## ⚙️ Options
- `transformer(data)` ``
- `data` ``
- `property` `` - The custom property name that's being transformed. The `--` prefix is omitted
- `filepath` `` - The path to the file where the custom property is being transformed
- `css` `` - The entire CSS code of the file