🚀 Installation

npm i @unizap/unicss

⚡ Usage

CLI Usage

Generate your CSS file:

npx unicss

Or watch for changes and output to a custom file:

npx unicss -w -o src/output.css

| Flag | Description | Default | |---|---|---| | -o, --output | Where to write the generated CSS | style/unicss.css | | -w, --watch | Rebuild when source files or unicss.config.js change | off | | -c, --content | Glob patterns to scan (comma-separated, repeatable) | **/*.{js,jsx,ts,tsx,html,vue} | | --skip-base | Emit utilities only, without the base reset and theme variables | off |

npx unicss -c "src/**/*.tsx,pages/**/*.tsx" -o src/unicss.css -w

PostCSS Integration (Recommended)

UniCSS works seamlessly with PostCSS, similar to Tailwind CSS. This is the recommended approach for modern web applications.

Method 1: Using @unicss Directives

Create a CSS file with UniCSS directives:

/* app/globals.css or src/styles.css */
@unicss;

Configure PostCSS in your project:

// postcss.config.js
module.exports = {
  plugins: {
    '@unizap/unicss/postcss': {},
    autoprefixer: {}
  }
}

Import the CSS in your application:

// For Next.js, Vite, or other frameworks
import './globals.css'

The @unicss directive will be replaced with all generated utility classes. You can also split base and utilities:

@unicss base;      /* Base styles and resets */
@unicss utilities; /* Utility classes only */

The plugin registers every scanned source file as a PostCSS dependency, so Next.js, Vite and webpack rebuild the stylesheet when your markup changes.

Method 2: Use the Included PostCSS Config

UniCSS includes a ready-to-use PostCSS configuration with these plugins:

• @unizap/unicss/postcss — generate UniCSS utilities
• postcss-import — inline @import rules
• postcss-nested — unwrap nested rules
• autoprefixer — add vendor prefixes automatically

Import it directly:

// postcss.config.js
const unicssPostCSS = require('@unizap/unicss/postcss.config.js');
module.exports = unicssPostCSS;

Vite Integration

Add the plugin to your vite.config.js:

import { defineConfig } from 'vite';
import unicss from '@unizap/unicss/vite-plugin-unicss';

export default defineConfig({
  plugins: [
    unicss({
      output: 'src/unicss.css',  // Output path for generated CSS
      skipBase: false             // Optional: skip base styles
    })
  ]
});

Then import the generated CSS in your main entry file:

import './unicss.css';

The plugin scans .html, .js, .jsx, .ts, .tsx, .vue and .svelte files and regenerates CSS on change with HMR.

CDN / browser

Drop in the browser build and it styles the page for you — no build step:

<script src="https://unpkg.com/@unizap/unicss/dist/unicss.min.js"></script>

It auto-initializes on DOMContentLoaded and keeps watching the DOM with a MutationObserver, so markup rendered later by React, Vue or htmx is styled too. For manual control, window.UniCSS exposes:

UniCSS.generate(config, options);  // returns CSS for the current DOM
UniCSS.init(config, options);      // generates and injects a <style> tag
UniCSS.watch(config, options);     // init + re-run on DOM changes

options accepts skipBase and styleId; config takes the same shape as unicss.config.js.

🎨 Reusing styles with @apply

Pull utilities into your own class instead of repeating them in markup. Works through the PostCSS plugin, and in the CLI — which globs your project's .css files for @apply regardless of how content is configured:

.card {
  @apply shadow-md p-5 rounded-lg bg-color-white;
}

.btn-primary {
  @apply bg-color-blue-600 text-color-white px-4 py-2 rounded-md;
}

Multiple classes per directive are supported. Variant prefixes (hover:, md:, dark:) are stripped — only the base declarations are inlined, since a nested at-rule cannot be flattened into the surrounding rule. Classes the engine does not recognize are left behind as a /* @apply: unresolved classes: … */ comment rather than silently vanishing, so a typo is visible in the output.

🧩 Variants

Prefix any utility to make it conditional. Prefixes stack (dark:md:hover:bg-color-blue-700).

| Kind | Examples | |---|---| | States | hover:, focus:, active:, visited:, disabled:, checked:, focus-visible:, focus-within:, valid:, invalid:, required:, read-only:, target: | | Position | first:, last:, odd:, even:, nth-3:, nth-last-2:, nth-of-type-2: | | Pseudo-elements | before:, after:, placeholder:, marker:, selection:, file:, first-line:, first-letter:, backdrop: | | Breakpoints | sm:, md:, lg:, xl:, 2xl: | | Dark mode | dark: | | Container queries | @sm:, @max-lg:, @min-[20rem]: | | Relationships | group-hover:, group-hover/name:, peer-focus:, peer-checked/name: | | Media features | contrast-more:, contrast-less:, forced-colors:, inverted-colors: | | Attributes | ltr:, rtl:, aria-expanded:, aria-checked:, aria-[…], data-[…] | | Feature queries | supports-[display:grid]: |

Append ! for !important (!p-4, hover:!bg-color-red-500), and use square brackets for arbitrary values (w-[42px], bg-color-[#1da1f2], grid-columns-[repeat(3,minmax(0,1fr))]).

⚙️ Configuration

Create unicss.config.js in your project root. Keys under theme.extend are merged into the defaults; anything else replaces them.

module.exports = {
  theme: {
    extend: {
      breakpoints: { sm: "40rem", md: "48rem", lg: "64rem", xl: "80rem", "2xl": "96rem" },
      colors: {
        brand: { 500: "#5b21b6", 600: "#4c1d95" }
      }
    }
  }
};

🧠 Architecture

All rule, variant and theme logic lives in a single engine, src/core/engine.js. The CLI, PostCSS plugin, Vite plugin and CDN build are thin adapters over it, so every target resolves a class name identically — a fix in the engine reaches all of them at once.

src/core/engine.js   ← all rule, variant and theme resolution
├── src/generate.js  → dist/index.js        (Node: CLI, PostCSS, Vite)
└── src/cdn.js       → dist/unicss.min.js   (browser IIFE, window.UniCSS)

🧩 Features

• Utility-first CSS generator with a single shared engine across every target
• PostCSS plugin with @unicss directives and @apply support
• Full variant system: states, breakpoints, dark mode, container queries, group/peer, media features, ARIA/data attributes and supports-[…]
• Arbitrary values (w-[42px]) and !important (!p-4)
• Automatic CSS filter utilities (e.g. blur-lg, brightness-150)
• CLI with watch mode and configurable content globs
• Vite plugin with HMR, plus a zero-build CDN bundle
• Works with Next.js, Remix, Astro, and any PostCSS-based setup

📄 License

MIT