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. Here are some benchmarks from our test suite:
- Simple utilities: ~7ms for 1,000 utilities
- Complex utilities (with variants): ~9ms for 1,000 utilities
- Arbitrary values: ~3ms for 1,000 utilities
- CSS output: ~1ms for 1,000 rules
All benchmarks run on Bun runtime. Your results may vary based on 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 💙
