doo-boilerplate 0.1.1 → 0.1.3

package/dist/index.js

@@ -28,7 +28,7 @@ function validateProjectName(name) {
 async function collectOptions(defaults, isTTY2 = true) {
   if (!isTTY2) {
     const valid = ["editor", "charts", "dnd", "sentry"];
-    const validPMs2 = ["npm", "yarn", "pnpm", "bun", "deno"];
+    const validPMs2 = ["pnpm", "bun", "yarn"];
     const projectName2 = defaults.projectName ?? "my-portal";
     const framework2 = defaults.framework === "nextjs" || defaults.framework === "vite" ? defaults.framework : "vite";
     const packageManager2 = validPMs2.includes(defaults.pm) ? defaults.pm : "pnpm";
@@ -64,8 +64,8 @@ async function collectOptions(defaults, isTTY2 = true) {
     const answer = await p.select({
       message: "Framework",
       options: [
-        { value: "nextjs", label: "Next.js 16", hint: "SSR \xB7 App Router \xB7 i18n-ready" },
-        { value: "vite", label: "Vite 7", hint: "SPA \xB7 faster builds \xB7 TanStack Router" }
+        { value: "vite", label: "Vite 8", hint: "SPA \xB7 faster builds \xB7 TanStack Router" },
+        { value: "nextjs", label: "Next.js 16", hint: "SSR \xB7 App Router \xB7 i18n-ready" }
       ]
     });
     if (p.isCancel(answer)) {
@@ -74,7 +74,7 @@ async function collectOptions(defaults, isTTY2 = true) {
     }
     framework = answer;
   }
-  const validPMs = ["npm", "yarn", "pnpm", "bun", "deno"];
+  const validPMs = ["pnpm", "bun", "yarn"];
   let packageManager;
   if (validPMs.includes(defaults.pm)) {
     packageManager = defaults.pm;
@@ -82,11 +82,9 @@ async function collectOptions(defaults, isTTY2 = true) {
     const answer = await p.select({
       message: "Package manager",
       options: [
-        { value: "npm", label: "npm", hint: "Node package manager" },
-        { value: "yarn", label: "yarn", hint: "Fast, reliable" },
-        { value: "pnpm", label: "pnpm", hint: "Efficient disk usage" },
-        { value: "bun", label: "bun", hint: "All-in-one runtime" },
-        { value: "deno", label: "deno", hint: "Secure by default" }
+        { value: "pnpm", label: "pnpm", hint: "recommended \xB7 efficient disk usage" },
+        { value: "bun", label: "bun", hint: "fastest \xB7 all-in-one runtime" },
+        { value: "yarn", label: "yarn", hint: "reliable \xB7 stable" }
       ]
     });
     if (p.isCancel(answer)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doo-boilerplate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI to scaffold Pila portal frontend projects",
   "type": "module",
   "bin": {

package/templates/template-nextjs/README.md

@@ -1,215 +1,297 @@
 # {{PROJECT_NAME}}
 
-> Next.js 16 server-side rendered portal frontend
-
-Production-ready Next.js 16 application with App Router, i18n, dark mode, authentication, and DevOps integration.
+> Next.js 16 SSR portal — scaffolded by [doo-boilerplate](https://www.npmjs.com/package/doo-boilerplate)
 
 ## Quick Start
 
 ```bash
-pnpm dev
+cp .env.example .env   # configure API URLs
+pnpm dev               # http://localhost:3000
 ```
 
-Open [http://localhost:3000](http://localhost:3000) in your browser.
+---
 
-## Available Scripts
+## Scripts
 
 | Command | Purpose |
 |---------|---------|
-| `pnpm dev` | Start dev server with Turbopack |
-| `pnpm build` | Build for production |
+| `pnpm dev` | Dev server with Turbopack |
+| `pnpm build` | Production build |
 | `pnpm start` | Run production server |
-| `pnpm lint` | Run ESLint |
-| `pnpm lint:fix` | Fix linting issues |
-| `pnpm type-check` | TypeScript type checking |
-| `pnpm format` | Format code with Prettier |
-| `pnpm format:check` | Check formatting without changes |
-| `pnpm knip` | Find unused files/exports |
-| `pnpm gen:api` | Generate types from Swagger spec |
-| `pnpm gen:api:watch` | Watch mode for API generation |
-| `pnpm docker:build` | Build & scan Docker image |
-| `pnpm docker:scan` | Security scan image with Trivy |
-
-## Tech Stack
-
-- **Framework:** Next.js 16 with App Router
-- **Styling:** Tailwind CSS 4 + Shadcn/ui
-- **i18n:** next-intl (EN/VI built-in)
-- **State:** Zustand 5 (global) + TanStack Query 5 (server)
-- **Forms:** React Hook Form + Zod
-- **HTTP:** Axios with JWT interceptors
-- **Auth:** JWT store with refresh token persistence
-- **DevOps:** Docker (multi-stage) + Trivy security scan
-
-## Environment Variables
-
-Copy `.env.example` to `.env`:
+| `pnpm lint` / `lint:fix` | ESLint |
+| `pnpm type-check` | TypeScript |
+| `pnpm format` | Prettier |
+| `pnpm knip` | Find unused code |
+| `pnpm gen:api` | Generate types from `docs/swagger/api.json` |
+| `pnpm gen:api:watch` | Watch mode |
+| `pnpm docker:build` | Build image + Trivy security scan |
+| `pnpm docker:scan` | Scan existing image |
 
-```bash
-cp .env.example .env
-```
-
-Key variables:
-
-```env
-# API Configuration
-NEXT_PUBLIC_API_URL=http://localhost:8000
-NEXT_PUBLIC_API_AUTH_URL=http://localhost:8001
-
-# App
-NEXT_PUBLIC_APP_URL=http://localhost:3000
-NEXT_PUBLIC_APP_NAME={{PROJECT_NAME}}
-```
+---
 
-## Project Structure
+## Folder Structure
 
 ```
 src/
-├── app/
-│   ├── (auth)/              # Auth layout group (login, register)
-│   ├── (dashboard)/         # Protected layout group
-│   ├── layout.tsx           # Root layout
-│   └── page.tsx             # Homepage
+├── app/                            # Next.js App Router (pages + layouts)
+│   ├── (auth)/                     # Unauthenticated route group
+│   │   ├── layout.tsx              # Minimal layout (no sidebar)
+│   │   └── sign-in/page.tsx
+│   ├── (dashboard)/                # Protected route group
+│   │   ├── layout.tsx              # Full layout: sidebar + header
+│   │   ├── page.tsx                # /dashboard
+│   │   ├── profile/page.tsx        # /profile
+│   │   └── settings/page.tsx       # /settings
+│   ├── api/health/route.ts         # Health check: GET /api/health
+│   ├── layout.tsx                  # Root: fonts, providers, html lang
+│   └── not-found.tsx               # 404 page
+│
 ├── components/
-│   ├── ui/                  # Shadcn/ui components
-│   └── **/                  # Feature-specific components
-├── features/
-│   ├── auth/
-│   │   ├── hooks/
-│   │   ├── stores/          # Zustand auth store
-│   │   ├── services/
-│   │   │   └── gen/         # Generated API types (gen:api)
-│   │   └── types/
-│   └── **/
-├── hooks/                   # Custom React hooks
+│   ├── ui/                         # Shadcn/ui primitives — DO NOT EDIT
+│   │   └── button, card, dialog, form, input, select, ...
+│   ├── common/                     # Shared app-wide components
+│   │   ├── error-boundary.tsx
+│   │   ├── loading-spinner.tsx
+│   │   └── theme-toggle.tsx        # Dark/light/system toggle
+│   └── layout/                     # Page chrome
+│       ├── sidebar.tsx             # Collapsible nav sidebar
+│       ├── header.tsx              # Top bar with user menu
+│       └── page-layout.tsx         # Wrapper: sidebar + main content
+│
+├── features/                       # Domain modules (feature-first)
+│   └── auth/
+│       ├── components/
+│       │   └── sign-in-form.tsx
+│       ├── hooks/
+│       │   └── use-auth.ts         # useSignIn, useSignOut, useCurrentUser
+│       ├── schemas/
+│       │   └── auth-schema.ts      # Zod: LoginSchema, RegisterSchema
+│       └── services/
+│           ├── auth-api.ts         # API calls: login, logout, me
+│           └── gen/                # Auto-generated types (pnpm gen:api)
+│
+├── hooks/                          # Shared custom hooks
+│   └── use-media-query.ts
+│
 ├── i18n/
-│   ├── request.ts           # Server-side i18n setup
-│   ├── routing.ts           # Route configuration
-│   └── translations/        # Message files
-├── lib/
-│   ├── cn.ts                # Tailwind merge utility
-│   ├── http.ts              # Axios instance
-│   └── **/
-├── middleware.ts            # next-intl middleware
+│   └── config.ts                   # locales: ['en', 'vi'], defaultLocale: 'en'
+│
+├── lib/                            # Utilities & singletons
+│   ├── api-client.ts               # Axios instance (auto Bearer token + 401 handler)
+│   ├── query-client.ts             # TanStack Query client config
+│   └── utils.ts                    # cn() = clsx + tailwind-merge
+│
+├── middleware.ts                    # next-intl routing (locale prefix)
+│
 ├── providers/
-│   ├── ClientProvider.tsx    # Client-side providers
-│   └── ThemeProvider.tsx     # next-themes setup
-├── stores/                  # Zustand stores
+│   ├── app-providers.tsx           # Compose all providers here
+│   ├── query-provider.tsx          # <QueryClientProvider>
+│   └── theme-provider.tsx          # <ThemeProvider> (next-themes)
+│
+├── stores/
+│   └── auth-store.ts               # Zustand auth (persisted to localStorage)
+│
 ├── styles/
-│   ├── globals.css
-│   └── variables.css        # CSS variables
+│   └── globals.css                 # @import tailwindcss + CSS variables
+│
 └── types/
-    └── index.ts
+    └── index.ts                    # Shared TS types (ApiError, PaginatedResponse, etc.)
 ```
 
-## API Code Generation
+---
 
-Generate TypeScript types from backend Swagger spec:
+## Design Patterns
 
-```bash
-# Place spec at docs/swagger/api.json
-curl https://api.example.com/swagger.json > docs/swagger/api.json
+### Feature-First Modules
 
-# Generate types
-pnpm gen:api
+Add new domain logic as a feature module:
 
-# Watch mode during API development
-pnpm gen:api:watch
+```
+features/users/
+├── components/user-table.tsx
+├── hooks/use-users.ts          ← TanStack Query hooks
+├── schemas/user-schema.ts      ← Zod validation
+└── services/
+    ├── users-api.ts            ← API calls
+    └── gen/                    ← Generated types (optional)
 ```
 
-Generated types appear in `src/features/auth/services/gen/`.
+### State Layers
 
-## Docker Deployment
+| State type | Tool | Location |
+|-----------|------|----------|
+| Server / async data | TanStack Query | `features/{x}/hooks/` |
+| Global client state | Zustand | `src/stores/` |
+| Form state | React Hook Form | component-local |
+| URL / route params | `useSearchParams` | component-local |
 
-### Build & Scan
+**Rule:** Never put fetched data in Zustand. Only put truly global client state (auth, UI prefs) in stores.
 
-```bash
-pnpm docker:build
-```
+### Auth Store
 
-Builds optimized multi-stage image and scans for vulnerabilities with Trivy.
+```ts
+import { useAuthStore } from '@/stores/auth-store'
 
-### Local Development
+// Read
+const { user, isAuthenticated } = useAuthStore()
 
-```bash
-docker-compose up
-# App runs on http://localhost:3000
+// RBAC
+const isAdmin = useAuthStore(s => s.hasRole('admin'))
+const canPublish = useAuthStore(s => s.hasPermission('publish:articles'))
+
+// Mutations
+const { login, logout } = useAuthStore()
 ```
 
-Environment variables read from `.env` file.
+Persisted fields: `user`, `accessToken`, `refreshToken`, `isAuthenticated`.
 
-### Production Build
+### API Client
 
-```bash
-docker build -t my-app:latest \
-  --build-arg NEXT_PUBLIC_API_URL=https://api.example.com .
+```ts
+// All features use the shared client from lib/api-client.ts
+import apiClient from '@/lib/api-client'
 
-docker run -p 3000:3000 \
-  -e NEXT_PUBLIC_API_URL=https://api.example.com \
-  my-app:latest
+// features/users/services/users-api.ts
+export const usersApi = {
+  list: (params?: ListParams) =>
+    apiClient.get<User[]>('/users', { params }).then(r => r.data),
+  create: (data: CreateUserDto) =>
+    apiClient.post<User>('/users', data).then(r => r.data),
+  update: (id: string, data: UpdateUserDto) =>
+    apiClient.patch<User>(`/users/${id}`, data).then(r => r.data),
+}
 ```
 
-## Next.js App Router Basics
+The client auto-injects `Authorization: Bearer <token>` and clears auth + redirects to `/sign-in` on 401.
 
-### Routing
+### TanStack Query Hooks
 
-Routes defined by file structure in `src/app/`:
+```ts
+// features/users/hooks/use-users.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { usersApi } from '../services/users-api'
 
-```
-app/
-├── page.tsx           → /
-├── about/
-│   └── page.tsx       → /about
-└── (auth)/
-    ├── login/
-    │   └── page.tsx   → /login
-    └── register/
-        └── page.tsx   → /register
+export function useUsers(params?: ListParams) {
+  return useQuery({
+    queryKey: ['users', params],
+    queryFn: () => usersApi.list(params),
+    staleTime: 5 * 60_000,
+  })
+}
+
+export function useCreateUser() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: usersApi.create,
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['users'] }),
+  })
+}
 ```
 
-Parentheses `(auth)` create layout groups without affecting URL.
+### Form Pattern
 
-### Server & Client Components
+```ts
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
 
-By default, all components are **Server Components** (run on server):
+const schema = z.object({ name: z.string().min(2) })
+type Values = z.infer<typeof schema>
 
-```typescript
-// src/app/page.tsx (Server Component)
-export default function Home() {
-  return <h1>SSR rendered on server</h1>
+function CreateUserForm() {
+  const form = useForm<Values>({ resolver: zodResolver(schema) })
+  const { mutate, isPending } = useCreateUser()
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(data => mutate(data))}>
+        <FormField control={form.control} name="name" render={...} />
+        <Button disabled={isPending}>Create</Button>
+      </form>
+    </Form>
+  )
 }
 ```
 
-For client-side logic, add `'use client'`:
+### Protected Routes
 
-```typescript
-// src/components/Counter.tsx (Client Component)
-'use client'
+Route groups handle protection at the layout level:
 
-import { useState } from 'react'
+```ts
+// app/(dashboard)/layout.tsx
+import { redirect } from 'next/navigation'
+import { getAuthFromCookies } from '@/lib/auth-server'
 
-export function Counter() {
-  const [count, setCount] = useState(0)
-  return <button onClick={() => setCount(count + 1)}>{count}</button>
+export default async function DashboardLayout({ children }) {
+  const auth = await getAuthFromCookies()
+  if (!auth?.isAuthenticated) redirect('/sign-in')
+  return <PageLayout>{children}</PageLayout>
 }
 ```
 
-### Layouts
+### Internationalization
 
-Create shared layouts for route groups:
+```ts
+// Server Component
+import { getTranslations } from 'next-intl/server'
+const t = await getTranslations('dashboard')
 
-```typescript
-// src/app/(dashboard)/layout.tsx
-export default function DashboardLayout({ children }) {
-  return (
-    <div>
-      <nav>Sidebar</nav>
-      <main>{children}</main>
-    </div>
-  )
-}
+// Client Component ('use client')
+import { useTranslations } from 'next-intl'
+const t = useTranslations('dashboard')
+
+t('welcome')         // → "Welcome" / "Chào mừng"
+t('items', { n: 5 }) // with interpolation
 ```
 
+Add translations in `messages/en.json` and `messages/vi.json`.
+
+---
+
+## API Type Generation
+
+```bash
+# 1. Place your backend OpenAPI spec
+curl https://api.example.com/swagger.json > docs/swagger/api.json
+
+# 2. Generate TypeScript types
+pnpm gen:api
+
+# 3. Import generated types
+import type { LoginRequest } from '@/features/auth/services/gen'
+```
+
+To generate types for a different feature, update the `-o` path in `package.json`:
+
+```json
+"gen:api": "swagger-typescript-api -p ./docs/swagger/api.json -o ./src/features/users/services/gen --no-client --modular"
+```
+
+---
+
+## Environment Variables
+
+```env
+# API
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_API_AUTH_URL=http://localhost:8001
+
+# App
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_APP_NAME={{PROJECT_NAME}}
+```
+
+---
+
+## Docker
+
+```bash
+pnpm docker:build          # Build + Trivy scan
+docker-compose up          # Local dev stack on :3000
+```
+
+The Dockerfile uses 3 stages: `deps` → `builder` → `runner` (minimal Node image). Uses `output: 'standalone'` for smallest container size.
+
 ---
 
-**Learn more:** [Next.js Docs](https://nextjs.org/docs)
+**Framework:** Next.js 16 · **Styling:** Tailwind CSS 4 + Shadcn/ui · **i18n:** next-intl (EN/VI) · **State:** Zustand 5 + TanStack Query 5

package/templates/template-nextjs/src/features/auth/components/sign-in-form.tsx

@@ -40,7 +40,7 @@ export function SignInForm() {
     <Card className="w-full max-w-md">
       <CardHeader className="space-y-1">
         <CardTitle className="text-2xl font-bold">Sign in</CardTitle>
-        <CardDescription>Enter your credentials to access your account</CardDescription>
+        <CardDescription>Enter your credentials to access your account · or try <strong>demo / demo</strong></CardDescription>
       </CardHeader>
       <CardContent>
         <Form {...form}>

package/templates/template-nextjs/src/features/auth/schemas/auth-schema.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod'
 
 export const signInSchema = z.object({
-  email: z.string().email('Invalid email address'),
-  password: z.string().min(6, 'Password must be at least 6 characters'),
+  email: z.union([z.string().email('Invalid email address'), z.literal('demo')]),
+  password: z.union([z.string().min(6, 'Password must be at least 6 characters'), z.literal('demo')]),
 })
 
 export const signUpSchema = z

package/templates/template-nextjs/src/features/auth/services/auth-api.ts

@@ -14,9 +14,29 @@ interface LoginResponse {
   refreshToken: string
 }
 
+/** Build a minimal JWT (not server-verified) for the demo account */
+function makeDemoToken(): string {
+  const b64 = (obj: object) =>
+    btoa(JSON.stringify(obj)).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_')
+  const header = b64({ alg: 'HS256', typ: 'JWT' })
+  const payload = b64({ sub: 'demo', roles: ['admin'], permissions: ['*'], exp: 9999999999 })
+  return `${header}.${payload}.demo`
+}
+
+const DEMO_RESPONSE: LoginResponse = {
+  user: { id: 'demo', email: 'demo', name: 'Demo User', roles: ['admin'], permissions: ['*'] },
+  accessToken: makeDemoToken(),
+  refreshToken: 'demo-refresh',
+}
+
 export const authApi = {
-  login: (data: SignInValues) =>
-    apiClient.post<LoginResponse>('/auth/login', data).then((r) => r.data),
+  login: (data: SignInValues): Promise<LoginResponse> => {
+    // Demo account — works without a real backend
+    if (data.email === 'demo' && data.password === 'demo') {
+      return Promise.resolve(DEMO_RESPONSE)
+    }
+    return apiClient.post<LoginResponse>('/auth/login', data).then((r) => r.data)
+  },
 
   logout: () => apiClient.post('/auth/logout'),
 

package/templates/template-vite/README.md

@@ -1,241 +1,305 @@
 # {{PROJECT_NAME}}
 
-> Vite 7 single-page application (SPA) portal frontend
-
-Lightning-fast Vite 7 application with TanStack Router, i18n, dark mode, authentication, and Nginx deployment ready.
+> Vite 8 SPA portal — scaffolded by [doo-boilerplate](https://www.npmjs.com/package/doo-boilerplate)
 
 ## Quick Start
 
 ```bash
-pnpm dev
+cp .env.example .env   # configure API URLs
+pnpm dev               # http://localhost:5173
 ```
 
-Open [http://localhost:5173](http://localhost:5173) in your browser.
+---
 
-## Available Scripts
+## Scripts
 
 | Command | Purpose |
 |---------|---------|
-| `pnpm dev` | Start dev server with HMR |
-| `pnpm build` | Build for production |
-| `pnpm preview` | Preview production build locally |
-| `pnpm lint` | Run ESLint |
-| `pnpm lint:fix` | Fix linting issues |
-| `pnpm type-check` | TypeScript type checking |
-| `pnpm format` | Format code with Prettier |
-| `pnpm format:check` | Check formatting without changes |
-| `pnpm knip` | Find unused files/exports |
-| `pnpm gen:api` | Generate types from Swagger spec |
-| `pnpm gen:api:watch` | Watch mode for API generation |
-| `pnpm docker:build` | Build & scan Docker image |
-| `pnpm docker:scan` | Security scan image with Trivy |
-
-## Tech Stack
-
-- **Bundler:** Vite 7 with SWC (lightning-fast)
-- **Routing:** TanStack Router 1 (file-based)
-- **Styling:** Tailwind CSS 4 + Shadcn/ui
-- **i18n:** i18next with auto-detection
-- **State:** Zustand 5 (global) + TanStack Query 5 (server)
-- **Forms:** React Hook Form + Zod
-- **HTTP:** Axios with JWT interceptors
-- **Auth:** JWT store with refresh token persistence
-- **DevOps:** Docker (multi-stage) + Nginx + Trivy
+| `pnpm dev` | Dev server with HMR |
+| `pnpm build` | Production build |
+| `pnpm preview` | Preview production build |
+| `pnpm lint` / `lint:fix` | ESLint |
+| `pnpm type-check` | TypeScript |
+| `pnpm format` | Prettier |
+| `pnpm knip` | Find unused code |
+| `pnpm gen:api` | Generate types from `docs/swagger/api.json` |
+| `pnpm gen:api:watch` | Watch mode |
+| `pnpm docker:build` | Build image + Trivy scan |
+| `pnpm docker:scan` | Scan existing image |
 
-## Environment Variables
+---
 
-Copy `.env.example` to `.env`:
+## Folder Structure
 
-```bash
-cp .env.example .env
+```
+src/
+├── routes/                         # TanStack Router (file-based, type-safe)
+│   ├── __root.tsx                  # Root layout: providers, loading bar
+│   ├── _authenticated.tsx          # Auth guard: redirects to /sign-in if no token
+│   ├── _authenticated/
+│   │   ├── dashboard.tsx           # /dashboard
+│   │   ├── profile.tsx             # /profile
+│   │   └── settings.tsx            # /settings
+│   ├── (auth)/
+│   │   └── sign-in.tsx             # /sign-in (public)
+│   └── (errors)/
+│       └── 404.tsx                 # 404 page
+│
+├── routeTree.gen.ts                # Auto-generated — NEVER edit manually
+│
+├── main.tsx                        # Entry: i18n init → <RouterProvider>
+│
+├── components/
+│   ├── ui/                         # Shadcn/ui primitives — DO NOT EDIT
+│   │   └── button, card, dialog, form, input, select, ...
+│   ├── common/                     # Shared app-wide components
+│   │   ├── error-boundary.tsx
+│   │   ├── loading-spinner.tsx
+│   │   └── theme-toggle.tsx        # Dark/light/system toggle
+│   └── layout/                     # Page chrome
+│       ├── sidebar.tsx             # Collapsible nav sidebar
+│       ├── header.tsx              # Top bar with user menu
+│       └── page-layout.tsx         # Wrapper: sidebar + main content
+│
+├── context/
+│   └── theme-provider.tsx          # next-themes wrapper for Vite
+│
+├── features/                       # Domain modules (feature-first)
+│   └── auth/
+│       ├── components/
+│       │   └── sign-in-form.tsx
+│       ├── hooks/
+│       │   └── use-auth.ts         # useSignIn, useSignOut, useCurrentUser
+│       ├── schemas/
+│       │   └── auth-schema.ts      # Zod: LoginSchema
+│       └── services/
+│           ├── auth-api.ts         # API calls: login, logout, me
+│           └── gen/                # Auto-generated types (pnpm gen:api)
+│
+├── hooks/                          # Shared custom hooks
+│   └── use-media-query.ts
+│
+├── lib/                            # Utilities & singletons
+│   ├── api-client.ts               # Axios instance (auto Bearer token + 401 handler)
+│   ├── i18n.ts                     # i18next init with EN/VI resources
+│   ├── query-client.ts             # TanStack Query client config
+│   └── utils.ts                    # cn() = clsx + tailwind-merge
+│
+├── stores/
+│   └── auth-store.ts               # Zustand auth (persisted to localStorage)
+│
+├── styles/
+│   └── globals.css                 # @import tailwindcss + CSS variables
+│
+└── types/
+    └── index.ts                    # Shared TS types
 ```
 
-In Vite, environment variables must be prefixed with `VITE_`:
+---
 
-```env
-# API Configuration
-VITE_API_URL=http://localhost:8000
-VITE_API_AUTH_URL=http://localhost:8001
+## Design Patterns
 
-# App
-VITE_APP_URL=http://localhost:5173
-VITE_APP_NAME={{PROJECT_NAME}}
-```
+### File-Based Routing (TanStack Router)
 
-Access in code:
+Routes are defined by files in `src/routes/`. The router plugin auto-generates `routeTree.gen.ts` on save.
 
-```typescript
-const apiUrl = import.meta.env.VITE_API_URL
-```
+| File naming | Result |
+|-------------|--------|
+| `_authenticated.tsx` | Layout route — all nested routes require auth |
+| `_authenticated/dashboard.tsx` | `/dashboard` (protected) |
+| `(auth)/sign-in.tsx` | `/sign-in` (parentheses = pathless group) |
+| `__root.tsx` | Root layout (wraps everything) |
 
-## Project Structure
+**Add a new protected page:**
 
+```bash
+touch src/routes/_authenticated/reports.tsx
 ```
-src/
-├── routes/
-│   ├── __root.tsx           # Root route (layout)
-│   ├── index.tsx            # Home page (/)
-│   ├── auth/
-│   │   ├── login.tsx        # /auth/login
-│   │   └── register.tsx     # /auth/register
-│   ├── dashboard/
-│   │   └── index.tsx        # /dashboard
-│   └── _404.tsx             # 404 Not Found
-├── routeTree.gen.ts         # Auto-generated by @tanstack/router-plugin
-├── main.tsx                 # App entry point
-├── components/
-│   ├── ui/                  # Shadcn/ui components
-│   └── **/                  # Feature-specific components
-├── features/
-│   ├── auth/
-│   │   ├── hooks/
-│   │   ├── stores/          # Zustand auth store
-│   │   ├── services/
-│   │   │   └── gen/         # Generated API types (gen:api)
-│   │   └── types/
-│   └── **/
-├── hooks/                   # Custom React hooks
-├── context/                 # React context providers
-├── lib/
-│   ├── cn.ts                # Tailwind merge utility
-│   ├── http.ts              # Axios instance
-│   └── **/
-├── stores/                  # Zustand stores
-├── styles/
-│   ├── globals.css
-│   └── variables.css        # CSS variables
-└── types/
-    └── index.ts
+
+```ts
+// src/routes/_authenticated/reports.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/reports')({
+  component: ReportsPage,
+})
+
+function ReportsPage() {
+  return <PageLayout title="Reports">...</PageLayout>
+}
 ```
 
-## TanStack Router Basics
+The route is auto-discovered and added to the type-safe route tree.
 
-### File-Based Routing
+### Feature-First Modules
 
-Routes defined by file structure in `src/routes/`:
+Add new domain logic as a self-contained feature:
 
 ```
-routes/
-├── __root.tsx           → Root layout
-├── index.tsx            → /
-├── about.tsx            → /about
-├── auth/
-│   ├── login.tsx        → /auth/login
-│   └── register.tsx     → /auth/register
-└── dashboard.index.tsx  → /dashboard
+features/reports/
+├── components/report-table.tsx
+├── hooks/use-reports.ts        ← TanStack Query hooks
+├── schemas/report-schema.ts    ← Zod validation
+└── services/
+    ├── reports-api.ts          ← API calls
+    └── gen/                    ← Generated types (optional)
 ```
 
-**Note:** Index files use `index.tsx`, nested routes use folder structure.
+### State Layers
 
-### Route Generation
+| State type | Tool | Location |
+|-----------|------|----------|
+| Server / async data | TanStack Query | `features/{x}/hooks/` |
+| Global client state | Zustand | `src/stores/` |
+| Form state | React Hook Form | component-local |
+| URL / search params | TanStack Router | `Route.useSearch()` |
 
-TanStack Router automatically generates `src/routeTree.gen.ts`. **Do not edit** this file manually—it's regenerated on every build.
+**Rule:** Never put fetched data in Zustand. Only truly global client state (auth, UI prefs) goes in stores.
 
-### Define Route Handlers
+### Auth Store
 
-```typescript
-// src/routes/auth/login.tsx
-import { createFileRoute } from '@tanstack/react-router'
+```ts
+import { useAuthStore } from '@/stores/auth-store'
 
-export const Route = createFileRoute('/auth/login')({
-  component: LoginPage,
-})
+// Read
+const { user, isAuthenticated } = useAuthStore()
 
-function LoginPage() {
-  return <div>Login Page</div>
-}
+// RBAC
+const isAdmin = useAuthStore(s => s.hasRole('admin'))
+const canPublish = useAuthStore(s => s.hasPermission('publish:articles'))
+
+// Mutations
+const { login, logout } = useAuthStore()
 ```
 
-### Link Navigation
+Persisted fields: `user`, `accessToken`, `refreshToken`, `isAuthenticated`.
 
-```typescript
-import { Link } from '@tanstack/react-router'
+### Auth Guard (Route Protection)
 
-export function Nav() {
-  return (
-    <nav>
-      <Link to="/">Home</Link>
-      <Link to="/auth/login">Login</Link>
-    </nav>
-  )
-}
+```ts
+// routes/_authenticated.tsx
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: () => {
+    const { isAuthenticated } = useAuthStore.getState()
+    if (!isAuthenticated) throw redirect({ to: '/sign-in' })
+  },
+})
 ```
 
-## API Code Generation
+All routes nested under `_authenticated/` inherit this guard automatically.
 
-Generate TypeScript types from backend Swagger spec:
+### API Client
 
-```bash
-# Place spec at docs/swagger/api.json
-curl https://api.example.com/swagger.json > docs/swagger/api.json
+```ts
+import apiClient from '@/lib/api-client'
 
-# Generate types
-pnpm gen:api
+// features/reports/services/reports-api.ts
+export const reportsApi = {
+  list: (params?: FilterParams) =>
+    apiClient.get<Report[]>('/reports', { params }).then(r => r.data),
+  create: (data: CreateReportDto) =>
+    apiClient.post<Report>('/reports', data).then(r => r.data),
+}
+```
+
+Auto-injects `Authorization: Bearer <token>` and redirects to `/sign-in` on 401.
+
+### TanStack Query Hooks
+
+```ts
+// features/reports/hooks/use-reports.ts
+export function useReports(params?: FilterParams) {
+  return useQuery({
+    queryKey: ['reports', params],
+    queryFn: () => reportsApi.list(params),
+    staleTime: 5 * 60_000,
+  })
+}
 
-# Watch mode during API development
-pnpm gen:api:watch
+export function useCreateReport() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: reportsApi.create,
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['reports'] }),
+  })
+}
 ```
 
-Generated types appear in `src/features/auth/services/gen/`.
+### Form Pattern
 
-## Docker Deployment
+```ts
+const schema = z.object({ title: z.string().min(3) })
+type Values = z.infer<typeof schema>
 
-### Build & Scan
+function CreateReportForm() {
+  const form = useForm<Values>({ resolver: zodResolver(schema) })
+  const { mutate, isPending } = useCreateReport()
 
-```bash
-pnpm docker:build
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(data => mutate(data))}>
+        <FormField control={form.control} name="title" render={...} />
+        <Button disabled={isPending}>Create</Button>
+      </form>
+    </Form>
+  )
+}
 ```
 
-Builds optimized production bundle and scans for vulnerabilities with Trivy.
+### Internationalization
 
-### Local Development
+```ts
+import { useTranslation } from 'react-i18next'
 
-```bash
-docker-compose up
-# App runs on http://localhost:3000
+function Dashboard() {
+  const { t, i18n } = useTranslation('dashboard')
+  return <h1>{t('welcome')}</h1>
+}
+
+// Switch language
+i18n.changeLanguage('vi')
 ```
 
-Environment variables read from `.env` file.
+Translation resources are in `src/lib/i18n.ts`. Add new namespaces or languages there.
 
-### Production Build
+---
 
-The Docker image includes Nginx for SPA routing. All requests fallback to `index.html`:
+## API Type Generation
 
 ```bash
-docker build -t my-app:latest \
-  --build-arg VITE_API_URL=https://api.example.com .
+# 1. Place your backend OpenAPI spec
+curl https://api.example.com/swagger.json > docs/swagger/api.json
 
-docker run -p 80:80 my-app:latest
-# Access at http://localhost
+# 2. Generate TypeScript types
+pnpm gen:api
+
+# 3. Import generated types
+import type { LoginRequest } from '@/features/auth/services/gen'
 ```
 
-### Nginx Configuration
+---
 
-Nginx config at `nginx.conf` handles SPA routing (all requests → `index.html`). No changes needed for typical deployments.
+## Environment Variables
+
+```env
+VITE_API_URL=http://localhost:8000
+VITE_API_AUTH_URL=http://localhost:8001
+VITE_APP_NAME={{PROJECT_NAME}}
+```
 
-## Vite Configuration
+Access in code: `import.meta.env.VITE_API_URL`
 
-Key Vite settings in `vite.config.ts`:
+---
 
-```typescript
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react-swc'
-import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+## Docker
 
-export default defineConfig({
-  plugins: [
-    TanStackRouterVite(),  // Auto-generate routes
-    react(),
-  ],
-  server: {
-    port: 5173,
-  },
-  build: {
-    target: 'ES2020',
-  },
-})
+```bash
+pnpm docker:build          # Build + Trivy scan
+docker-compose up          # Local dev stack on :3000
 ```
 
+Vite builds a static bundle served by Nginx. The `nginx.conf` uses `try_files $uri /index.html` for SPA routing.
+
 ---
 
-**Learn more:** [Vite Docs](https://vitejs.dev) | [TanStack Router Docs](https://tanstack.com/router)
+**Framework:** Vite 8 + React 19 · **Routing:** TanStack Router (file-based) · **Styling:** Tailwind CSS 4 + Shadcn/ui · **i18n:** i18next (EN/VI) · **State:** Zustand 5 + TanStack Query 5 · **Node:** ≥20.19.0

package/templates/template-vite/package.json

@@ -25,7 +25,7 @@
     "react-i18next": "^15.5.2",
     "i18next-browser-languagedetector": "^8.0.5",
     "next-themes": "^0.4.6",
-    "@tanstack/react-router": "^1.132.47",
+    "@tanstack/react-router": "^1.166.12",
     "@tanstack/react-query": "^5.90.2",
     "@tanstack/react-table": "^8.21.3",
     "zustand": "^5.0.8",
@@ -63,13 +63,13 @@
     "@types/react-dom": "^19",
     "@types/node": "^22",
     "typescript": "^5.9.3",
-    "@vitejs/plugin-react-swc": "^4.1.0",
-    "vite": "^7.1.9",
-    "@tailwindcss/vite": "^4.1.14",
-    "tailwindcss": "^4.1.14",
-    "@tanstack/router-plugin": "^1.132.47",
+    "@vitejs/plugin-react-swc": "^4.3.0",
+    "vite": "^8.0.0",
+    "@tailwindcss/vite": "^4.2.1",
+    "tailwindcss": "^4.2.1",
+    "@tanstack/router-plugin": "^1.166.12",
     "@tanstack/react-query-devtools": "^5.90.2",
-    "@tanstack/router-devtools": "^1.132.47",
+    "@tanstack/router-devtools": "^1.166.12",
     "eslint": "^9",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-unused-imports": "^4.1.4",
@@ -87,5 +87,8 @@
   },
   "lint-staged": {
     "*.{js,ts,tsx,css}": ["eslint --fix", "prettier --write"]
+  },
+  "engines": {
+    "node": ">=20.19.0"
   }
 }

package/templates/template-vite/src/features/auth/components/sign-in-form.tsx

@@ -25,7 +25,7 @@ export function SignInForm() {
       <div className='text-center'>
         <h1 className='text-2xl font-bold tracking-tight'>Sign in</h1>
         <p className='mt-1 text-sm text-muted-foreground'>
-          Enter your credentials to access your account
+          Enter your credentials to access your account · or try <strong>demo / demo</strong>
         </p>
       </div>
 

package/templates/template-vite/src/features/auth/schemas/auth-schema.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 
 export const signInSchema = z.object({
-  email: z.string().email('Please enter a valid email address'),
+  email: z.union([z.string().email('Please enter a valid email address'), z.literal('demo')]),
   password: z.string().min(1, 'Password is required'),
 })
 

package/templates/template-vite/src/features/auth/services/auth-api.ts

@@ -14,9 +14,29 @@ interface LoginResponse {
   refreshToken: string
 }
 
+/** Build a minimal JWT (not server-verified) for the demo account */
+function makeDemoToken(): string {
+  const b64 = (obj: object) =>
+    btoa(JSON.stringify(obj)).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_')
+  const header = b64({ alg: 'HS256', typ: 'JWT' })
+  const payload = b64({ sub: 'demo', roles: ['admin'], permissions: ['*'], exp: 9999999999 })
+  return `${header}.${payload}.demo`
+}
+
+const DEMO_RESPONSE: LoginResponse = {
+  user: { id: 'demo', email: 'demo', name: 'Demo User', roles: ['admin'], permissions: ['*'] },
+  accessToken: makeDemoToken(),
+  refreshToken: 'demo-refresh',
+}
+
 export const authApi = {
-  login: (data: SignInValues) =>
-    apiClient.post<LoginResponse>('/auth/login', data).then((r) => r.data),
+  login: (data: SignInValues): Promise<LoginResponse> => {
+    // Demo account — works without a real backend
+    if (data.email === 'demo' && data.password === 'demo') {
+      return Promise.resolve(DEMO_RESPONSE)
+    }
+    return apiClient.post<LoginResponse>('/auth/login', data).then((r) => r.data)
+  },
 
   logout: () => apiClient.post('/auth/logout'),
 

package/templates/template-vite/vite.config.ts

@@ -15,7 +15,7 @@ export default defineConfig({
   },
   build: {
     target: 'esnext',
-    rollupOptions: {
+    rolldownOptions: {
       output: {
         manualChunks: {
           vendor: ['react', 'react-dom'],