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.

📖 Table of Contents

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

🗝️ Features

• 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

🚀 Getting Started

Installation

Using npm

npm install -D css-seasoning

Visit the npm page for more information.

Usage 🎉

Basic Usage

# 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.

Example: Using Minimal Mode

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;
}.c {
  background-color:var(--a);
}.c.d {
  background-color:var(--b);
}

Example: Using Debug Mode

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);
}

Example: Saving Conversion Tables

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"
  }
}

Example: Using Saved Conversion Tables

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

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

📖 Config Options Reference

All options in one place 📦

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
  conversionTables: {    // Optional reusable mappings
    selector: { "\\.button": "\\.preserved-class" },
    ident: { "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

💻 CLI

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

css-seasoning [OPTIONS] <input-file>

Options

-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
-s, --suffix <suffix>        Suffix to add at the end in debug mode
--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

Examples

# 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

⭐ TODO

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

🐛 Known Issues

• Waiting for you

🤝 Contributing

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.

📝 License

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

⭐ Star History

☕ Donation

Love it? Consider a donation to support my work.

<- click me~