A next-generation, Tailwind-like JIT CSS/PostCSS plugin with a powerful plugin system, support for arbitrary values, variants (including dark mode and RTL), efficient watch mode, and CSS variable theme support.

RelaxCSS can be used as a PostCSS plugin (recommended for most build pipelines) or as a standalone CLI tool.

PostCSS Plugin Usage

RelaxCSS is a drop-in PostCSS plugin. It works with PostCSS v8+ and integrates with any PostCSS-based build system (Webpack, Vite, Parcel, etc).

// postcss.config.js
const relaxcss = require('relaxcss');

module.exports = {
  plugins: [
    require('postcss-import'), // must be first
    relaxcss({
      // custom config here
    }),
    require('autoprefixer'),
    // ...
  ]
};

• Supports all RelaxCSS features: JIT utilities, plugins, variants, dark mode, RTL, CSS variables, and more.
• Use your relaxcss.config.js for custom configuration.
• Compatible with PostCSS v8+ and all major build tools.

Table of Contents

• PostCSS Plugin Usage
• Table of Contents
• Features
• Installation
• Quick Start
  • 1. As a CLI (recommended for most projects)
  • 2. As a PostCSS Plugin
• Usage as CLI
  • CLI Options
• Usage as PostCSS Plugin
• Configuration
  • Config Options
    • Example relaxcss.config.js
  • Theme
    • Example
  • Variants
    • Example
  • Dark Mode
  • RTL Support
  • Preflight
  • Plugin System
    • Example
• Arbitrary Values
• Variants & Responsive Utilities
• CSS Variable Theme Support
• @apply and Utility Extraction
• Production Usage & PurgeCSS
• Advanced Examples
  • Custom Utility Plugin
  • Arbitrary Value Utility
  • Responsive and Variant Utilities
• FAQ
  • Why use RelaxCSS as a PostCSS plugin?
• License

Features

• JIT utility generation (like Tailwind, but faster)
• Plugin system for user utilities
• Arbitrary value support (e.g. bg-[#222], p-[4px])
• Variants: responsive, pseudo, dark mode (class/media/both), RTL
• CSS variable theme support (theme values as CSS custom properties)
• Efficient CLI: npx/Node CLI for project-wide class extraction and CSS generation
• @apply and class extraction from HTML/JSX/Vue/Svelte
• Preflight: base styles with fine-grained control

Installation

npm install relaxcss --save-dev
# or
yarn add relaxcss --dev

Quick Start

1. As a CLI (recommended for most projects)

npx relaxcss --out dist/output.css

• Scans your src/ directory for all HTML, JS, TS, JSX, TSX, Vue, and Svelte files.
• Extracts all class names and generates CSS for all used classes.
• Use --watch for watch mode (if implemented).

2. As a PostCSS Plugin

In your postcss.config.js:

const relaxcss = require('relaxcss');

module.exports = {
  plugins: [
    require('postcss-import'), // must be first
    relaxcss({
      // custom config here
    }),
    require('autoprefixer'),
    // ...
  ]
};

Usage as CLI

npx relaxcss --out dist/output.css

• By default, scans src/**/*.{css,html,js,jsx,ts,tsx,vue,svelte}.
• Extracts all class names and @apply utilities.
• Generates CSS for all found classes.
• Supports custom config via relaxcss.config.js.

CLI Options

• --out <file>: Output CSS file (default: dist/output.css)
• --watch: Watch mode (auto-rebuild on file changes)
• --config <file>: Path to custom config (default: relaxcss.config.js)

Usage as PostCSS Plugin

const relaxcss = require('relaxcss');

module.exports = {
  plugins: [
    require('postcss-import'),
    relaxcss({
      // config options
    }),
    require('autoprefixer'),
  ]
};

Configuration

RelaxCSS can be configured via a relaxcss.config.js file or by passing an options object to the plugin.

Config Options

| Option | Type | Default | Description | |----------------|-----------|--------------|-------------| | theme | Object | See below | Design tokens (colors, spacing, etc.) | | variants | Object | See below | Responsive breakpoints, pseudo-classes | | plugins | Array | [] | User utility plugins | | preflight | Object | { enabled: true } | Base styles, overrides, disables | | darkMode | String | 'class' | 'class', 'media', or 'both' | | rtl | Boolean | false | Enable RTL logical property support | | fileExtensions| Array | ["css","html","js","jsx","ts","tsx","vue","svelte"] | Extensions to scan in CLI |

Example relaxcss.config.js

module.exports = {
  theme: {
    colors: {
      primary: '#0070f3',
      gray: {
        100: '#f3f4f6',
        900: '#111827',
      },
    },
    spacing: {
      1: '0.25rem',
      2: '0.5rem',
      4: '1rem',
    },
    // ...
  },
  variants: {
    responsive: ['sm', 'md', 'lg', 'xl', '2xl'],
    pseudoClasses: ['hover', 'focus', 'active', 'disabled'],
  },
  plugins: [
    function({ addUtilities, config }) {
      addUtilities({
        'fancy-border': () => [
          { prop: 'border', value: '2px dashed magenta' },
        ],
      });
    },
  ],
  preflight: {
    enabled: true,
    disableSections: ['box-sizing', 'list-style'],
    overrides: 'body { background: #fafafa; }',
  },
  darkMode: 'class', // or 'media' or 'both'
  rtl: false,
  fileExtensions: ['html', 'js', 'jsx', 'ts', 'tsx', 'vue', 'svelte'],
};

Theme

• theme is an object of design tokens: colors, spacing, fontSize, fontWeight, lineHeight, boxShadow, zIndex, opacity, borderRadius, borderWidth, gridTemplateColumns, gridTemplateRows, flex, transitionProperty, transitionDuration, transitionTimingFunction, maxWidth, maxHeight, etc.
• All theme values are exported as CSS custom properties (variables) for easy use in utilities and custom CSS.

Example

module.exports = {
  theme: {
    colors: {
      primary: '#0070f3',
      gray: { 100: '#f3f4f6', 900: '#111827' },
    },
    spacing: { 1: '0.25rem', 2: '0.5rem', 4: '1rem' },
    // ...
  },
};

Variants

• responsive: Array of breakpoint keys (e.g. sm, md, lg, ...)
• pseudoClasses: Array of pseudo-class variants (e.g. hover, focus, active, ...)

Example

variants: {
  responsive: ['sm', 'md', 'lg', 'xl', '2xl'],
  pseudoClasses: ['hover', 'focus', 'active', 'disabled'],
}

Dark Mode

• darkMode: 'class' (default), 'media', or 'both'
  • 'class': Uses .dark class for dark mode
  • 'media': Uses @media (prefers-color-scheme: dark)
  • 'both': Supports both strategies

RTL Support

• rtl: true or false (default)
• When enabled, logical properties (e.g. margin-inline-start) are used for margin/padding utilities, and direction-aware utilities are generated.

Preflight

• preflight.enabled: Enable/disable base styles
• preflight.disableSections: Array of base style sections to disable (e.g. ['box-sizing', 'list-style'])
• preflight.overrides: Custom CSS to inject at the top of the output

Plugin System

• Add custom utilities via the plugins array.
• Each plugin is a function receiving { addUtilities, config }.
• Use addUtilities({ 'class-name': (config) => [ { prop, value }, ... ] }) to register utilities.

Example

plugins: [
  function({ addUtilities, config }) {
    addUtilities({
      'fancy-border': () => [
        { prop: 'border', value: '2px dashed magenta' },
      ],
    });
  },
]

Arbitrary Values

• Use square brackets for arbitrary values: bg-[#222], p-[4px], w-[72vw], etc.
• Works for colors, spacing, width, height, and more.

Variants & Responsive Utilities

• Prefix classes with breakpoints or pseudo-classes: sm:bg-blue-500, hover:text-red-500, dark:bg-black, rtl:pl-4.
• Combine multiple variants: sm:hover:bg-blue-500, dark:focus:ring-2.

CSS Variable Theme Support

• All theme values are exported as CSS custom properties (e.g. --color-primary, --spacing-4).
• Utilities use these variables for easy theming and overrides.

@apply and Utility Extraction

• RelaxCSS extracts all class names from your source files, including those used in @apply in CSS.
• All used classes are included in the generated CSS.

Production Usage & PurgeCSS

• For production, use PurgeCSS to remove unused CSS.
• Example postcss.config.js:

const relaxcss = require('relaxcss');
const purgecss = require('@fullhuman/postcss-purgecss');

module.exports = {
  plugins: [
    require('postcss-import'),
    relaxcss({ config: './relaxcss.config.js' }),
    require('autoprefixer'),
    purgecss({
      content: [
        './public/**/*.html',
        './src/**/*.js',
        './src/**/*.jsx',
        './src/**/*.ts',
        './src/**/*.tsx',
        './src/**/*.vue',
      ],
      defaultExtractor: content => content.match(/[^\s"'`<>]+/g) || [],
      safelist: {
        standard: ['body', 'html'],
        greedy: [/^(sm:|md:|lg:|xl:|2xl:)/],
      },
    }),
  ],
};

Advanced Examples

Custom Utility Plugin

// relaxcss.config.js
module.exports = {
  plugins: [
    function({ addUtilities, config }) {
      addUtilities({
        'btn-primary': () => [
          { prop: 'background', value: config.theme.colors.primary },
          { prop: 'color', value: '#fff' },
          { prop: 'padding', value: config.theme.spacing[2] },
        ],
      });
    },
  ],
};

Arbitrary Value Utility

<div class="bg-[#222] p-[4px] w-[72vw]"></div>

Responsive and Variant Utilities

<div class="sm:bg-blue-500 hover:text-red-500 dark:bg-black rtl:pl-4"></div>

FAQ

Why use RelaxCSS as a PostCSS plugin?

• Seamless integration: Works with any PostCSS-based build system (Webpack, Vite, Parcel, etc).
• Automatic class extraction: Processes your CSS and source files to generate only the CSS you use.
• Full feature set: All RelaxCSS features (JIT, plugins, variants, dark mode, RTL, CSS variables, etc) are available in plugin mode.
• Production ready: Combine with PurgeCSS and other PostCSS plugins for optimal output.

License

MIT