Headwind

A high-performance Tailwind CSS alternative built with Zig, targeting feature parity with Tailwind 4.1.

Features

🚀 Blazing Fast - Built with Zig for maximum performance ⚡ Zero Dependencies - No Node.js required (optional npm wrapper for convenience) 🎯 Type-Safe - Compile-time safety guarantees 🔥 Hot Reload - Lightning-fast rebuilds with intelligent caching 🎨 Tailwind Compatible - Designed for feature parity with Tailwind 4.1 🧩 Extensible - Powerful plugin system

Current Status

This project is in active development. Phase 1 (Project Setup & Core Architecture) is complete.

See TODO.md for the comprehensive implementation roadmap.

Installation

From Source (Current)

git clone https://github.com/yourusername/headwind.git
cd headwind
zig build

Via npm (Coming Soon)

npm install -g @headwind/headwind

Via Homebrew (Coming Soon)

brew install headwind

Quick Start

1. Initialize a new project

headwind init

This creates a headwind.config.json file:

{
  "content": {
    "files": [
      "src/**/*.{html,js,jsx,ts,tsx,vue,svelte}"
    ]
  },
  "theme": {
    "extend": {}
  },
  "plugins": []
}

2. Build your CSS

headwind build

3. Watch for changes (Coming Soon)

headwind watch

Configuration

Headwind uses zig-config for configuration management, supporting multiple formats and sources.

Configuration File

Create headwind.config.json in your project root:

{
  "content": {
    "files": ["src/**/*.{html,js,jsx,ts,tsx}"],
    "exclude": ["node_modules/**", "dist/**"]
  },
  "theme": {
    "colors": {
      "primary": "#3b82f6",
      "secondary": "#8b5cf6"
    },
    "extend": {
      "spacing": {
        "128": "32rem"
      }
    }
  },
  "darkMode": {
    "strategy": "class",
    "className": "dark"
  },
  "build": {
    "output": "dist/headwind.css",
    "minify": true,
    "sourcemap": true
  },
  "plugins": []
}

Environment Variables

Override configuration with environment variables:

export HEADWIND_BUILD_MINIFY=true
export HEADWIND_BUILD_OUTPUT=dist/styles.css
headwind build

Configuration Schema

pub const HeadwindConfig = struct {
    content: ContentConfig,
    theme: ThemeConfig,
    build: BuildConfig,
    darkMode: DarkModeConfig,
    plugins: []PluginConfig,
    prefix: []const u8 = "",
    separator: []const u8 = ":",
};

See src/config/schema.zig for the full schema.

CLI Commands

headwind build          # Build CSS from source files
headwind watch          # Watch for changes and rebuild (coming soon)
headwind init           # Initialize configuration file
headwind check          # Validate configuration
headwind clean          # Clean cache
headwind version        # Show version information
headwind help           # Show help message

Architecture

Headwind is designed with performance and safety in mind:

Core Modules

• Core - Fundamental types and memory management
• Config - Configuration loading and validation
• Scanner - File system scanning and class extraction
• Parser - CSS class name parsing and validation
• Generator - CSS rule generation and optimization
• Cache - Intelligent caching system
• CLI - Command-line interface

Memory Management

Headwind uses Zig's allocator system with:

• Arena allocators for request-scoped memory
• String interning for deduplication
• Object pools for reusable allocations
• Zero-copy parsing where possible

Performance Features

• Multi-threaded file scanning
• Lock-free cache data structures
• SIMD-accelerated string matching (planned)
• Incremental builds with smart caching
• Parallel CSS generation

Development

Prerequisites

• Zig 0.12.0 or later
• zig-config (included as dependency)

Build

# Build the project
zig build

# Run tests
zig build test

# Run benchmarks
zig build bench

# Format code
zig build fmt

# Cross-compile for all platforms
zig build cross

Project Structure

headwind/
├── src/
│   ├── main.zig              # CLI entry point
│   ├── headwind.zig          # Library entry point
│   ├── core/                 # Core types and utilities
│   │   ├── types.zig
│   │   └── allocator.zig
│   ├── config/               # Configuration system
│   │   ├── schema.zig
│   │   └── loader.zig
│   ├── scanner/              # File scanning (planned)
│   ├── parser/               # CSS parsing (planned)
│   ├── generator/            # CSS generation (planned)
│   ├── cache/                # Caching system (planned)
│   ├── cli/                  # CLI utilities (planned)
│   └── utils/                # Shared utilities
│       └── string.zig
├── test/                     # Tests
├── examples/                 # Example projects
├── build.zig                 # Build configuration
├── build.zig.zon            # Dependency configuration
└── TODO.md                   # Implementation roadmap

Roadmap

See TODO.md for the comprehensive roadmap with 650+ tasks organized into 17 phases.

Phase 1: ✅ Complete

• Project setup and build system
• Core architecture
• Configuration system with zig-config
• Memory management utilities
• String utilities
• CLI framework

Phase 2-17: 🚧 Planned

• CSS scanning and parsing
• Utility class system
• Variant system
• Modern CSS features (Tailwind 4.1)
• Plugin system
• Performance optimization
• Testing and benchmarks
• Documentation and tooling
• Ecosystem integration

Benchmarks (Planned)

Target performance metrics vs Tailwind CSS:

• 10x faster cold start
• 5x faster incremental builds
• 50% lower memory usage
• Sub-millisecond class extraction

Contributing

Contributions are welcome! Please see CONTRIBUTING.md (coming soon) for guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

• Inspired by Tailwind CSS
• Inspired by UnoCSS
• Built with Zig
• Configuration powered by zig-config

Links

• Documentation: [Coming Soon]
• GitHub: https://github.com/yourusername/headwind
• Discord: [Coming Soon]

---

Built with ❤️ and Zig