Lightning CSS

Lightning CSS

Lightning CSS is an extremely fast CSS parser, transformer, bundler, and minifier written in Rust. It replaces PostCSS + autoprefixer + postcss-preset-env in a single tool.

When to Use This Skill

Core Expertise

• Rust-native: 100x+ faster than PostCSS for transforms
• All-in-one: Replaces autoprefixer, postcss-preset-env, postcss-import, cssnano
• Syntax lowering: Modern CSS to browser-compatible CSS based on targets
• Vendor prefixing: Automatic addition and removal based on targets
• CSS modules: Built-in scoped class names
• Minification: Smaller output than esbuild's CSS minifier
• Bundling: Inlines @import rules with dependency resolution

Installation

# As Vite dependency (most common)
npm add -D lightningcss browserslist

# Standalone CLI
npm add -g lightningcss-cli

# Bun
bun add -d lightningcss browserslist

Vite Integration

Basic Setup

// vite.config.ts
import { defineConfig } from 'vite'
import browserslist from 'browserslist'
import { browserslistToTargets } from 'lightningcss'

export default defineConfig({
  css: {
    transformer: 'lightningcss',
    lightningcss: {
      targets: browserslistToTargets(browserslist('>= 0.25%'))
    }
  },
  build: {
    cssMinify: 'lightningcss'
  }
})

With UnoCSS (Recommended Combo)

// vite.config.ts
import UnoCSS from 'unocss/vite'
import browserslist from 'browserslist'
import { browserslistToTargets } from 'lightningcss'

export default defineConfig({
  plugins: [UnoCSS()],
  css: {
    transformer: 'lightningcss',
    lightningcss: {
      targets: browserslistToTargets(browserslist('>= 0.25%'))
    }
  },
  build: {
    cssMinify: 'lightningcss'
  }
})

CSS Modules via Vite

// vite.config.ts - use css.lightningcss.cssModules (NOT css.modules)
export default defineConfig({
  css: {
    transformer: 'lightningcss',
    lightningcss: {
      cssModules: {
        pattern: '[hash]_[local]'
      }
    }
  }
})

Draft Syntax Features

// Enable experimental CSS features
export default defineConfig({
  css: {
    transformer: 'lightningcss',
    lightningcss: {
      drafts: {
        customMedia: true
      }
    }
  }
})

CLI Usage

# Transform and minify
lightningcss --minify --bundle --targets '>= 0.25%' input.css -o output.css

# With source maps
lightningcss --minify --bundle --sourcemap input.css -o output.css

# Error recovery (skip invalid rules)
lightningcss --error-recovery input.css -o output.css

Transformation Features

Lightning CSS automatically transpiles based on browser targets:

CSS Modules

Lightning CSS provides built-in CSS modules support:

/* styles.module.css */
.container {
  composes: base from './base.module.css';
  padding: 1rem;
}

.title {
  color: var(--heading-color);
}

// Component usage
import styles from './styles.module.css'
element.className = styles.container

Replacing PostCSS Pipeline

Migration Steps

1. Remove PostCSS dependencies and postcss.config.js
2. Add lightningcss and browserslist as dev dependencies
3. Set css.transformer: 'lightningcss' in Vite config
4. Set build.cssMinify: 'lightningcss'
5. Configure targets via browserslist (.browserslistrc or package.json)
6. Move CSS modules config from css.modules to css.lightningcss.cssModules

Browser Targets

# .browserslistrc
>= 0.25%
not dead
not op_mini all

// package.json alternative
{
  "browserslist": [">= 0.25%", "not dead"]
}

Agentic Optimizations

Quick Reference

References

• Official docs: https://lightningcss.dev
• Vite integration: https://vite.dev/guide/features#lightning-css
• Transpilation features: https://lightningcss.dev/transpilation.html
• CSS modules: https://lightningcss.dev/css-modules.html