Compatibility matrix
This page is the canonical “does helixui work with X?” answer. Anything marked tested has an end-to-end fixture in CI; expected means the API surface is compatible but we don’t have a fixture; unsupported means it doesn’t work today.
Last updated: 2026-05-26 against helixui 0.1.0.
Node.js
| Version | Status | Notes |
|---|---|---|
| 20.x (active LTS) | ✅ tested | CI matrix runs every PR. |
| 22.x (active LTS) | ✅ tested | CI matrix runs every PR. |
| 23.x | ⚙️ expected | Should work; not in CI matrix yet. |
| 18.x (maintenance LTS) | ⚙️ expected | We don’t use any 20-only API; should work. |
| 16.x | ❌ unsupported | Below engines: '>=20'. |
| Bun ≥ 1.1 | ⚙️ expected | Runs the harness in dev; not in CI matrix. |
| Deno | ❌ unsupported | Native ESM works but Vite + react-aria-components combos haven’t been verified. |
React
| Version | Status | Notes |
|---|---|---|
| 18.2 | ✅ tested | Peer floor. |
| 18.3 | ✅ tested | Current dev target. |
| 19.0 | ✅ tested | Concurrent features work. forwardRef not yet migrated to ref-as-prop — tracked for v0.2. |
| 17.x | ❌ unsupported | react-aria-components requires React 18+. |
Frontend frameworks
| Framework | Version | Status | Notes |
|---|---|---|---|
| Vite + React | ≥ 5.0 | ✅ tested | The development happy path. |
| Next.js (Pages Router) | 14.x, 15.x | ⚙️ expected | helixui is plain React; no special config needed. |
| Next.js (App Router) | 14.x, 15.x | ✅ tested | Every helixui component is 'use client' — see RSC compat. |
| Remix v2 | 2.x | ⚙️ expected | Browser runtime; helixui imports work. |
| React Router v7 | 7.x | ⚙️ expected | Same as Remix. |
| Astro Islands | 5.x | ✅ tested | Use client:load on helixui imports. |
| TanStack Start | preview | ⚙️ expected | Not personally verified; should work. |
| Gatsby | 5.x | ⚙️ expected | Last verified February 2026. |
| Webpack 5 (vanilla) | — | ⚙️ expected | helixui ships ESM + CJS-friendly exports. |
| Parcel | 2.x | ⚙️ expected | Untested. |
| Bun bundler | 1.1+ | ⚙️ expected | Runtime works; bundler less tested. |
Bundlers
helixui ships ESM. Tree-shaking is enabled across every package; the
sideEffects: ['**/*.css'] directive on components-that-have-CSS
tells bundlers which files to preserve.
| Bundler | Tree-shakes? | Notes |
|---|---|---|
| Vite (rollup) | ✅ | Recommended. |
| Webpack 5 | ✅ | Use mode: 'production'. |
| esbuild | ✅ | |
| Rollup | ✅ | |
| Parcel 2 | ✅ | |
| Turbopack | ⚙️ expected | Untested in CI. |
TypeScript
| Version | Status | Notes |
|---|---|---|
| 5.0+ | ✅ tested | Build target. |
| 4.9 | ⚙️ expected | helixui’s published .d.ts uses satisfies (5.0+) in places; older versions may emit warnings. |
| < 4.9 | ❌ unsupported |
Browsers
helixui targets evergreen browsers (last 2 versions of Chrome, Firefox, Safari, Edge). CSS features it relies on:
| Feature | Min Chrome | Min Firefox | Min Safari |
|---|---|---|---|
| OKLCH colors | 111 | 113 | 15.4 |
color-mix() | 111 | 113 | 16.2 |
:focus-visible | 86 | 85 | 15.4 |
:has() | 105 | 121 | 15.4 |
| Container queries | 105 | 110 | 16.0 |
In practice that puts the floor at Chrome/Edge 121, Firefox 121, Safari 16.4.
Older browsers degrade gracefully — colors fall back to the next defined
value in var(--…, fallback) chains — but the visual fidelity isn’t
guaranteed.
Editors
| Editor | Status | Notes |
|---|---|---|
| VS Code | ✅ tested | .vscode/settings.json ships in-repo — wires spec.md schema + CSS-var autocomplete. |
| Cursor | ✅ tested | .cursorrules template. |
| WebStorm / JetBrains | ⚙️ expected | YAML schema + CSS modules pickup auto. |
| Neovim + LSP | ⚙️ expected | Anyone running tsserver + yaml-language-server is in good shape. |
| Zed | ⚙️ expected | |
| Sublime Text | ⚙️ expected |
AI tools
| Tool | Status | Notes |
|---|---|---|
| Claude Code | ✅ tested | Integration guide. |
| Cursor | ✅ tested | .cursorrules + MCP. |
| GitHub Copilot | ✅ tested | .github/copilot-instructions.md ships. |
| Windsurf | ✅ tested | Integration. |
| Aider | ⚙️ expected | Reads AGENTS.md automatically. |
| Sweep | ⚙️ expected | Reads AGENTS.md. |
| Devin | ⚙️ expected | Reads AGENTS.md. |
Why we don’t list more
Compatibility matrices age fast. Anything in this table needs to be demonstrably running today — we’d rather under-promise. If you’ve verified helixui on a setup not listed, open a PR with a one-line note and we’ll mark it tested.
Reporting a regression
If a previously-tested combo stops working, file an issue tagged
compatibility with:
- Tool / framework / browser version.
- The exact error.
- A minimal repro (CodeSandbox or fork branch).
Compatibility regressions are P0. We treat them like security issues.