Claude Code for Lightning CSS — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are using Lightning CSS, the Rust-based CSS parser, transformer, and minifier that replaces PostCSS, Autoprefixer, and CSS Nano in a single tool. Lightning CSS handles vendor prefixing, nesting, custom media queries, and minification at build time. Claude Code can configure it, but it keeps generating PostCSS configs with plugin chains instead.

What Claude Code Gets Wrong By Default

  1. Creates postcss.config.js with plugin arrays. Claude sets up PostCSS with autoprefixer, postcss-nesting, and cssnano plugins. Lightning CSS handles all of these natively — no PostCSS config needed.

  2. Uses PostCSS plugin syntax for transforms. Claude writes @apply directives and PostCSS custom syntax. Lightning CSS uses standard CSS nesting syntax (the spec), not PostCSS-specific extensions.

  3. Adds autoprefixer as a separate dependency. Claude installs autoprefixer alongside the bundler. Lightning CSS has built-in vendor prefixing based on your browser targets — no separate tool needed.

  4. Configures CSS minification separately. Claude adds cssnano or clean-css to the build pipeline. Lightning CSS minifies as part of its transform step with a single minify: true option.

The CLAUDE.md Configuration

# Lightning CSS Project

## CSS Tooling
- CSS: Lightning CSS (lightningcss package)
- Replaces: PostCSS, Autoprefixer, CSS Nano — all in one
- Integration: Vite plugin or standalone CLI/API

## Lightning CSS Rules
- No postcss.config.js needed
- Browser targets set in package.json "browserslist" or config
- Vendor prefixes: automatic based on targets (no autoprefixer)
- Nesting: standard CSS nesting syntax (& parent selector)
- Minification: built-in, enable with minify: true
- CSS Modules: built-in support with cssModules: true
- Custom media queries and color functions: auto-compiled

## Conventions
- Vite integration: vite-plugin-lightningcss in vite.config.ts
- Targets: "> 0.5%, last 2 versions, not dead"
- Write modern CSS — Lightning CSS compiles down for targets
- Use standard CSS nesting, not PostCSS @nest syntax
- Color functions (oklch, lab) compiled to rgb for older browsers
- No PostCSS plugins, no PostCSS config files

Workflow Example

You want to migrate from PostCSS to Lightning CSS in a Vite project. Prompt Claude Code:

“Replace PostCSS with Lightning CSS in this Vite project. Remove autoprefixer and cssnano dependencies, convert any PostCSS-specific syntax to standard CSS, and configure Lightning CSS with the Vite plugin.”

Claude Code should remove postcss.config.js, uninstall PostCSS plugins, install lightningcss and vite-plugin-lightningcss, add the plugin to vite.config.ts with browser targets, and convert any @nest rules to standard CSS nesting syntax.

Common Pitfalls

  1. PostCSS plugin compatibility expectations. Claude tries to use PostCSS plugins like postcss-import alongside Lightning CSS. Lightning CSS does not use the PostCSS plugin system. If you need file imports, use your bundler’s CSS import handling or Lightning CSS’s own bundle API.

  2. Nesting syntax differences. Claude writes PostCSS-style @nest .parent & { } syntax. Lightning CSS uses the standard CSS nesting spec: .parent { & .child { } } with the & selector. The old @nest at-rule is not supported.

  3. Color function output surprises. Claude writes oklch(0.7 0.15 180) expecting it to stay as oklch in output. Lightning CSS compiles modern color functions down to rgb() when browser targets do not support them. The visual result is the same, but the output CSS looks different from the source.