CSS-SEASONING

Project starts on 02-03-2025

Visit the GitHub Page for better reading experience and latest docs. 😎

A tool deeply inspired by google/postcss-rename but not dependent on PostCSS.

CSS-SEASONING is designed seasoning your CSS files by transforming selectors and custom properties into hash values (multiple modes available). It can be used to obfuscate CSS files, reduce file size, or simply make your CSS more readable.

Let's say goodbye to long and complex CSS selectors and custom properties, and hello to a cleaner, more efficient CSS!

[!NOTE]
This package does not provide tool to change your HTML or JS files. It only transforms CSS files. You need to use other tools to change your HTML or JS files to match the transformed CSS.

Give me a ⭐ if you like it.

• 🗝️ Features
• 🚀 Getting Started
• 📖 Config Options Reference
• 💻 CLI
• ⭐ TODO
• 🐛 Known Issues
• 🤝 Contributing
• 📝 License
• ⭐ Star History
• ☕ Donation

• Hash-based transformation: Convert CSS selectors and custom properties to hash values
• Minimal mode: Convert to shortest possible alphabetical names (a, b, c, ...)
• Debug mode: Add prefixes and suffixes to help debugging transformed CSS
• Custom seed support: Use a specific seed to generate consistent hashes
• Conversion tables: Save and reuse conversion mappings between runs
• Easy-to-use CLI: Simple command-line interface for quick transformations
• CSS optimisation: Improve the efficiency of your CSS code

npm install -D css-seasoning

Visit the npm page for more information.

# Using the CLI (if installed via npm)
css-seasoning styles.css

# Using Deno directly
deno run cli styles.css

[!NOTE]
This will transform your CSS file using the default hash mode and display the output in the console if no output file is specified.

css-seasoning styles.css -m minimal

Input (styles.css):

:root {
  --main-color: blue;
  --accent-color: red;
}

.button {
  background-color: var(--main-color);
}

.button.primary {
  background-color: var(--accent-color);
}

Prettied Output:

:root {
  --a:blue; --b:red;
}
.a {
  background-color:var(--a);
}
.b.c {
  background-color:var(--b);
}

css-seasoning styles.css -m debug -d "__DEBUG__" -p "prefix-" -s "-suffix"

Prettied Output:

:root {
   --__DEBUG__prefix-main-color-suffix:blue;
   --__DEBUG__prefix-accent-color-suffix:red;
}

.__DEBUG__prefix-\.button-suffix {
   background-color: var(--__DEBUG__prefix-main-color-suffix);
}
.__DEBUG__prefix-\.button-suffix.__DEBUG__prefix-\.primary-suffix {
   background-color: var(--__DEBUG__prefix-accent-color-suffix);
}

css-seasoning styles.css --save-tables tables.json

This generates a conversion table file (tables.json) that maps original selectors and custom properties to their transformed versions:

{
  "selector": {
    "\\.button": "\\.rde48G",
    "\\.primary": "\\.K9aB2z"
  },
  "ident": {
    "main-color": "a8XPz8",
    "accent-color": "mL3o9P"
  }
}

css-seasoning new-styles.css --conversion-tables tables.json

This ensures that the same mappings are used across multiple CSS files or builds.

You can selectively ignore certain selectors or custom properties that you don't want to transform using regex patterns. There are two ways to specify patterns:

1. Separately for selectors and identifiers (CLI):

# Ignore Bootstrap utility classes starting with 'btn-'
css-seasoning styles.css --ignore-selector "^btn-"

# Ignore both bootstrap buttons and theme color custom properties
css-seasoning styles.css --ignore-selector "^btn-" --ignore-ident "^theme-"

2. Using the same patterns for both (programmatic API):

When using the API directly, you can also provide a single array of patterns that will apply to both selectors and identifiers:

transform({
  css: inputCss,
  // These patterns will apply to both selectors and custom properties
  ignorePatterns: ["^btn-", "^theme-", /bootstrap-/]
});

Input:

:root {
  --main-color: blue;
  --theme-primary: red;
}

.button {
  color: var(--main-color);
}

.btn-primary {
  color: var(--theme-primary);
}

Output with ignore patterns:

:root {
  --a:blue; --theme-primary:red;
}
.a {
  color:var(--a);
}
.btn-primary {
  color:var(--theme-primary);
}

This allows you to keep certain naming conventions intact (like framework-specific class names or theme variables) while still transforming the rest of your CSS.

# Using CLI with different prefixes for selectors and identifiers
css-seasoning styles.css -m debug --prefix-selector "sel-" --prefix-ident "var-"

# Using CLI with different suffixes for selectors and identifiers
css-seasoning styles.css -m debug --suffix-selector "-s" --suffix-ident "-v"

# Using both different prefixes and suffixes
css-seasoning styles.css -m debug --prefix-selector "sel-" --prefix-ident "var-" --suffix-selector "-s" --suffix-ident "-v"

When using the API directly, you can provide separate values as an object:

transform({
  css: inputCss,
  mode: "debug",
  // Different prefixes for selectors and identifiers
  prefix: {
    selectors: "sel-",
    idents: "var-"
  },
  // Different suffixes for selectors and identifiers
  suffix: {
    selectors: "-s",
    idents: "-v"
  }
});

Input:

:root {
  --main-color: blue;
  --accent-color: red;
}

.button {
  background-color: var(--main-color);
}

Output with different prefixes and suffixes:

:root {
  --_var-main-color-v: blue;
  --_var-accent-color-v: red;
}

._sel-\.button-s {
  background-color: var(--_var-main-color-v);
}

This allows for more flexibility when debugging by making it easier to visually distinguish between transformed selectors and custom properties.

If you're using css-seasoning as a library:

import { transform } from "css-seasoning";

const result = transform({
  css: inputCss,
  mode: "hash",          // "hash", "minimal", or "debug"
  debugSymbol: "_",      // Symbol for debug mode
  prefix: "prefix-",     // Prefix in debug mode (after symbol)
  suffix: "-suffix",     // Suffix in debug mode
  seed: 123,             // Custom seed for hash generation
  
  // Object format for ignorePatterns (separate patterns for selectors and identifiers)
  ignorePatterns: {      
    selectors: ["^btn-", /header$/],
    idents: ["^theme-"]
  },
  
  // Alternative: Array format (applies to both selectors and identifiers)
  // ignorePatterns: ["^btn-", "^theme-", /header$/],
  
  conversionTables: {    // Optional reusable mappings
    selectors: { "\\.button": "\\.preserved-class" },
    idents: { "color": "preserved-var" }
  },
  lightningcssOptions: { // Lightning CSS options
    minify: true,
    sourceMap: false
  }
});

console.log(result.css);                // The transformed CSS
console.log(result.conversionTables);   // The generated/used conversion tables

The CLI provides a convenient way to transform CSS files from the command line.

css-seasoning [OPTIONS] <input-file>

-h, --help                   Show help message
-o, --output <file>          Output file (default: input-file with '-refined' suffix)
-m, --mode <mode>            Transformation mode: hash, minimal, or debug (default: hash)
-d, --debug-symbol <symbol>  Symbol to use for debug mode (default: _)
-p, --prefix <prefix>        Prefix to add after debug symbol in debug mode
    --prefix-selector <prefix> Prefix to use for selectors (overrides --prefix)
    --prefix-ident <prefix>  Prefix to use for identifiers (overrides --prefix)
-s, --suffix <suffix>        Suffix to add at the end in debug mode
    --suffix-selector <suffix> Suffix to use for selectors (overrides --suffix)
    --suffix-ident <suffix>  Suffix to use for identifiers (overrides --suffix)
--seed <number>              Seed for hash generation in hash mode
--minify                     Minify the output CSS (default: true)
--source-map                 Generate source map
--conversion-tables <file>   JSON file with existing conversion tables to preserve mappings
--save-tables <file>         Save the conversion tables to a JSON file
--ignore <pattern>           Regex pattern for selectors and custom properties to ignore (can be used multiple times)
--ignore-selector <pattern>  Regex pattern for selectors to ignore (can be used multiple times, overridden by --ignore)
--ignore-ident <pattern>     Regex pattern for custom properties to ignore (can be used multiple times, overridden by --ignore)

# Basic usage with default options
css-seasoning styles.css

# Use minimal mode and specify output file
css-seasoning -o output.css -m minimal styles.css

# Debug mode with custom debug symbol
css-seasoning --mode debug --debug-symbol "_d_" styles.css

# Save and reuse conversion tables
css-seasoning styles.css --save-tables tables.json
css-seasoning other.css --conversion-tables tables.json

• [ ] Combine Selectors
• [ ] Allow selector patterns, eg. convert .class #id to .newClass
• [ ] Add CLI tests
• [ ] Publish to JSR

• Waiting for you

Contributions are welcome! If you find a bug or have a feature request, please open an issue. If you want to contribute code, please fork the repository and run deno run fmt & deno run test before submitting a pull request.

We are following Conventional Commits for commit messages.

This project is licensed under the MIT License - see the LICENSE file for details

Love it? Consider a donation to support my work.

<- click me~