{"id":31906331,"url":"https://github.com/stacksjs/headwind","last_synced_at":"2025-10-13T14:24:43.109Z","repository":{"id":317758398,"uuid":"1068620505","full_name":"stacksjs/headwind","owner":"stacksjs","description":"A Tailwind-like utility-first CSS framework, powered by Bun.","archived":false,"fork":false,"pushed_at":"2025-10-09T16:12:26.000Z","size":22508,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-10T00:19:42.683Z","etag":null,"topics":["atomic-css","bun","framework","tailwindcss","unocss","utility-classes"],"latest_commit_sha":null,"homepage":"https://headwind.netlify.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacksjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["stacksjs","chrisbbreuer"],"open_collective":"stacksjs"}},"created_at":"2025-10-02T16:51:43.000Z","updated_at":"2025-10-07T06:13:04.000Z","dependencies_parsed_at":"2025-10-02T22:23:23.260Z","dependency_job_id":null,"html_url":"https://github.com/stacksjs/headwind","commit_stats":null,"previous_names":["stacksjs/headwind"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/stacksjs/headwind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fheadwind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fheadwind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fheadwind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fheadwind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacksjs","download_url":"https://codeload.github.com/stacksjs/headwind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fheadwind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015724,"owners_count":26085748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atomic-css","bun","framework","tailwindcss","unocss","utility-classes"],"created_at":"2025-10-13T14:24:40.414Z","updated_at":"2025-10-13T14:24:43.104Z","avatar_url":"https://github.com/stacksjs.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\u003cimg src=\".github/art/cover.jpg\" alt=\"Social Card of this repo\"\u003e\u003c/p\u003e\n\n[![npm version][npm-version-src]][npm-version-href]\n[![GitHub Actions][github-actions-src]][github-actions-href]\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\u003c!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] --\u003e\n\u003c!-- [![Codecov][codecov-src]][codecov-href] --\u003e\n\n# headwind\n\nA 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.\n\n## Features\n\n- ⚡️ **Blazingly Fast** - Built with Bun for exceptional performance (1000+ utilities in \u003c10ms)\n- 🎯 **On-Demand Generation** - Only generates CSS for utilities you actually use\n- 🎨 **Tailwind-Compatible** - Familiar utility classes and syntax\n- 💪 **Fully Typed** - Complete TypeScript support with type-safe configuration\n- 🔧 **Highly Configurable** - Customize theme, colors, spacing, variants, and more\n- 📦 **Zero Runtime Dependencies** - Minimal footprint, maximum performance\n- 🔥 **Hot Reload** - Watch mode for instant rebuilds during development\n- 🎭 **Variant Support** - Responsive, state (hover, focus, etc.), dark mode, and custom variants\n- ✨ **Modern CSS Features** - Grid, Flexbox, animations, transforms, filters, and more\n- 🔨 **Class Compilation** - Optimize HTML by compiling utility groups into single class names\n- 🧪 **Thoroughly Tested** - 860+ tests including comprehensive performance benchmarks\n- 🚀 **Production Ready** - Minification, preflight CSS, and optimized builds\n- ⌨️ **CLI \u0026 API** - Use via command line or programmatic API\n\n## Get Started\n\n### Installation\n\n```bash\nbun add headwind\n# or\nnpm install headwind\n```\n\n### Quick Start\n\n1. **Initialize Headwind**:\n\n```bash\n# Create a config file\nbunx headwind init\n```\n\nThis creates a `headwind.config.ts` file:\n\n```typescript\nimport type { HeadwindOptions } from 'headwind'\n\nexport default {\n  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],\n  output: './dist/headwind.css',\n  minify: false,\n} satisfies HeadwindOptions\n```\n\n2. **Add utility classes to your HTML**:\n\n```html\n\u003cdiv class=\"flex items-center justify-between p-4 bg-blue-500 text-white rounded-lg shadow-md hover:bg-blue-600\"\u003e\n  \u003ch1 class=\"text-2xl font-bold\"\u003eHello Headwind!\u003c/h1\u003e\n\u003c/div\u003e\n```\n\n3. **Build your CSS**:\n\n```bash\n# Build once\nbunx headwind build\n\n# Build and watch for changes\nbunx headwind watch\n\n# Build with options\nbunx headwind build --output ./dist/styles.css --minify\n```\n\n### Programmatic API\n\nYou can also use Headwind programmatically:\n\n```typescript\nimport { build } from 'headwind'\n\nconst result = await build({\n  content: ['./src/**/*.html'],\n  output: './dist/styles.css',\n  minify: true,\n})\n\nconsole.log(`Generated ${result.classes.size} classes in ${result.duration}ms`)\n```\n\n## CLI Commands\n\nHeadwind provides a comprehensive CLI:\n\n```bash\nheadwind build            # Build CSS once\nheadwind watch            # Build and watch for changes\nheadwind init             # Create config file\nheadwind analyze          # Analyze utility class usage\nheadwind clean            # Remove output CSS file\nheadwind preflight        # Generate preflight CSS only\nheadwind --version        # Show version\nheadwind --help           # Show help\n```\n\n## Configuration\n\nHeadwind supports extensive configuration options:\n\n```typescript\nimport type { HeadwindOptions } from 'headwind'\n\nexport default {\n  // Content sources to scan for utility classes\n  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],\n\n  // Output CSS file path\n  output: './dist/styles.css',\n\n  // Minify output CSS\n  minify: false,\n\n  // Enable watch mode\n  watch: false,\n\n  // Enable verbose logging\n  verbose: false,\n\n  // Theme customization\n  theme: {\n    colors: {\n      primary: '#3b82f6',\n      secondary: '#10b981',\n      // ... extend or override default colors\n    },\n    spacing: {\n      // ... customize spacing scale\n    },\n    fontSize: {\n      // ... customize font sizes\n    },\n    // ... and more\n  },\n\n  // Shortcuts (utility aliases)\n  shortcuts: {\n    btn: 'px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600',\n    card: 'p-6 bg-white rounded-lg shadow-md',\n  },\n\n  // Custom variants\n  variants: {\n    // ... configure breakpoints, states, etc.\n  },\n\n  // Safelist (always include these classes)\n  safelist: ['bg-red-500', 'text-green-500'],\n\n  // Blocklist (never include these classes)\n  blocklist: ['debug-*'],\n\n  // Custom rules\n  rules: [],\n\n  // Preflight CSS (normalize/reset styles)\n  preflights: [],\n\n  // Presets\n  presets: [],\n} satisfies HeadwindOptions\n```\n\nFor more configuration options, see the [Configuration Guide](https://headwind.stacksjs.org/config).\n\n## Available Utilities\n\nHeadwind provides a comprehensive set of utility classes compatible with Tailwind CSS:\n\n- **Layout**: display, position, overflow, z-index, etc.\n- **Flexbox \u0026 Grid**: flex, grid, gap, align, justify, etc.\n- **Spacing**: margin, padding with full scale support\n- **Sizing**: width, height, min/max sizes\n- **Typography**: font family, size, weight, line height, text alignment, etc.\n- **Backgrounds**: colors, gradients, images, position, size\n- **Borders**: width, color, radius, style\n- **Effects**: shadow, opacity, blend modes, filters\n- **Transforms**: translate, rotate, scale, skew\n- **Transitions \u0026 Animations**: duration, timing, delay\n- **Interactivity**: cursor, pointer events, user select, scroll behavior\n- **Advanced**: mask utilities, backdrop filters, ring utilities\n\n### Variants\n\n- **Responsive**: `sm:`, `md:`, `lg:`, `xl:`, `2xl:`\n- **State**: `hover:`, `focus:`, `active:`, `disabled:`, `visited:`, `checked:`\n- **Pseudo-elements**: `before:`, `after:`, `placeholder:`, `selection:`\n- **Group/Peer**: `group-hover:`, `peer-focus:`\n- **Dark mode**: `dark:`\n- **Positional**: `first:`, `last:`, `odd:`, `even:`\n- **Important**: `!` prefix (e.g., `!text-red-500`)\n\n### Arbitrary Values\n\nHeadwind supports arbitrary values for maximum flexibility:\n\n```html\n\u003cdiv class=\"w-[500px] h-[calc(100vh-4rem)] bg-[#1da1f2] text-[clamp(1rem,5vw,3rem)]\"\u003e\n  Custom values!\n\u003c/div\u003e\n```\n\n### Compile Class (HTML Optimization)\n\nOptimize your HTML by compiling utility groups into single class names:\n\n```html\n\u003c!-- Before --\u003e\n\u003cdiv class=\":hw: flex items-center justify-between px-4 py-2 bg-white rounded-lg shadow-md\"\u003e\n  Content\n\u003c/div\u003e\n\n\u003c!-- After build --\u003e\n\u003cdiv class=\"hw-2k9d3a\"\u003e\n  Content\n\u003c/div\u003e\n```\n\nThis reduces HTML file size by up to 60%. Learn more in the [Compile Class documentation](https://headwind.stacksjs.org/features/compile-class).\n\n## Testing\n\nHeadwind includes a comprehensive test suite with 860+ tests:\n\n```bash\n# Run all tests\nbun test\n\n# Run specific test files\nbun test test/performance.test.ts\n\n# Run tests in watch mode\nbun test --watch\n```\n\n### Test Coverage\n\n- **Core Functionality**: Parser, generator, scanner, builder\n- **Utilities**: Layout, typography, colors, spacing, grid, flexbox\n- **Variants**: Responsive, state, pseudo-elements, combinations\n- **Advanced Features**: Shortcuts, custom rules, arbitrary values\n- **Performance**: Benchmarks for generation speed and memory efficiency\n- **Edge Cases**: Invalid inputs, complex nesting, duplicate handling\n\n## Performance\n\nHeadwind is designed for speed. Here are some benchmarks from our test suite:\n\n- **Simple utilities**: ~7ms for 1,000 utilities\n- **Complex utilities** (with variants): ~9ms for 1,000 utilities\n- **Arbitrary values**: ~3ms for 1,000 utilities\n- **CSS output**: ~1ms for 1,000 rules\n\nAll benchmarks run on Bun runtime. Your results may vary based on hardware.\n\n## Development\n\nTo contribute to Headwind development:\n\n```bash\n# Clone the repository\ngit clone https://github.com/stacksjs/headwind.git\ncd headwind\n\n# Install dependencies\nbun install\n\n# Run tests\nbun test\n\n# Run tests in watch mode\nbun test --watch\n\n# Run performance benchmarks\nbun test test/performance.test.ts\n\n# Type check\nbun run typecheck\n\n# Build the package\nbun run build\n```\n\n## Documentation\n\nFor comprehensive documentation, visit [headwind.stacksjs.org](https://headwind.stacksjs.org)\n\n- [Installation Guide](https://headwind.stacksjs.org/install)\n- [Usage Guide](https://headwind.stacksjs.org/usage)\n- [Configuration](https://headwind.stacksjs.org/config)\n- [CLI Reference](https://headwind.stacksjs.org/features/cli)\n- [API Reference](https://headwind.stacksjs.org/api-reference)\n\n## Changelog\n\nPlease see our [releases](https://github.com/stacksjs/headwind/releases) page for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.\n\nWe welcome contributions! Whether it's:\n\n- 🐛 Bug reports and fixes\n- ✨ New utility classes or features\n- 📝 Documentation improvements\n- ⚡️ Performance optimizations\n- 🧪 Additional test coverage\n\n## Community\n\nFor help, discussion about best practices, or any other conversation that would benefit from being searchable:\n\n[Discussions on GitHub](https://github.com/stacksjs/headwind/discussions)\n\nFor casual chit-chat with others using this package:\n\n[Join the Stacks Discord Server](https://discord.gg/stacksjs)\n\n## Postcardware\n\n“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.\n\nOur address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎\n\n## Sponsors\n\nWe 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.\n\n- [JetBrains](https://www.jetbrains.com/)\n- [The Solana Foundation](https://solana.com/)\n\n## License\n\nThe MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.\n\nMade with 💙\n\n\u003c!-- Badges --\u003e\n[npm-version-src]: https://img.shields.io/npm/v/headwind?style=flat-square\n[npm-version-href]: https://npmjs.com/package/headwind\n[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/headwind/ci.yml?style=flat-square\u0026branch=main\n[github-actions-href]: https://github.com/stacksjs/headwind/actions?query=workflow%3Aci\n\n\u003c!-- [codecov-src]: https://img.shields.io/codecov/c/gh/stacksjs/headwind/main?style=flat-square\n[codecov-href]: https://codecov.io/gh/stacksjs/headwind --\u003e\n","funding_links":["https://github.com/sponsors/stacksjs","https://github.com/sponsors/chrisbbreuer","https://opencollective.com/stacksjs"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacksjs%2Fheadwind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacksjs%2Fheadwind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacksjs%2Fheadwind/lists"}