laurigates/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

| Use this skill when... | Use something else when... | |------------------------|---------------------------| | Configuring CSS processing in Vite | Generating utility classes (use UnoCSS) | | Replacing PostCSS/autoprefixer pipeline | Linting CSS rules (use Stylelint) | | Setting up browser target transpilation | Writing CSS-in-JS (use framework tooling) | | Enabling CSS modules | Formatting CSS code (use Biome/Prettier) | | Minifying CSS for production | Need PostCSS plugins with no Lightning CSS equivalent | | Bundling CSS @import chains | |

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:

| Feature | Modern CSS | Transpiled Output | |---------|-----------|-------------------| | Nesting | .parent { .child { } } | .parent .child { } | | Color functions | oklch(0.7 0.15 180) | rgb(...) fallback | | color-mix() | color-mix(in srgb, red, blue) | Computed color value | | light-dark() | light-dark(white, black) | Media query fallbacks | | Logical properties | margin-inline | margin-left/margin-right | | Media range syntax | (480px <= width <= 768px) | (min-width: 480px) and (max-width: 768px) | | Vendor prefixes | user-select: none | -webkit-user-select: none + unprefixed | | Math functions | clamp(), round() | Static values where possible | | Custom media | @custom-media --mobile (max-width: 768px) | Inlined media queries | | :is() / :not() | Complex selectors | Expanded fallbacks | | system-ui font | font-family: system-ui | Cross-platform font stack |

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

| PostCSS Plugin | Lightning CSS Equivalent | |----------------|-------------------------| | autoprefixer | Built-in (via targets) | | postcss-preset-env | Built-in (syntax lowering) | | postcss-import | --bundle flag | | postcss-nesting | Built-in (via targets) | | postcss-custom-media | drafts.customMedia: true | | cssnano | --minify flag | | postcss-modules | cssModules: true |

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

| Context | Command | |---------|---------| | Quick minify | lightningcss --minify input.css -o output.css | | Bundle + minify | lightningcss --minify --bundle input.css -o output.css | | With targets | lightningcss --minify --targets '>= 0.25%' input.css -o output.css | | Error recovery | lightningcss --error-recovery input.css -o output.css | | Check Vite config | Read vite.config.ts for css.transformer and css.lightningcss | | Check browserslist | Read .browserslistrc or browserslist in package.json |

Quick Reference

| Flag | Description | |------|-------------| | --minify | Minify output CSS | | --bundle | Inline @import rules | | --targets | Browser targets (browserslist query) | | --sourcemap | Generate source maps | | --error-recovery | Skip invalid rules instead of erroring | | -o <file> | Output file path |

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