"readme": "# React Zero‑UI (Beta)\n\n**Instant UI state updates. ZERO React re‑renders. <1 KB runtime.**\n\nPre‑render your UI once, flip a `data-*` attribute to update — that's it.\n\n<a href=\"https://bundlephobia.com/package/@austinserb/
[email protected]\" target=\"_blank\" rel=\"noopener noreferrer\"><img src=\"https://badgen.net/bundlephobia/min/@austinserb/
[email protected]\" alt=\"npm version\" /> </a><a href=\"https://www.npmjs.com/package/@austinserb/react-zero-ui\" target=\"_blank\" rel=\"noopener noreferrer\"><img src=\"https://img.shields.io/npm/v/@austinserb/react-zero-ui\" alt=\"npm version\" /></a> <a href=\"https://opensource.org/licenses/MIT\" target=\"_blank\" rel=\"noopener noreferrer\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /></a> \n\n---\n\n\n## 📚 Quick Links\n\n- [⚡️ Quick Start](#️-quick-start)\n- [🏄♂️ Usage](#-usage)\n- [🧬 How it works](#-how-it-works)\n- [✅ Features](#-features)\n- [🏗 Best Practices](#-best-practices)\n\n---\n\n## 🚀 Live Demo\n\n| Example | Link | What it shows | Link to Code |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Interactive menu with render tracker | <a href=\"https://react-zero-ui.vercel.app/\" target=\"_blank\" rel=\"noopener noreferrer\"><strong>Main Demo↗</strong></a> | Compare Zero‑UI vs. React side‑by‑side while toggling a menu. | <a href=\"https://github.com/Austin1serb/React-Zero-UI/tree/main/examples/demo\" target=\"_blank\" rel=\"noopener noreferrer\">Github</a> |\n| React benchmark (10 000 nested nodes) | <a href=\"https://react-zero-ui.vercel.app/react\" target=\"_blank\" rel=\"noopener noreferrer\"><strong>React 10k↗</strong></a> | How long the traditional React render path takes. | <a href=\"https://github.com/Austin1serb/React-Zero-UI/tree/main/examples/demo/src/app/react\" target=\"_blank\" rel=\"noopener noreferrer\">Github</a> |\n| Zero‑UI benchmark (10 000 nested nodes) | <a href=\"https://react-zero-ui.vercel.app/zero-ui\" target=\"_blank\" rel=\"noopener noreferrer\"><strong style=\"text-align: nowrap;\">Zero‑UI 10k↗</strong></a> | Identical DOM, but powered by Zero‑UI's `data-*` switch. | <a href=\"https://github.com/Austin1serb/React-Zero-UI/tree/main/examples/demo/src/app/zero-ui\" target=\"_blank\" rel=\"noopener noreferrer\">Github</a> |\n\n---\n\n## 🧐 Why Zero‑UI?\n\nEvery `setState` in React triggers the full VDOM → Diff → Reconciliation → Paint pipeline. For _pure UI state_ (themes, menus, toggles) that work is wasted.\n\n**Zero‑UI introduces \"_PRE‑rendering_\":**\n\n1. Tailwind variants for every state are **generated at build‑time**.\n2. The app **pre‑renders once**.\n3. Runtime state changes only **flip a `data-*` attribute on `<body>`**.\n\nResult → **5-10× faster visual updates** with **ZERO additional bundle cost**.\n\n### 📊 Micro‑benchmarks (Apple M1)\n\n| Nodes updated | React state | Zero‑UI | Speed‑up |\n| ------------- | ----------- | ------- | -------- |\n| 10,000 | \\~50 ms | \\~5 ms | **10×** |\n| 25,000 | \\~180 ms | \\~15 ms | **12×** |\n| 50,000 | \\~300 ms | \\~20 ms | **15×** |\n\nRe‑run these numbers yourself via the links above.\n\n---\n\n## ⚡️ Quick Start\n\n> **Prerequisite:** Tailwind CSS v4 must already be initialized in your project.\n\n```bash\n# Inside an existing *Next.js (App Router)* or *Vite* repo\nnpx create-zero-ui\n```\n\nThat's it — the CLI patch‑installs the required Babel & PostCSS plugins and updates `configs` for you.\n\n### Manual Install\n\n```bash\nnpm install @austinserb/react-zero-ui\n```\n\nThen follow **Setup →** for your bundler.\n\n---\n\n## 🔧 Setup\n\n### Vite\n\n```js\n// vite.config.*\nimport { zeroUIPlugin } from '@austinserb/react-zero-ui/vite';\n\nexport default {\n\t// ❗️Remove the default `tailwindcss()` plugin — Zero‑UI extends it internally\n\tplugins: [zeroUIPlugin()],\n};\n```\n\n### Next.js (App Router)\n\n1. **Spread `bodyAttributes` on `<body>`** in your root layout.\n\n ```tsx\n // app/layout.tsx\n import { bodyAttributes } from '@austinserb/react-zero-ui/attributes';\n // or: import { bodyAttributes } from '../.zero-ui/attributes';\n\n export default function RootLayout({ children }) {\n \treturn (\n \t\t<html lang=\"en\">\n \t\t\t<body {...bodyAttributes}>{children}</body>\n \t\t</html>\n \t);\n }\n ```\n\n2. **Add the PostCSS plugin (must come _before_ Tailwind).**\n\n ```js\n // postcss.config.js\n module.exports = { plugins: { '@austinserb/react-zero-ui/postcss': {}, tailwindcss: {} } };\n ```\n\n---\n\n## 🏄♂️ Usage\n\n\n\n---\n\n## 🛠 API\n\n### `useUI(key, defaultValue)`\n\n```ts\nconst [staleValue, setValue] = useUI<'open' | 'closed'>('sidebar', 'closed');\n```\n\n- `key` → becomes `data-{key}` on `<body>`.\n- `defaultValue` → optional, prevents FOUC.\n- **Note:** the returned `staleValue` does **not** update (`useUI` is write‑only).\n\n### Tailwind variants\n\n```jsx\n<div className=\"sidebar-open:translate-x-0 sidebar-closed:-translate-x-full\" />\n```\n\nAny `data-{key}=\"{value}\"` pair becomes a variant: `{key}-{value}:`.\n\n---\n\n## 🧬 How it works\n\n1. **`useUI`** → writes to `data-*` attributes on `<body>`.\n2. **Babel plugin** → scans code, finds every `key/value`, injects them into **PostCSS**.\n3. **PostCSS plugin** → generates static Tailwind classes **at build‑time**.\n4. **Runtime** → changing state only touches the attribute — no VDOM, no reconciliation, no re‑paint.\n\n---\n\n## ✅ Features\n\n- **Zero React re‑renders** for UI‑only state.\n- **Global setters** — call from any component or util.\n- **Tiny**: < 1 KB gzipped runtime.\n- **TypeScript‑first**.\n- **SSR‑friendly** (Next.js & Vite SSR).\n- **Framework‑agnostic CSS** — generated classes work in plain HTML / Vue / Svelte as well.\n\n---\n\n## 🏗 Best Practices\n\n1. **UI state only** → themes, layout toggles, feature flags.\n2. **Business logic stays in React** → fetching, data mutation, etc.\n3. **Kebab‑case keys** → e.g. `sidebar-open`.\n4. **Provide defaults** to avoid Flash‑Of‑Unstyled‑Content.\n\n---\n\n## 🤝 Contributing\n\nPRs & issues welcome! Please read the [Contributing Guide](CONTRIBUTING.md).\n\n---\n\n## 📜 License\n\n[MIT](LICENSE) © Austin Serb\n\n---\n\nBuilt with ❤️ for the React community. If Zero‑UI makes your app feel ZERO fast, please ⭐️ the repo!\n",
0 commit comments