⚡ valcss

valcss is a tiny, flexible CLI utility to generate atomic and utility-first CSS classes from usage in your HTML and custom plugins. It allows you to configure class patterns, outputs, breakpoints, and even inject CSS directly into your HTML or as a separate file.

Table of Contents

• Features
• Installation
• Getting Started
• Configuration
• Usage
• Plugin System
• Injection Modes
• Live Example
• FAQ
• License

Features

• ⚡ Instantly extracts and generates a CSS file from your HTML.
• ⏳ Supports watch mode for live editing.
• 🧩 Extendable through custom plugins.
• 🔗 CSS injection: inline in HTML or as a .
• 📦 Zero-dependency CLI.
• 🌈 Supports breakpoints (responsive utilities).
• 📝 Customizable with a simple JS config file.

Installation

npm install -g valcss

Getting Started

1. Scaffold a config file

valcss init

This creates a valcss.config.js file in your project:

// valcss.config.js
module.exports = {
  files: ["index.html", "src/**/*.html"],
  output: "valcss-main.css",
  inject: {
    mode: "link", // or "inline"
    targets: ["index.html"],
  },
  breakpoints: {
    lg: 990,
  },
  plugins: [
    ({ addUtilities }) => {
      addUtilities(
        {
          "flex-center": {
            display: "flex",
            "justify-content": "center",
            "align-items": "center",
          },
        },
        "*"
      );
    },
  ],
};

2. Add utility CSS classes in your HTML:

Example (index.html):

<link rel="stylesheet" href="valcss-main.css" />
<div class="p-[25px] flex-center hover:flex-center lg:flex-center ...">
  <p class="text-[#000] bg-[#00ff00] border-[1px_solid_#000] ...">Hello</p>
</div>

3. Build your CSS

valcss

• This scans your HTML, generates only the CSS classes you actually use, and writes them to valcss-main.css.
• The CSS is injected (as a link or inline) into your specified HTML targets.

Configuration

The config file lets you control:

• files: Files/globs to scan for class usage.
• output: The CSS file output.
• inject: How and where to inject the styles.
• breakpoints: Custom responsive breakpoints.
• plugins: Extendable utility generators.

See valcss.config.js for an example.

Usage

| Command | Description | | ------------------------ | ------------------------------------ | | valcss | Run CSS extraction/generation | | valcss --output <file> | Override the default output file | | valcss --watch | Enable file watching/live rebuilds | | valcss init | Scaffold a config file | | valcss --dry-run | Print generated CSS to terminal only | | valcss --help | Show help message |

Example:

valcss --watch --output custom.css

Plugin System

Define your own utilities with the plugins array in your config:

plugins: [
  ({ addUtilities }) => {
    addUtilities(
      {
        "flex-center": {
          display: "flex",
          "justify-content": "center",
          "align-items": "center",
        },
      },
      "*"
    );
  },
];

This adds the flex-center class to your utility set:

.flex-center {
  display: flex;
  justify-content: center;
  align-items: center;
}

Injection Modes

• "link": Injects your built CSS using <link rel="stylesheet" ...>.
• "inline": Injects the CSS directly inside <style> tags.
• Targets: Specify which HTML files receive the injection.

Edit these options under inject in your config file.

Live Example

• index.html with the generated classes applied.
• valcss-main.css is the result.

FAQ

How does valcss work?

• Scans your specified files for ALL CSS classes used.
• Resolves and compiles only the classes you use into a single CSS file.
• Optionally injects that file into your HTML via link or inline style.

How to add my own utility classes?

Use the plugin system in the config. See Plugin System.

Does valcss support responsiveness?

Yes! Example:
.md:utility or .lg:flex-center generates the correct breakpoint selectors.

License

MIT © 2025 @hardik-143

Ready to make your CSS minimal, maintainable, and fast? Try valcss and get instant atomic CSS using only what you use!