|
| 1 | +# Genesis Base Template v2 - AI Development Guide |
| 2 | + |
| 3 | +## Core Rules |
| 4 | + |
| 5 | +1. **Work ONLY in `src/`** - Create/modify files only under `src/`, never touch files outside |
| 6 | +2. **Don't modify `src/main.tsx`** - Entry point is fixed |
| 7 | +3. **Start with `src/App.tsx`** - Root component of the application |
| 8 | +4. **Use `@/` imports** - `import { cn } from '@/lib/utils'` not relative paths |
| 9 | + |
| 10 | +## File Structure |
| 11 | + |
| 12 | +``` |
| 13 | +src/ |
| 14 | +├── App.tsx # Root component (start here) |
| 15 | +├── main.tsx # Entry point (don't modify) |
| 16 | +├── index.css # Tailwind + CSS variables |
| 17 | +├── components/ui/ # Base UI components (Button, Dialog, etc.) |
| 18 | +├── components/ai-elements/ # Pre-built AI chat UI components |
| 19 | +└── lib/ |
| 20 | + ├── utils.ts # cn() utility |
| 21 | + └── agent-chat/v2/ # Agent Chat SDK (useChat + createAgentChat) |
| 22 | +``` |
| 23 | + |
| 24 | +## Available Dependencies |
| 25 | + |
| 26 | +### Core |
| 27 | + |
| 28 | +- react 18.3, react-dom 18.3, typescript 5.4, tailwindcss 3.4 |
| 29 | + |
| 30 | +### UI & Styling |
| 31 | + |
| 32 | +- **@radix-ui/react-\*** - Dialog, Dropdown Menu, Select, Switch, Tabs, Tooltip, Progress, Separator |
| 33 | +- **lucide-react** 0.542 - Icons (1000+ available) |
| 34 | +- **framer-motion** 12.9 - Animations |
| 35 | +- **next-themes** 0.4 - Dark mode |
| 36 | +- **tailwind-merge** + **clsx** - `cn()` utility |
| 37 | +- **class-variance-authority** 0.7 - Variant styling |
| 38 | +- **@radix-ui/colors** 3.0 - Color system |
| 39 | + |
| 40 | +### Forms & Validation |
| 41 | + |
| 42 | +- **react-hook-form** 7.54 + **@hookform/resolvers** 3.4 |
| 43 | +- **zod** 3.25 - Schema validation |
| 44 | + |
| 45 | +### State & Routing |
| 46 | + |
| 47 | +- **zustand** 4.5 - State management |
| 48 | +- **react-router-dom** 6.30 - Routing |
| 49 | +- **react-oidc-context** 3.3 - OIDC auth client |
| 50 | +- **axios** 1.12 - HTTP client |
| 51 | + |
| 52 | +### UI Components |
| 53 | + |
| 54 | +- **cmdk** 1.1 - Command palette |
| 55 | +- **sonner** 2.0 - Toasts |
| 56 | +- **@hello-pangea/dnd** 18.0 - Drag & drop |
| 57 | +- **@formkit/auto-animate** 0.8 - Auto animations |
| 58 | +- **react-textarea-autosize** 8.5 - Auto-growing textarea |
| 59 | +- **react-intersection-observer** 9.16 - Visibility detection |
| 60 | +- **react-error-boundary** 5.0 - Error boundaries |
| 61 | + |
| 62 | +### Content & Data |
| 63 | + |
| 64 | +- **react-markdown** 10.1 + **remark-gfm** 4.0 - Markdown |
| 65 | +- **recharts** 2.15 - Charts |
| 66 | +- **date-fns** 4.1 - Date utilities |
| 67 | + |
| 68 | +### AI Chat |
| 69 | + |
| 70 | +- **@ai-sdk/react** - `useChat` hook for AI chat interfaces |
| 71 | +- **ai** - AI SDK core (types, transports) |
| 72 | +- **ai-elements** - Pre-built chat UI components at `@/components/ai-elements/` |
| 73 | +- **ulidx** - ULID generation for message IDs |
| 74 | + |
| 75 | +## Authentication (OIDC) |
| 76 | + |
| 77 | +A pre-built auth wrapper is available at `@/lib/genesis-auth`. Use it instead of configuring `AuthProvider` manually. |
| 78 | + |
| 79 | +### When to add auth |
| 80 | + |
| 81 | +Add auth when the app needs to identify individual users (login, signup, per-user data, multi-user features). |
| 82 | +Do NOT add auth for single-purpose tools with no user concept. |
| 83 | + |
| 84 | +### Usage |
| 85 | + |
| 86 | +```tsx |
| 87 | +import { GenesisAuth } from '@/lib/genesis-auth'; |
| 88 | + |
| 89 | +function App() { |
| 90 | + return ( |
| 91 | + <GenesisAuth> |
| 92 | + <ProtectedApp /> |
| 93 | + </GenesisAuth> |
| 94 | + ); |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +Access user profile after login: |
| 99 | + |
| 100 | +```tsx |
| 101 | +import { useAuth } from 'react-oidc-context'; |
| 102 | + |
| 103 | +function Profile() { |
| 104 | + const auth = useAuth(); |
| 105 | + if (!auth.isAuthenticated) { |
| 106 | + return <button onClick={() => auth.signinRedirect()}>Sign in</button>; |
| 107 | + } |
| 108 | + const { email, name, preferred_username, sub } = auth.user?.profile ?? {}; |
| 109 | + return <div>Hello {name}</div>; |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +- `auth.signinRedirect()` — trigger login (Genesis provides the login/signup UI) |
| 114 | +- `auth.signoutRedirect()` — logout |
| 115 | +- `auth.isAuthenticated` — check login state |
| 116 | +- `auth.user?.profile` — `{ email, name, preferred_username, sub }` |
| 117 | + |
| 118 | +Do not build custom login forms or custom auth flows unless explicitly asked. |
| 119 | + |
| 120 | +## Pre-built Components |
| 121 | + |
| 122 | +**Base UI** (`@/components/ui/`) — Button, Dialog, Select, Switch, Tabs, etc. |
| 123 | + |
| 124 | +**AI Elements** (`@/components/ai-elements/`) — Pre-built chat UI components: |
| 125 | + |
| 126 | +- `Conversation`, `ConversationContent`, `ConversationScrollButton` — Scrollable chat container |
| 127 | +- `Message`, `MessageContent`, `MessageResponse` — Message bubbles with streaming markdown |
| 128 | +- `PromptInput`, `PromptInputTextarea`, `PromptInputFooter`, `PromptInputSubmit` — Chat input form |
| 129 | +- `Suggestions`, `Suggestion` — Quick-reply suggestion pills |
| 130 | +- `Reasoning`, `ReasoningTrigger`, `ReasoningContent` — Collapsible thinking display |
| 131 | +- `CodeBlock` — Syntax-highlighted code with copy button |
| 132 | + |
| 133 | +See `src/lib/agent-chat/v2/README.md` for full Agent Chat SDK docs + AI Elements usage examples. |
| 134 | + |
| 135 | +Create custom components freely in `src/components/` using Radix UI primitives. |
| 136 | + |
| 137 | +## CSS Design System |
| 138 | + |
| 139 | +Use semantic color classes (automatically supports light/dark mode): |
| 140 | + |
| 141 | +- `bg-background text-foreground` - Page default |
| 142 | +- `bg-primary text-primary-foreground` - Primary buttons |
| 143 | +- `bg-secondary text-secondary-foreground` - Secondary elements |
| 144 | +- `bg-muted text-muted-foreground` - Disabled/subtle |
| 145 | +- `bg-accent text-accent-foreground` - Highlights |
| 146 | +- `bg-destructive text-destructive-foreground` - Delete/error |
| 147 | +- `bg-card text-card-foreground` - Cards |
| 148 | +- `border-border` - Borders |
| 149 | +- `ring-ring` - Focus rings |
| 150 | + |
| 151 | +## Component Patterns |
| 152 | + |
| 153 | +### TypeScript |
| 154 | + |
| 155 | +- Define explicit Props interfaces for all components |
| 156 | +- Use `React.FC<Props>` and function declarations |
| 157 | +- Use Zod schemas with `z.infer<typeof schema>` for form types |
| 158 | + |
| 159 | +### Styling |
| 160 | + |
| 161 | +- Use Tailwind utility classes |
| 162 | +- Use `cn()` from `@/lib/utils` for conditional classes |
| 163 | +- Use semantic color classes for theme consistency |
| 164 | + |
| 165 | +### File Organization |
| 166 | + |
| 167 | +- `src/components/` - Reusable components |
| 168 | +- `src/pages/` - Route pages |
| 169 | +- `src/hooks/` - Custom hooks |
| 170 | +- `src/stores/` - Zustand stores |
| 171 | +- `src/lib/` - Utilities |
| 172 | + |
| 173 | +## Key Libraries Usage |
| 174 | + |
| 175 | +### Routing |
| 176 | + |
| 177 | +- Use `react-router-dom` with `BrowserRouter`, `Routes`, `Route` |
| 178 | + |
| 179 | +### State Management |
| 180 | + |
| 181 | +- Use `zustand` with `create<State>()` for global state |
| 182 | + |
| 183 | +### Forms |
| 184 | + |
| 185 | +- Use `react-hook-form` with `useForm()` and `zodResolver()` for validation |
| 186 | + |
| 187 | +### Icons |
| 188 | + |
| 189 | +- Import from `lucide-react`: `import { Home, User, Settings } from 'lucide-react'` |
| 190 | + |
| 191 | +### Dark Mode |
| 192 | + |
| 193 | +- Use `next-themes` with `ThemeProvider` and `useTheme()` hook |
| 194 | + |
| 195 | +### HTTP |
| 196 | + |
| 197 | +- Use `axios` for API calls |
| 198 | + |
| 199 | +## Summary |
| 200 | + |
| 201 | +React 18 + TypeScript + Tailwind CSS template. Work only in `src/`. Use Radix UI primitives for accessible components, Zustand for state, React Router for routing, react-hook-form + Zod for forms, Lucide for icons. Build custom components as needed. |
0 commit comments