A blazingly fast, utility-first CSS framework built with Bun. Headwind generates only the CSS you need by scanning your files for utility classes, providing Tailwind CSS-compatible utilities with exceptional performance.
- ⚡️ Blazingly Fast - Built with Bun for exceptional performance (1000+ utilities in <10ms)
- 🎯 On-Demand Generation - Only generates CSS for utilities you actually use
- 🎨 Tailwind-Compatible - Familiar utility classes and syntax
- 💪 Fully Typed - Complete TypeScript support with type-safe configuration
- 🔧 Highly Configurable - Customize theme, colors, spacing, variants, and more
- 📦 Zero Runtime Dependencies - Minimal footprint, maximum performance
- 🔥 Hot Reload - Watch mode for instant rebuilds during development
- 🎭 Variant Support - Responsive, state (hover, focus, etc.), dark mode, and custom variants
- ✨ Modern CSS Features - Grid, Flexbox, animations, transforms, filters, and more
- 🔨 Class Compilation - Optimize HTML by compiling utility groups into single class names
- 🧪 Thoroughly Tested - 860+ tests including comprehensive performance benchmarks
- 🚀 Production Ready - Minification, preflight CSS, and optimized builds
- ⌨️ CLI & API - Use via command line or programmatic API
bun add headwind
# or
npm install headwind- Initialize Headwind:
# Create a config file
bunx headwind initThis creates a headwind.config.ts file:
import type { HeadwindOptions } from 'headwind'
export default {
content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
output: './dist/headwind.css',
minify: false,
} satisfies HeadwindOptions- Add utility classes to your HTML:
<div class="flex items-center justify-between p-4 bg-blue-500 text-white rounded-lg shadow-md hover:bg-blue-600">
<h1 class="text-2xl font-bold">Hello Headwind!</h1>
</div>- Build your CSS:
# Build once
bunx headwind build
# Build and watch for changes
bunx headwind watch
# Build with options
bunx headwind build --output ./dist/styles.css --minifyYou can also use Headwind programmatically:
import { build } from 'headwind'
const result = await build({
content: ['./src/**/*.html'],
output: './dist/styles.css',
minify: true,
})
console.log(`Generated ${result.classes.size} classes in ${result.duration}ms`)Headwind provides a comprehensive CLI:
headwind build # Build CSS once
headwind watch # Build and watch for changes
headwind init # Create config file
headwind analyze # Analyze utility class usage
headwind clean # Remove output CSS file
headwind preflight # Generate preflight CSS only
headwind --version # Show version
headwind --help # Show helpHeadwind supports extensive configuration options:
import type { HeadwindOptions } from 'headwind'
export default {
// Content sources to scan for utility classes
content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
// Output CSS file path
output: './dist/styles.css',
// Minify output CSS
minify: false,
// Enable watch mode
watch: false,
// Enable verbose logging
verbose: false,
// Theme customization
theme: {
colors: {
primary: '#3b82f6',
secondary: '#10b981',
// ... extend or override default colors
},
spacing: {
// ... customize spacing scale
},
fontSize: {
// ... customize font sizes
},
// ... and more
},
// Shortcuts (utility aliases)
shortcuts: {
btn: 'px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600',
card: 'p-6 bg-white rounded-lg shadow-md',
},
// Custom variants
variants: {
// ... configure breakpoints, states, etc.
},
// Safelist (always include these classes)
safelist: ['bg-red-500', 'text-green-500'],
// Blocklist (never include these classes)
blocklist: ['debug-*'],
// Custom rules
rules: [],
// Preflight CSS (normalize/reset styles)
preflights: [],
// Presets
presets: [],
} satisfies HeadwindOptionsFor more configuration options, see the Configuration Guide.
Headwind provides a comprehensive set of utility classes compatible with Tailwind CSS:
- Layout: display, position, overflow, z-index, etc.
- Flexbox & Grid: flex, grid, gap, align, justify, etc.
- Spacing: margin, padding with full scale support
- Sizing: width, height, min/max sizes
- Typography: font family, size, weight, line height, text alignment, etc.
- Backgrounds: colors, gradients, images, position, size
- Borders: width, color, radius, style
- Effects: shadow, opacity, blend modes, filters
- Transforms: translate, rotate, scale, skew
- Transitions & Animations: duration, timing, delay
- Interactivity: cursor, pointer events, user select, scroll behavior
- Advanced: mask utilities, backdrop filters, ring utilities
- Responsive:
sm:,md:,lg:,xl:,2xl: - State:
hover:,focus:,active:,disabled:,visited:,checked: - Pseudo-elements:
before:,after:,placeholder:,selection: - Group/Peer:
group-hover:,peer-focus: - Dark mode:
dark: - Positional:
first:,last:,odd:,even: - Important:
!prefix (e.g.,!text-red-500)
Headwind supports arbitrary values for maximum flexibility:
<div class="w-[500px] h-[calc(100vh-4rem)] bg-[#1da1f2] text-[clamp(1rem,5vw,3rem)]">
Custom values!
</div>Optimize your HTML by compiling utility groups into single class names:
<!-- Before -->
<div class=":hw: flex items-center justify-between px-4 py-2 bg-white rounded-lg shadow-md">
Content
</div>
<!-- After build -->
<div class="hw-2k9d3a">
Content
</div>This reduces HTML file size by up to 60%. Learn more in the Compile Class documentation.
Headwind includes a comprehensive test suite with 860+ tests:
# Run all tests
bun test
# Run specific test files
bun test test/performance.test.ts
# Run tests in watch mode
bun test --watch- Core Functionality: Parser, generator, scanner, builder
- Utilities: Layout, typography, colors, spacing, grid, flexbox
- Variants: Responsive, state, pseudo-elements, combinations
- Advanced Features: Shortcuts, custom rules, arbitrary values
- Performance: Benchmarks for generation speed and memory efficiency
- Edge Cases: Invalid inputs, complex nesting, duplicate handling
Headwind is designed for speed. We've benchmarked against other popular utility-first CSS frameworks to demonstrate our performance advantages.
Our comprehensive benchmark suite compares Headwind with other popular utility-first CSS frameworks. Headwind WINS ALL 10/10 CATEGORIES! 🏆🔥
| Scenario | Headwind | UnoCSS | Tailwind v3 | Tailwind v4 | Performance |
|---|---|---|---|---|---|
| Simple Utilities (10 classes) | 6.20µs | 17.49µs | 8.12ms | 21.78ms | Headwind: 2.8x faster than UnoCSS, 1,310x faster than v3, 3,513x faster than v4 ⚡ |
| Complex Utilities (11 classes) | 10.17µs | 23.69µs | 7.76ms | 21.37ms | Headwind: 2.3x faster than UnoCSS, 763x faster than v3, 2,101x faster than v4 ⚡ |
| Arbitrary Values (7 classes) | 3.03µs | 25.87µs | 7.76ms | 20.90ms | Headwind: 8.5x faster than UnoCSS, 2,561x faster than v3, 6,897x faster than v4 ⚡ |
| Real-world Components (6 strings) | 7.59µs | 98.78µs | 147.22ms | 124.23ms | Headwind: 13x faster than UnoCSS, 19,397x faster than v3, 16,369x faster than v4 ⚡ |
| Large Scale (1000 utilities) | 259.23µs | 404.17µs | 7.95ms | 20.94ms | Headwind: 1.6x faster than UnoCSS, 31x faster than v3, 81x faster than v4 ⚡ |
| CSS Output (1000 rules) | 558.03µs | 69.23ms | 8.11ms | 21.33ms | Headwind: 124x faster than UnoCSS, 15x faster than v3, 38x faster than v4 ⚡ |
| Color Utilities (240 classes) | 206.40µs | 304.94µs | 7.88ms | 20.90ms | Headwind: 1.5x faster than UnoCSS, 38x faster than v3, 101x faster than v4 ⚡ |
| Responsive (1000 classes) | 519.39µs | 659.12µs | 7.94ms | 20.20ms | Headwind: 1.3x faster than UnoCSS, 15x faster than v3, 39x faster than v4 ⚡ |
| Interactive States (550 classes) | 567.40µs | 915.33µs | 8.25ms | 21.42ms | Headwind: 1.6x faster than UnoCSS, 15x faster than v3, 38x faster than v4 ⚡ |
| Duplicate Handling (6000 items) | 31.24µs | 1.61ms | 8.54ms | 22.17ms | Headwind: 52x faster than UnoCSS, 273x faster than v3, 710x faster than v4 ⚡ |
Key Takeaways:
- 🏆 HEADWIND WINS ALL 10/10 CATEGORIES vs UnoCSS, Tailwind v3, AND Tailwind v4! 🏆
- Real-world components: Up to 19,397x faster than Tailwind v3 - Dominant performance for actual usage
- Duplicate handling: 710x faster than Tailwind v4, 273x faster than v3, 52x faster than UnoCSS
- Simple utilities: 3,513x faster than Tailwind v4, 1,310x faster than v3, 2.8x faster than UnoCSS
- CSS output generation: 124x faster than UnoCSS, 38x faster than Tailwind v4, 15x faster than v3
- Consistently faster: Beats all frameworks across all 10 benchmark categories
- Production-ready performance: Optimized for real-world applications with complex component patterns
You can run the benchmarks yourself to see the performance on your hardware:
# Run the comprehensive benchmark suite
bun run benchmark
# Or run from the packages/headwind directory
cd packages/headwind
bun run benchmarkAll benchmarks use Mitata for accurate measurements and run on Bun runtime. Results may vary based on your hardware.
To contribute to Headwind development:
# Clone the repository
git clone https://github.com/stacksjs/headwind.git
cd headwind
# Install dependencies
bun install
# Run tests
bun test
# Run tests in watch mode
bun test --watch
# Run performance benchmarks
bun test test/performance.test.ts
# Type check
bun run typecheck
# Build the package
bun run buildFor comprehensive documentation, visit headwind.stacksjs.org
Please see our releases page for more information on what has changed recently.
Please see CONTRIBUTING for details.
We welcome contributions! Whether it's:
- 🐛 Bug reports and fixes
- ✨ New utility classes or features
- 📝 Documentation improvements
- ⚡️ Performance optimizations
- 🧪 Additional test coverage
For help, discussion about best practices, or any other conversation that would benefit from being searchable:
For casual chit-chat with others using this package:
Join the Stacks Discord Server
“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
The MIT License (MIT). Please see LICENSE for more information.
Made with 💙
