tailwindcss-performance — Claude Code skill: setup and install
tailwindcss-performance is a Claude Code skill for tuning Tailwind CSS builds and trimming generated CSS. It activates for Tailwind v4 performance work, content detection issues, and dynamic class names.
MIT 239 installs ★ 66 updated 2026-06-18
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a claude-codeWhat tailwindcss-performance does
The skill covers Tailwind CSS build settings, including source detection, removal of unused styles, minification, and CSS bundle size. For v4, it explains automatic source discovery and explicit file patterns with @source.
For dynamic classes, it outlines complete class names, data attributes, and adding classes with @source inline. It also covers Vite and PostCSS settings, critical CSS extraction, caching, and transitions. Tailwind does not detect class names assembled from string fragments, so those classes need full names or an explicit safelist.
What it helps with
- reduce the size of a Tailwind CSS build
- configure which files Tailwind scans
- fix styles missing for dynamic class names
- set up CSS minification in Vite or PostCSS
- remove unused styles and theme values
Example prompts for the agent
- Review this Tailwind v4 build and find what is adding to the CSS bundle.
- Configure Tailwind source detection so it skips unrelated files.
- Why are styles missing for the dynamic classes in this component?
How to install tailwindcss-performance
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a claude-code2Manually: put the files in place
~/.claude/skills/tailwindcss-performance/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tailwindcss-performance/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a codex2Manually: put the files in place
.agents/skills/tailwindcss-performance/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a cursor2Manually: put the files in place
.cursor/skills/tailwindcss-performance/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install JosiahSiegel/claude-plugin-marketplace plugins/tailwindcss-master/skills/tailwindcss-performance2Manually: put the files in place
.github/skills/tailwindcss-performance/SKILL.md1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a gemini-cli2Platform CLI
gemini skills install https://github.com/JosiahSiegel/claude-plugin-marketplace --path plugins/tailwindcss-master/skills/tailwindcss-performanceManually: put the files in place
.devin/skills/tailwindcss-performance/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tailwindcss-performance
How do I install tailwindcss-performance in Claude Code?
Run npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a claude-code. The skill file is placed at ~/.claude/skills/tailwindcss-performance/SKILL.md.
What does tailwindcss-performance do?
It helps tune Tailwind CSS builds, reduce generated CSS, configure class discovery, and investigate dynamic class names. It also covers minification and Tailwind v4 performance settings.
Why does Tailwind miss dynamically constructed classes?
Tailwind cannot detect class names assembled from string fragments. The skill describes using complete class names, data attributes, or adding classes with @source inline.
Source text
SKILL.md · MIT
---
name: tailwindcss-performance
description: |
Tailwind CSS performance optimization including v4 improvements.
PROACTIVELY activate for: (1) Tailwind v4 Oxide engine performance, (2) Lightning CSS minification, (3) reducing CSS bundle size, (4) content config tuning to avoid scanning unused files, (5) safelist for dynamic classes (without bloating), (6) production builds with @apply minimization, (7) critical CSS extraction, (8) HTTP caching of generated CSS, (9) avoiding @apply overuse (utility-first preferred), (10) PurgeCSS / content-detection edge cases.
Provides: performance tuning checklist, Oxide engine notes, content config patterns, safelist guidance, and critical-CSS workflow.
---
# Tailwind CSS Performance Optimization
## v4 Performance Improvements
Tailwind CSS v4 features a completely rewritten engine in Rust:
| Metric | v3 | v4 |
|--------|----|----|
| Full builds | Baseline | Up to 5x faster |
| Incremental builds | Milliseconds | Microseconds (100x+) |
| Engine | JavaScript | Rust |
## JIT (Just-In-Time) Compilation
### How JIT Works
JIT generates styles on-demand as classes are discovered in your files:
1. Scans source files for class names
2. Generates only the CSS you use
3. Produces minimal, optimized output
### v4: Always JIT
Unlike v3, JIT is always enabled in v4—no configuration needed:
```css
@import "tailwindcss";
/* JIT is automatic */
```
## Content Detection
### Automatic Detection (v4)
v4 automatically detects template files—no content configuration required:
```css
/* v4 - Works automatically */
@import "tailwindcss";
```
### Explicit Content (v4)
If automatic detection fails, specify sources explicitly:
```css
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";
@source "./components/**/*.{js,jsx,ts,tsx}";
```
### Excluding Paths
```css
@source not "./src/legacy/**";
```
## Tree Shaking
### How It Works
Tailwind's build process removes unused CSS:
```text
Source: All possible utilities (~15MB+)
↓
Scan: Find used class names
↓
Output: Only used styles (~10-50KB typical)
```
### Production Build
```bash
# Vite - automatically optimized for production
npm run build
# PostCSS - ensure NODE_ENV is set
NODE_ENV=production npx postcss input.css -o output.css
```
## Dynamic Class Names
### The Problem
Tailwind can't detect dynamically constructed class names:
```javascript
// BAD - Classes won't be generated
const color = 'blue'
className={`text-${color}-500`} // ❌ Not detected
const size = 'lg'
className={`text-${size}`} // ❌ Not detected
```
### Solutions
#### 1. Use Complete Class Names
```javascript
// GOOD - Full class names
const colorClasses = {
blue: 'text-blue-500',
red: 'text-red-500',
green: 'text-green-500',
}
className={colorClasses[color]} // ✓ Detected
```
#### 2. Use Data Attributes
```javascript
// GOOD - Style based on data attributes
<div data-color={color} className="data-[color=blue]:text-blue-500 data-[color=red]:text-red-500">
```
#### 3. Safelist Classes
```css
/* In your CSS for v4 */
@source inline("text-blue-500 text-red-500 text-green-500");
```
#### 4. CSS Variables
```css
@theme {
--color-dynamic: oklch(0.6 0.2 250);
}
```
```html
<div class="text-[var(--color-dynamic)]">Dynamic color</div>
```
## Optimizing Transitions
### Use Specific Transitions
```html
<!-- SLOW - Transitions all properties -->
<button class="transition-all duration-200">
<!-- FAST - Only transitions specific properties -->
<button class="transition-colors duration-200">
<button class="transition-transform duration-200">
<button class="transition-opacity duration-200">
```
### GPU-Accelerated Properties
Prefer `transform` and `opacity` for smooth animations:
```html
<!-- GOOD - GPU accelerated -->
<div class="transform hover:scale-105 transition-transform">
<!-- GOOD - GPU accelerated -->
<div class="opacity-100 hover:opacity-80 transition-opacity">
<!-- SLOW - May cause repaints -->
<div class="left-0 hover:left-4 transition-all">
```
## CSS Variable Usage
### Prefer Native Variables
In v4, use CSS variables directly instead of `theme()`:
```css
/* v3 - Uses theme() function */
.element {
color: theme(colors.blue.500);
}
/* v4 - Use CSS variables (faster) */
.element {
color: var(--color-blue-500);
}
```
### Static Theme Values
For performance-critical paths:
```css
@import "tailwindcss/theme.css" theme(static);
```
This inlines theme values instead of using CSS variables.
## Build Optimization
### Vite Configuration
```javascript
// vite.config.js
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [tailwindcss()],
build: {
// Minify CSS
cssMinify: 'lightningcss',
// Optimize chunks
rollupOptions: {
output: {
manualChunks: {
// Split vendor CSS if needed
}
}
}
}
})
```
### PostCSS with cssnano
```javascript
// postcss.config.mjs
export default {
plugins: {
'@tailwindcss/postcss': {},
cssnano: process.env.NODE_ENV === 'production' ? {} : false
}
}
```
## Reducing Bundle Size
### 1. Avoid Unused Plugins
```css
/* Only load what you need */
@plugin "@tailwindcss/typography";
/* Don't load unused plugins */
```
### 2. Limit Color Palette
```css
@theme {
/* Disable default colors */
--color-*: initial;
/* Define only needed colors */
--color-primary: oklch(0.6 0.2 250);
--color-secondary: oklch(0.7 0.15 180);
--color-gray-100: oklch(0.95 0 0);
--color-gray-900: oklch(0.15 0 0);
}
```
### 3. Limit Breakpoints
```css
@theme {
/* Remove unused breakpoints */
--breakpoint-2xl: initial;
/* Keep only what you use */
--breakpoint-sm: 640px;
--breakpoint-md: 768px;
--breakpoint-lg: 1024px;
}
```
## Caching Strategies
### Development
- v4's incremental builds are already extremely fast
- No additional caching needed in most cases
### CI/CD
```yaml
# GitHub Actions example
- name: Cache node_modules
uses: actions/cache@v4
with:
path: node_modules
key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
- name: Build
run: npm run build
```
## Measuring Performance
### Build Time Analysis
```bash
# Time your build
time npm run build
# Verbose output
DEBUG=tailwindcss:* npm run build
```
### Bundle Analysis
```bash
# Install analyzer
npm install -D vite-bundle-analyzer
# Analyze bundle
npm run build -- --analyze
```
### CSS Size Check
```bash
# Check output CSS size
ls -lh dist/assets/*.css
# Gzipped size
gzip -c dist/assets/main.css | wc -c
```
## Performance Checklist
### Development
- [ ] JIT is working (styles update instantly)
- [ ] No console warnings about large files
- [ ] Hot reload is fast
### Production
- [ ] `NODE_ENV=production` is set
- [ ] CSS is minified
- [ ] Unused CSS is removed
- [ ] No dynamic class name issues
- [ ] CSS size is reasonable (<50KB typical)
### Common Issues
| Issue | Solution |
|-------|----------|
| Large CSS output | Check for dynamic classes, safelist issues |
| Slow builds | Ensure v4, check file globs |
| Missing styles | Check content detection, class names |
| Slow animations | Use GPU-accelerated properties |
## Lazy Loading CSS
For very large apps, consider code-splitting CSS:
```javascript
// Dynamically import CSS for routes
const AdminPage = lazy(() =>
import('./admin.css').then(() => import('./AdminPage'))
)
```
## Best Practices Summary
1. **Let JIT do its work** - Don't safelist unnecessarily
2. **Use complete class names** - Avoid dynamic concatenation
3. **Specific transitions** - Not `transition-all`
4. **GPU properties** - Prefer `transform` and `opacity`
5. **Minimal theme** - Only define what you use
6. **Production builds** - Always use production mode
7. **Measure** - Check your actual CSS size
© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace