Repository files navigation

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# ornpm install headwind

1. Initialize Headwind:

# Create a config filebunx headwind init

This creates aheadwind.config.ts file:

importtype{HeadwindOptions}from'headwind'exportdefault{content:['./src/**/*.{html,js,ts,jsx,tsx}'],output:'./dist/headwind.css',minify:false,}satisfiesHeadwindOptions

2. Add utility classes to your HTML:

<divclass="flex items-center justify-between p-4 bg-blue-500 text-white rounded-lg shadow-md hover:bg-blue-600"><h1class="text-2xl font-bold">Hello Headwind!</h1></div>

3. Build your CSS:

# Build oncebunx headwind build# Build and watch for changesbunx headwind watch# Build with optionsbunx headwind build --output ./dist/styles.css --minify

You can also use Headwind programmatically:

import{build}from'headwind'constresult=awaitbuild({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 onceheadwind watch# Build and watch for changesheadwind init# Create config fileheadwind analyze# Analyze utility class usageheadwind clean# Remove output CSS fileheadwind preflight# Generate preflight CSS onlyheadwind --version# Show versionheadwind --help# Show help

Headwind supports extensive configuration options:

importtype{HeadwindOptions}from'headwind'exportdefault{// Content sources to scan for utility classescontent:['./src/**/*.{html,js,ts,jsx,tsx}'],// Output CSS file pathoutput:'./dist/styles.css',// Minify output CSSminify:false,// Enable watch modewatch:false,// Enable verbose loggingverbose:false,// Theme customizationtheme:{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 variantsvariants:{// ... configure breakpoints, states, etc.},// Safelist (always include these classes)safelist:['bg-red-500','text-green-500'],// Blocklist (never include these classes)blocklist:['debug-*'],// Custom rulesrules:[],// Preflight CSS (normalize/reset styles)preflights:[],// Presetspresets:[],}satisfiesHeadwindOptions

For more configuration options, see theConfiguration 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:

<divclass="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 --><divclass=":hw: flex items-center justify-between px-4 py-2 bg-white rounded-lg shadow-md">  Content</div><!-- After build --><divclass="hw-2k9d3a">  Content</div>

This reduces HTML file size by up to 60%. Learn more in theCompile Class documentation.

Headwind includes a comprehensive test suite with 860+ tests:

# Run all testsbuntest# Run specific test filesbuntest test/performance.test.ts# Run tests in watch modebuntest --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! 🏆🔥

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 suitebun run benchmark# Or run from the packages/headwind directorycd packages/headwindbun run benchmark

All benchmarks useMitata for accurate measurements and run on Bun runtime. Results may vary based on your hardware.

To contribute to Headwind development:

# Clone the repositorygit clone https://github.com/stacksjs/headwind.gitcd headwind# Install dependenciesbun install# Run testsbuntest# Run tests in watch modebuntest --watch# Run performance benchmarksbuntest test/performance.test.ts# Type checkbun run typecheck# Build the packagebun run build

For comprehensive documentation, visitheadwind.stacksjs.org

• Installation Guide
• Usage Guide
• Configuration
• CLI Reference
• API Reference

Please see ourreleases page for more information on what has changed recently.

Please seeCONTRIBUTING 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:

Discussions on GitHub

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.

• JetBrains
• The Solana Foundation

The MIT License (MIT). Please seeLICENSE for more information.

Made with 💙