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
- Remove PostCSS dependencies and
postcss.config.js - Add
lightningcss and browserslist as dev dependencies - Set
css.transformer: 'lightningcss' in Vite config - Set
build.cssMinify: 'lightningcss' - Configure targets via browserslist (
.browserslistrc or package.json) - 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
