create-reactivite 1.4.0 → 1.7.0

package/README.md

@@ -1,290 +1,326 @@
-# create-reactivite
-
-A modern frontend boilerplate generator. On run it asks which template you want, then scaffolds a production-ready app with TypeScript, Tailwind CSS v4 and shadcn/ui pre-wired.
-
-## 🚀 Templates
-
-When you run the CLI you pick one of three templates:
-
-| Template | Stack |
-| --- | --- |
-| **React + Vite** | React 19, Vite 8 (Rolldown), Tailwind v4, shadcn/ui, React Router v7, Recharts |
-| **Next.js 16** | Next.js 16 (App Router), React 19, Tailwind v4, shadcn/ui, i18n, TanStack Query, axios + orval, Zustand, react-hook-form + zod, husky, Vitest + MSW |
-| **Rspack** | React 19 + TypeScript, Rspack bundler (SWC). Minimal starter — grow it yourself. |
-
-```
-$ npx create-reactivite my-app
-
-? Project name: my-app
-? Pick a template: ›
-❯ React + Vite (Tailwind v4, shadcn/ui, React Router)
-  Next.js 16 (App Router, i18n, TanStack Query, orval, Zustand, husky)
-  Rspack (minimal React + TypeScript starter)
-```
-
-## 📦 Installation
-
-### Using npx (Recommended)
-
-```bash
-npx create-reactivite my-app
-cd my-app
-pnpm dev
-```
-
-### Using npm
-
-```bash
-npm create reactivite my-app
-cd my-app
-npm run dev
-```
-
-### Install in current directory
-
-```bash
-npx create-reactivite .
-```
-
-Dependencies install automatically (`pnpm`, falling back to `npm`).
-
-## 🛠️ CLI usage
-
-The CLI runs interactively (prompts) or non-interactively (flags) — flags skip the matching prompt, so it works in scripts and CI.
-
-```
-npx create-reactivite [name] [options]
-```
-
-| Argument / Flag | Alias | Description |
-| --- | --- | --- |
-| `name` | | Project folder. Use `.` to scaffold into the current directory. Omit to be prompted. Must be lowercase letters, digits, `-` `.` `_` `~`. |
-| `--template <name>` | `-t` | `template` · `template2` · `template3`. Omit to be prompted. |
-| `--help` | `-h` | Print usage and exit. |
-| `--version` | `-v` | Print version and exit. |
-
-```bash
-# fully non-interactive (no prompts)
-npx create-reactivite my-app --template template2
-npx create-reactivite my-app -t template3
-
-npx create-reactivite --help
-npx create-reactivite --version
-```
-
-After copying the template the CLI sets `name` in the new `package.json`, removes any bundled lockfile (fresh resolve), runs `git init`, then installs dependencies.
-
----
-
-## ⚛️ Template 1 — React + Vite
-
-### Features
-
-- **⚡ Vite 8** — Lightning-fast build tool and dev server (Rolldown bundler)
-- **⚛️ React 19** — Latest React with modern features
-- **📘 TypeScript 6** — Full TypeScript with strict configuration
-- **🎨 Tailwind CSS v4** — Config-less, CSS-variable driven theme
-- **🧩 shadcn/ui** — Beautiful, accessible UI components (new-york)
-- **🧭 React Router v7** — Client-side routing with `createBrowserRouter`
-- **📊 Recharts** — Composable charts for the admin dashboard
-- **🌙 Dark Mode** — Built-in theme switching
-- **🔔 Toasts** — Sonner notifications
-- **🎯 ESLint** — Modern flat config
-
-### Scripts
-
-- `pnpm dev` — dev server (port 5173)
-- `pnpm build` — `tsc -b && vite build`
-- `pnpm preview` — serve the production build
-- `pnpm lint` — ESLint
-
-### Structure
-
-```
-my-app/
-├── public/
-├── src/
-│   ├── components/
-│   │   ├── ui/                    # shadcn/ui components
-│   │   ├── home-page-components/
-│   │   └── admin-page-components/
-│   ├── lib/utils.ts
-│   ├── pages/
-│   │   ├── Homepage/
-│   │   └── Dashboard/
-│   ├── App.tsx                   # createBrowserRouter route shell
-│   ├── main.tsx
-│   └── global.css
-├── components.json
-├── vite.config.ts
-└── eslint.config.js
-```
-
-### Routing
-
-Routes live in `App.tsx` via `createBrowserRouter` from **react-router** v7 (not `react-router-dom`):
-
-```typescript
-import { createBrowserRouter } from "react-router"
-
-const router = createBrowserRouter([
-  { path: "/", element: <Homepage /> },
-  { path: "/dashboard", element: <Dashboard /> },
-])
-```
-
----
-
-## ▲ Template 2 — Next.js 16
-
-A locale-scoped App Router boilerplate with a full data layer and tooling.
-
-### Features
-
-- **▲ Next.js 16** — App Router, `output: "standalone"`
-- **🌍 i18n** — `app/[locale]` routing, lightweight `TranslationProvider` + `locales/*.json`
-- **🔁 TanStack Query** — `QueryClientProvider` + Devtools
-- **🔌 axios + orval** — typed API hooks generated from your OpenAPI schema
-- **🐻 Zustand** — state stores (persisted `user-store`)
-- **📝 react-hook-form + zod** — typed forms
-- **🧪 Vitest + MSW** — unit tests with mocked network
-- **🐶 husky** — pre-commit: lint + format + tests
-- **🎨 Tailwind v4 + shadcn/ui**
-
-### Scripts
-
-- `pnpm dev` — dev server (port 3000, redirects `/` → `/az`)
-- `pnpm build` — `next build`
-- `pnpm test` / `pnpm test:run` — Vitest
-- `pnpm generate:api` — orval codegen into `services/generated/`
-- `pnpm lint` / `pnpm format`
-
-### Structure
-
-```
-my-app/
-├── app/
-│   ├── layout.tsx              # root passthrough
-│   ├── page.tsx                # redirects to /{DEFAULT_LOCALE}
-│   ├── globals.css
-│   ├── api/clear-session/
-│   └── [locale]/
-│       ├── layout.tsx          # html/body shell + providers
-│       ├── locales.ts          # server-only dictionary loader
-│       ├── page.tsx            # Home
-│       ├── (public)/login/
-│       └── (private)/dashboard/
-├── components/ui/              # shadcn/ui
-├── config/                     # env + constants (LOCALES)
-├── contexts/                   # translation-context
-├── hoc/                        # QueryProvider
-├── lib/                        # utils, paramsSerializer
-├── services/
-│   ├── httpClient/             # axios + orval mutator
-│   └── generated/              # orval output
-├── store/                      # zustand
-├── locales/                    # az.json, en.json
-├── testing/msw/
-└── orval.config.ts
-```
-
-### API codegen (orval)
-
-1. Point `orval.config.ts` `input.target` at your OpenAPI schema (or set `OPENAPI_TARGET`).
-2. `pnpm generate:api` → writes react-query hooks + models to `services/generated/`.
-
-> The `@/` path alias maps to the **project root** in this template (not `src/`).
-
----
-
-## 🦀 Template 3 — Rspack (minimal)
-
-A deliberately bare **React + TypeScript** starter on [Rspack](https://rspack.dev/) (Rust-based bundler, built-in SWC). No router, no UI kit — a clean base to build on.
-
-### Scripts
-
-- `pnpm dev` — dev server (port 5174)
-- `pnpm build` — production build → `dist/`
-- `pnpm preview` — serve the production build
-
-### Structure
-
-```
-my-app/
-├── index.html
-├── rspack.config.mjs       # entry, swc loader, html plugin, native CSS
-├── tsconfig.json
-└── src/
-    ├── main.tsx
-    ├── App.tsx
-    ├── index.css
-    └── components/author-credit.tsx
-```
-
----
-
-## 👤 Author
-
-Every template renders a small credit linking to the author. Built by **Javid Salimov** —
-[GitHub](https://github.com/javidselimov) ·
-[LinkedIn](https://www.linkedin.com/in/javidsalim/) ·
-[npm](https://www.npmjs.com/~ubuligan).
-
----
-
-## 🎨 Adding shadcn/ui Components
-
-The React + Vite and Next.js templates use shadcn/ui (new-york, lucide icons):
-
-```bash
-npx shadcn@latest add button
-npx shadcn@latest add form
-```
-
-## 🔄 Maintaining template versions
-
-This repo ships a Claude Code skill that bumps every template's dependencies to their latest published versions in one shot — useful when keeping the scaffolds current.
-
-```
-/update-template-deps
-```
-
-It runs `npm-check-updates` inside `template/`, `template2/` and `template3/`, rewrites each `package.json` to the latest, and reports what changed — flagging **major** bumps that need a build check. The generator's own root `package.json` is left untouched.
-
-You can also run the helper directly:
-
-```bash
-# all templates, latest (includes majors)
-node .claude/skills/update-template-deps/update-deps.mjs
-
-# safe — no major bumps
-node .claude/skills/update-template-deps/update-deps.mjs --target minor
-
-# a single template
-node .claude/skills/update-template-deps/update-deps.mjs --template template2
-```
-
-After a major bump, verify the affected template still builds before publishing:
-
-```bash
-cd template2 && pnpm install && pnpm build
-```
-
-## 🤝 Contributing
-
-Contributions welcome — open a PR.
-
-## 📄 License
-
-MIT
-
-## 🔗 Links
-
-- [React](https://react.dev/) · [Next.js](https://nextjs.org/) · [Vite](https://vite.dev/) · [Rspack](https://rspack.dev/)
-- [Tailwind CSS](https://tailwindcss.com/) · [shadcn/ui](https://ui.shadcn.com/)
-- [React Router](https://reactrouter.com/) · [TanStack Query](https://tanstack.com/query) · [orval](https://orval.dev/)
-- [Zustand](https://zustand.docs.pmnd.rs/) · [Recharts](https://recharts.org/) · [TypeScript](https://www.typescriptlang.org/)
-
----
-
-**Happy coding! 🎉**
+# create-reactivite
+
+A modern frontend boilerplate generator. On run it asks which template you want, then scaffolds a production-ready app with TypeScript, Tailwind CSS v4 and shadcn/ui pre-wired.
+
+## 🚀 Templates
+
+When you run the CLI you pick one of three templates:
+
+| Template | Stack |
+| --- | --- |
+| **React + Vite** | React 19, Vite 8 (Rolldown), Tailwind v4, shadcn/ui, React Router v8, Recharts |
+| **Next.js 16** | Next.js 16 (App Router), React 19, Tailwind v4, shadcn/ui, i18n, TanStack Query, axios + orval, Zustand, react-hook-form + zod, husky, Vitest + MSW |
+| **Rspack** | React 19 + TypeScript, Rspack bundler (SWC), Tailwind v4, shadcn/ui, React Router v7, Matrix/terminal theme |
+
+```
+$ npx create-reactivite my-app
+
+? Project name: my-app
+? Pick a template: ›
+❯ React + Vite (Tailwind v4, shadcn/ui, React Router)
+  Next.js 16 (App Router, i18n, TanStack Query, orval, Zustand, husky)
+  Rspack (Tailwind v4, shadcn/ui, React Router, Matrix theme)
+```
+
+## 📦 Installation
+
+### Using npx (Recommended)
+
+```bash
+npx create-reactivite my-app
+cd my-app
+pnpm dev
+```
+
+### Using npm
+
+```bash
+npm create reactivite my-app
+cd my-app
+npm run dev
+```
+
+### Install in current directory
+
+```bash
+npx create-reactivite .
+```
+
+Dependencies install automatically (`pnpm`, falling back to `npm`).
+
+## 🛠️ CLI usage
+
+The CLI runs interactively (prompts) or non-interactively (flags) — flags skip the matching prompt, so it works in scripts and CI.
+
+```
+npx create-reactivite [name] [options]
+```
+
+| Argument / Flag | Alias | Description |
+| --- | --- | --- |
+| `name` | | Project folder. Use `.` to scaffold into the current directory. Omit to be prompted. Must be lowercase letters, digits, `-` `.` `_` `~`. |
+| `--template <name>` | `-t` | `template` · `template2` · `template3`. Omit to be prompted. |
+| `--help` | `-h` | Print usage and exit. |
+| `--version` | `-v` | Print version and exit. |
+
+```bash
+# fully non-interactive (no prompts)
+npx create-reactivite my-app --template template2
+npx create-reactivite my-app -t template3
+
+npx create-reactivite --help
+npx create-reactivite --version
+```
+
+After copying the template the CLI sets `name` in the new `package.json`, removes any bundled lockfile (fresh resolve), runs `git init`, then installs dependencies.
+
+---
+
+## ⚛️ Template 1 — React + Vite
+
+### Features
+
+- **⚡ Vite 8** — Lightning-fast build tool and dev server (Rolldown bundler)
+- **⚛️ React 19** — Latest React with modern features
+- **📘 TypeScript 6** — Full TypeScript with strict configuration
+- **🎨 Tailwind CSS v4** — Config-less, CSS-variable driven theme
+- **🧩 shadcn/ui** — Beautiful, accessible UI components (new-york)
+- **🧭 React Router v8** — Client-side routing with `createBrowserRouter`
+- **📊 Recharts** — Composable charts for the admin dashboard
+- **🌙 Dark Mode** — Built-in theme switching
+- **🔔 Toasts** — Sonner notifications
+- **🎯 ESLint** — Modern flat config
+
+### Scripts
+
+- `pnpm dev` — dev server (port 5173)
+- `pnpm build` — `tsc -b && vite build`
+- `pnpm preview` — serve the production build
+- `pnpm lint` — ESLint
+
+### Structure
+
+```
+my-app/
+├── public/
+├── src/
+│   ├── components/
+│   │   ├── ui/                    # shadcn/ui components
+│   │   ├── home-page-components/
+│   │   └── admin-page-components/
+│   ├── lib/utils.ts
+│   ├── pages/
+│   │   ├── Homepage/
+│   │   └── Dashboard/
+│   ├── App.tsx                   # createBrowserRouter route shell
+│   ├── main.tsx
+│   └── global.css
+├── components.json
+├── vite.config.ts
+└── eslint.config.js
+```
+
+### Routing
+
+Routes live in `App.tsx` via `createBrowserRouter` from **react-router** v8 (not `react-router-dom`):
+
+```typescript
+import { createBrowserRouter } from "react-router"
+
+const router = createBrowserRouter([
+  { path: "/", element: <Homepage /> },
+  { path: "/dashboard", element: <Dashboard /> },
+])
+```
+
+---
+
+## ▲ Template 2 — Next.js 16
+
+A locale-scoped App Router boilerplate with a full data layer and tooling.
+
+### Features
+
+- **▲ Next.js 16** — App Router, `output: "standalone"`
+- **🌍 i18n** — `app/[locale]` routing, lightweight `TranslationProvider` + `locales/*.json`
+- **🔁 TanStack Query** — `QueryClientProvider` + Devtools
+- **🔌 axios + orval** — typed API hooks generated from your OpenAPI schema
+- **🐻 Zustand** — state stores (persisted `user-store`)
+- **📝 react-hook-form + zod** — typed forms
+- **🧪 Vitest + MSW** — unit tests with mocked network
+- **🐶 husky** — pre-commit: lint + format + tests
+- **🎨 Tailwind v4 + shadcn/ui**
+
+### Scripts
+
+- `pnpm dev` — dev server (port 3000, redirects `/` → `/az`)
+- `pnpm build` — `next build`
+- `pnpm test` / `pnpm test:run` — Vitest
+- `pnpm generate:api` — orval codegen into `services/generated/`
+- `pnpm lint` / `pnpm format`
+
+### Structure
+
+```
+my-app/
+├── app/
+│   ├── layout.tsx              # root passthrough
+│   ├── page.tsx                # redirects to /{DEFAULT_LOCALE}
+│   ├── globals.css
+│   ├── api/clear-session/
+│   └── [locale]/
+│       ├── layout.tsx          # html/body shell + providers
+│       ├── locales.ts          # server-only dictionary loader
+│       ├── page.tsx            # Home
+│       ├── (public)/login/
+│       └── (private)/dashboard/
+├── components/ui/              # shadcn/ui
+├── config/                     # env + constants (LOCALES)
+├── contexts/                   # translation-context
+├── hoc/                        # QueryProvider
+├── lib/                        # utils, paramsSerializer
+├── services/
+│   ├── httpClient/             # axios + orval mutator
+│   └── generated/              # orval output
+├── store/                      # zustand
+├── locales/                    # az.json, en.json
+├── testing/msw/
+└── orval.config.ts
+```
+
+### API codegen (orval)
+
+1. Point `orval.config.ts` `input.target` at your OpenAPI schema (or set `OPENAPI_TARGET`).
+2. `pnpm generate:api` → writes react-query hooks + models to `services/generated/`.
+
+> The `@/` path alias maps to the **project root** in this template (not `src/`).
+
+---
+
+## 🦀 Template 3 — Rspack
+
+A **React 19 + TypeScript** app on [Rspack](https://rspack.dev/) (Rust-based bundler, built-in SWC), themed as a Matrix/terminal hacker UI (canvas glyph rain, scanlines, neon glow, Orbitron / Share Tech Mono fonts).
+
+### Features
+
+- **🦀 Rspack** — fast Rust bundler with built-in SWC
+- **⚛️ React 19 + TypeScript 6**
+- **🎨 Tailwind v4** — via PostCSS (`@tailwindcss/postcss` + `postcss-loader`), not the Vite plugin
+- **🧩 shadcn/ui** — full new-york component set vendored in `src/components/ui/`
+- **🧭 React Router v7** — `react-router-dom` component API (`BrowserRouter`/`Routes`/`Route`)
+- **🌧️ Matrix theme** — `MatrixRain` canvas, scanlines, `text-glow`; forced dark mode
+
+### Scripts
+
+- `pnpm dev` — dev server (port 5174)
+- `pnpm build` — production build → `dist/`
+- `pnpm preview` — serve the production build
+
+### Structure
+
+```
+my-app/
+├── index.html              # <html class="dark">, Google Fonts
+├── rspack.config.mjs       # entry, swc loader, postcss-loader, @/ alias
+├── postcss.config.mjs      # @tailwindcss/postcss
+├── components.json         # shadcn config (css → src/index.css)
+├── tsconfig.json           # @/ → src/
+└── src/
+    ├── main.tsx
+    ├── App.tsx             # <Routes> route shell
+    ├── index.css           # tailwind + oklch theme + effects
+    ├── lib/utils.ts
+    ├── hooks/use-mobile.ts
+    ├── pages/              # home.tsx, about.tsx, contact.tsx
+    └── components/
+        ├── ui/             # shadcn/ui
+        ├── layout.tsx      # nav + Outlet + MatrixRain + AuthorCredit
+        ├── matrix-rain.tsx
+        └── author-credit.tsx
+```
+
+### Routing
+
+Routes live in `App.tsx` via the **`react-router-dom`** v7 component API (not the `createBrowserRouter` data router used by Template 1):
+
+```tsx
+import { BrowserRouter, Route, Routes } from "react-router-dom"
+
+<BrowserRouter>
+  <Routes>
+    <Route element={<Layout />}>
+      <Route index element={<Home />} />
+      <Route path="about" element={<About />} />
+      <Route path="contact" element={<Contact />} />
+    </Route>
+  </Routes>
+</BrowserRouter>
+```
+
+---
+
+## 👤 Author
+
+Every template renders a small credit linking to the author. Built by **Javid Salimov** —
+[GitHub](https://github.com/javidselimov) ·
+[LinkedIn](https://www.linkedin.com/in/javidsalim/) ·
+[npm](https://www.npmjs.com/~ubuligan).
+
+---
+
+## 🎨 Adding shadcn/ui Components
+
+All three templates use shadcn/ui (new-york, lucide icons):
+
+```bash
+npx shadcn@latest add button
+npx shadcn@latest add form
+```
+
+## 🔄 Maintaining template versions
+
+This repo ships a Claude Code skill that bumps every template's dependencies to their latest published versions in one shot — useful when keeping the scaffolds current.
+
+```
+/update-template-deps
+```
+
+It runs `npm-check-updates` inside `template/`, `template2/` and `template3/`, rewrites each `package.json` to the latest, and reports what changed — flagging **major** bumps that need a build check. The generator's own root `package.json` is left untouched.
+
+You can also run the helper directly:
+
+```bash
+# all templates, latest (includes majors)
+node .claude/skills/update-template-deps/update-deps.mjs
+
+# safe — no major bumps
+node .claude/skills/update-template-deps/update-deps.mjs --target minor
+
+# a single template
+node .claude/skills/update-template-deps/update-deps.mjs --template template2
+```
+
+After a major bump, verify the affected template still builds before publishing:
+
+```bash
+cd template2 && pnpm install && pnpm build
+```
+
+## 🤝 Contributing
+
+Contributions welcome — open a PR.
+
+## 📄 License
+
+MIT
+
+## 🔗 Links
+
+- [React](https://react.dev/) · [Next.js](https://nextjs.org/) · [Vite](https://vite.dev/) · [Rspack](https://rspack.dev/)
+- [Tailwind CSS](https://tailwindcss.com/) · [shadcn/ui](https://ui.shadcn.com/)
+- [React Router](https://reactrouter.com/) · [TanStack Query](https://tanstack.com/query) · [orval](https://orval.dev/)
+- [Zustand](https://zustand.docs.pmnd.rs/) · [Recharts](https://recharts.org/) · [TypeScript](https://www.typescriptlang.org/)
+
+---
+
+**Happy coding! 🎉**