Refactor React app structure: replace AppShell with TopBar for layout, enhance theme handling, and improve authentication flows. Update README for clarity on project features and setup. Add user account management capabilities including profile deletion and password change. Enhance UI components with new logo and alert designs.

Author: claudio-silva

AGENTS.md

@@ -36,11 +36,16 @@ import { Kysely } from 'kysely';
 ```
 src/
 ├── react-app/              # React frontend
+│   ├── assets/             # Static assets (logos, images)
+│   │   ├── logo-light.svg  # Logo for light theme
+│   │   └── logo-dark.svg   # Logo for dark theme
 │   ├── components/
 │   │   ├── auth/           # Auth UI (LoginForm, ProtectedRoute, AuthOverlay)
 │   │   ├── ui/             # shadcn/ui components
-│   │   ├── AppShell.tsx    # Sidebar + header layout
-│   │   └── theme-provider.tsx
+│   │   ├── TopBar.tsx      # Full-width header with logo and user menu
+│   │   ├── Logo.tsx        # Theme-aware logo component
+│   │   ├── ModeToggle.tsx  # Dark/light theme toggle
+│   │   └── theme-provider.tsx  # Theme context with URL param support
 │   ├── pages/              # Route pages
 │   │   ├── auth/           # SignUp, VerifyEmail
 │   │   ├── Home.tsx        # Protected home
@@ -130,8 +135,8 @@ pnpm deploy:production      # Deploy to Cloudflare
 
 ### Add a New Page
 1. Create `src/react-app/pages/MyPage.tsx`
-2. Add route in `src/react-app/App.tsx`
-3. Add nav item in `src/react-app/components/AppShell.tsx`
+2. Add route in `src/react-app/App.tsx` wrapped with `<ProtectedRoute>` and `<TopBar>` if needed
+3. Add navigation as appropriate for your app (TopBar doesn't include nav by default)
 
 ### Add an API Endpoint
 1. Add route in `src/worker/index.ts`

README.md

@@ -2,9 +2,9 @@
 
 [![CI](https://github.com/claudio-silva/cloudflare-fullstack-starter/actions/workflows/ci.yml/badge.svg)](https://github.com/claudio-silva/cloudflare-fullstack-starter/actions/workflows/ci.yml)
 
-A production-ready, agent-friendly full-stack foundation built to run on Cloudflare’s edge platform.
+A full-stack Cloudflare starter that gets you building real features immediately — production-ready, optimized for AI agents, and built to scale on Cloudflare’s global edge network.
 
-Clone it, set it up, and start building. Authentication, database, UI, CLI, and deployment are all ready to go.
+Install it and start building. Authentication, database, UI, CLI, and deployment are all ready to go.
 
 A great starting point for your next MVP or SaaS app.
 
@@ -30,9 +30,9 @@ This means you can build, launch, and validate your idea without upfront infrast
 
 Cloudflare gives you remarkable power at the edge, but it isn’t a traditional hosting platform. Most mainstream web frameworks don’t run on Workers out of the box, and adapting them to Cloudflare’s request-driven runtime can feel unfamiliar if you’re used to environments that hide the wiring. That early friction slows down the part you actually care about: building something new.
 
-Agentic coding helps, but unfamiliar runtimes are still a weak spot. On platforms like Cloudflare, agents rarely succeed on the first attempt. They burn cycles rebuilding boilerplate, fixing type and lint errors, debugging auth flows, smoothing out theme flicker, tweaking configs, and juggling multi-environment setups — all the fragile infrastructure work that slows real development. And every new project means repeating the same setup steps.
+Agentic coding helps, but unfamiliar runtimes are still a weak spot. When developing for platforms like Cloudflare, agents rarely succeed on the first attempt. They burn cycles rebuilding boilerplate, fixing type and lint errors, debugging auth flows, smoothing out theme flicker, tweaking configs, and juggling multi-environment setups — all the fragile infrastructure work that slows real development. And every new project means repeating the same setup steps.
 
-This starter removes that overhead entirely. From the moment you create a project from this template — or even ask your coding agent to install it for you — you begin with a fully working, production-grade foundation:
+This starter removes that overhead entirely. From the moment you create a project from this template — or even ask your coding agent to install it for you — you begin with a fully working, production-ready foundation:
 
 - **Complete Auth Flow** — Sign up, email verification, login, logout, profile management, powered by [Better Auth](https://www.better-auth.com/)
 - **Database Ready** — [Cloudflare D1](https://developers.cloudflare.com/d1/) with migrations, used for auth but extensible
@@ -189,20 +189,25 @@ If wrangler is logged in, you can do it from the command line:
 - CLI user management (create, list, view, edit, delete, activate)
 
 ### UI Features
-- Responsive sidebar + header layout
-- Avatar dropdown with Profile/Logout
-- Dark/light theme with FOUC prevention
+- Clean top header bar with logo and user menu
+- Avatar dropdown with user info, Profile, and Sign Out
+- Dark/light theme toggle with FOUC prevention
+- Theme-aware logo component (auto-switches light/dark)
+- Theme can be passed via URL parameter for cross-app navigation
 - 50+ shadcn/ui components ready to use
 
 ## Project Structure
 
 ```
 ├── src/
 │   ├── react-app/           # React frontend
+│   │   ├── assets/          # Static assets (logo-light.svg, logo-dark.svg)
 │   │   ├── components/
-│   │   │   ├── auth/        # Auth components (LoginForm, ProtectedRoute)
+│   │   │   ├── auth/        # Auth components (LoginForm, ProtectedRoute, AuthOverlay)
 │   │   │   ├── ui/          # shadcn/ui components
-│   │   │   └── AppShell.tsx # Sidebar + header layout
+│   │   │   ├── TopBar.tsx   # Header with logo and user menu
+│   │   │   ├── Logo.tsx     # Theme-aware logo
+│   │   │   └── ModeToggle.tsx # Theme toggle
 │   │   ├── pages/           # Route pages (Home, Profile, auth/)
 │   │   └── lib/auth/        # Better Auth client
 │   └── worker/              # Hono API backend
@@ -220,18 +225,41 @@ If wrangler is logged in, you can do it from the command line:
 
 ### Auth Management
 
+Manage users directly from your terminal — useful for creating admin accounts, debugging, or scripting.
+
+> ⚠️ When managing local users, **the dev server must be running** (`npm run dev`) for these commands to work. They communicate with the API at `http://localhost:5173`.
+
 ```bash
+# List all users (shows email, name, verification status, creation date)
 npm run auth list-users
+npm run auth list-users -- --limit 10           # limit results
+npm run auth list-users -- --search "john"      # search by email or name
+
+# Create a new user (useful for seeding admin accounts)
 npm run auth create-user -- -u [email protected] -p password123
+npm run auth create-user -- -u [email protected] -p password123 -n "Admin User"
+
+# View detailed user info (includes account provider, sessions, timestamps)
 npm run auth show-user -- -u [email protected]
-npm run auth edit-user -- -u [email protected] -n "Admin User"
-npm run auth activate-user -- -u [email protected] -s on
+
+# Edit user details
+npm run auth edit-user -- -u [email protected] -n "New Name"
+npm run auth edit-user -- -u [email protected] -e [email protected]
+npm run auth edit-user -- -u [email protected] -p newpassword123
+
+# Activate or deactivate a user account
+npm run auth activate-user -- -u [email protected] -s on   # activate
+npm run auth activate-user -- -u [email protected] -s off  # deactivate
+
+# Delete a user (removes user, accounts, and sessions)
 npm run auth delete-user -- -u [email protected]
+npm run auth delete-user -- --all                          # delete ALL users (use with caution)
 ```
 
-Or call directly:
+For remote environments, use the `--env` flag and set `CLI_ADMIN_EMAIL`/`CLI_ADMIN_PASSWORD` in your `.env.*` file:
 ```bash
-./bin/auth list-users --env local
+npm run auth list-users -- --env preview
+npm run auth list-users -- --env production
 ```
 
 ### Database
@@ -295,8 +323,8 @@ Search and replace these placeholders:
 ### Adding Pages
 1. Create page in `src/react-app/pages/`
 2. Add route in `src/react-app/App.tsx`
-3. Wrap with `<ProtectedRoute>` if auth required
-4. Add to sidebar in `src/react-app/components/AppShell.tsx`
+3. Wrap with `<ProtectedRoute>` and `<TopBar>` if auth required
+4. Add navigation as appropriate for your app design
 
 ### Email Provider
 Replace `createResendEmailSender` in `src/worker/middleware/auth.ts` with your provider implementing the `EmailSender` interface.

bin/init.ts

@@ -2,6 +2,10 @@ import fs from "fs";
 import path from "path";
 import readline from "readline";
 import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 type Answers = {
 	projectName: string;

index.html

@@ -1,10 +1,31 @@
 <!doctype html>
-<html lang="en" class="dark">
+<html lang="en">
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Vite + React + TS</title>
+    <title>My App</title>
+    <script>
+      // Apply theme BEFORE React renders to prevent flash of unstyled content (FOUC)
+      (function() {
+        const storageKey = 'app-theme';
+        const theme = localStorage.getItem(storageKey) || 'light';
+        
+        let actualTheme = theme;
+        if (theme === 'system') {
+          actualTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+        }
+        
+        document.documentElement.classList.add(actualTheme);
+        
+        // Apply background color immediately to prevent white/dark flash
+        if (actualTheme === 'dark') {
+          document.documentElement.style.backgroundColor = 'hsl(0 0% 3.9%)';
+        } else {
+          document.documentElement.style.backgroundColor = 'hsl(0 0% 100%)';
+        }
+      })();
+    </script>
   </head>
 
   <body>

package.json

@@ -25,12 +25,12 @@
     "deploy:preview": "wrangler deploy --env preview",
     "deploy:production": "wrangler deploy --env production",
     "cf-typegen": "wrangler types",
-    "db:migrate:local": "wrangler d1 migrations apply starter --local",
-    "db:migrate:preview": "wrangler d1 migrations apply starter --env preview",
-    "db:migrate:production": "wrangler d1 migrations apply starter --env production",
-    "db:seed:local": "wrangler d1 execute starter --local --file=./migrations/0002_seed_data.sql",
-    "db:seed:preview": "wrangler d1 execute starter --env preview --file=./migrations/0002_seed_data.sql",
-    "db:seed:production": "wrangler d1 execute starter --env production --file=./migrations/0002_seed_data.sql",
+    "db:migrate:local": "wrangler d1 migrations apply cloudflare-fullstack-starter --local",
+    "db:migrate:preview": "wrangler d1 migrations apply cloudflare-fullstack-starter --env preview",
+    "db:migrate:production": "wrangler d1 migrations apply cloudflare-fullstack-starter --env production",
+    "db:seed:local": "wrangler d1 execute cloudflare-fullstack-starter --local --file=./migrations/0002_seed_data.sql",
+    "db:seed:preview": "wrangler d1 execute cloudflare-fullstack-starter --env preview --file=./migrations/0002_seed_data.sql",
+    "db:seed:production": "wrangler d1 execute cloudflare-fullstack-starter --env production --file=./migrations/0002_seed_data.sql",
     "init": "tsx bin/init.ts",
     "auth": "tsx bin/auth.ts"
   },

src/cli/utils/output.ts

@@ -2,12 +2,14 @@ import { format } from "date-fns";
 
 type TableRow = Record<string, unknown>;
 
+type Timestamp = number | string | Date;
+
 type PrintableAccount = {
 	accountId: string;
 	providerId: string;
 	hasPassword: boolean;
-	createdAt: number | Date;
-	updatedAt: number | Date;
+	createdAt: Timestamp;
+	updatedAt: Timestamp;
 };
 
 type PrintableUser = {
@@ -16,8 +18,8 @@ type PrintableUser = {
 	name?: string | null;
 	image?: string | null;
 	emailVerified?: boolean | number;
-	createdAt: number | Date;
-	updatedAt: number | Date;
+	createdAt: Timestamp;
+	updatedAt: Timestamp;
 	account?: PrintableAccount | null;
 	sessions?: number;
 };
@@ -104,7 +106,14 @@ export function printWarning(message: string): void {
 	console.warn(`⚠️  ${message}`);
 }
 
-export function formatTimestamp(timestamp: number): string {
+export function formatTimestamp(timestamp: number | string | Date): string {
+	// Handle various timestamp formats from API/database
+	if (typeof timestamp === "string") {
+		return format(new Date(timestamp), "yyyy-MM-dd HH:mm:ss");
+	}
+	if (timestamp instanceof Date) {
+		return format(timestamp, "yyyy-MM-dd HH:mm:ss");
+	}
 	return format(new Date(timestamp), "yyyy-MM-dd HH:mm:ss");
 }
 
@@ -114,6 +123,6 @@ export function formatUsersForTable(users: PrintableUser[]): UserRow[] {
 		email: user.email,
 		name: user.name || "N/A",
 		verified: user.emailVerified ? "Yes" : "No",
-		created: formatTimestamp(typeof user.createdAt === "number" ? user.createdAt : user.createdAt.getTime()),
+		created: formatTimestamp(user.createdAt),
 	}));
 }

src/react-app/App.css

@@ -1,51 +1 @@
-#root {
-  max-width: 1280px;
-  margin: 0 auto;
-  padding: 2rem;
-  text-align: center;
-}
-
-.logo {
-  height: 6em;
-  padding: 1.5em;
-  will-change: filter;
-  transition: filter 300ms;
-}
-.logo:hover {
-  filter: drop-shadow(0 0 2em #646cffaa);
-}
-.logo.react:hover {
-  filter: drop-shadow(0 0 2em #61dafbaa);
-}
-.logo.cloudflare:hover {
-  filter: drop-shadow(0 0 2em #f6821faa);
-}
-.logo.cloudflare {
-  height: 9em;
-  padding-left: 0;
-  position: relative;
-  left: -1em;
-}
-
-@keyframes logo-spin {
-  from {
-    transform: rotate(0deg);
-  }
-  to {
-    transform: rotate(360deg);
-  }
-}
-
-@media (prefers-reduced-motion: no-preference) {
-  a:nth-of-type(2) .logo {
-    animation: logo-spin infinite 20s linear;
-  }
-}
-
-.card {
-  padding: 2em;
-}
-
-.read-the-docs {
-  color: #888;
-}
+/* App-specific styles */

src/react-app/App.tsx

@@ -1,50 +1,79 @@
-import { Routes, Route } from "react-router-dom";
-import { AppShell } from "@/components/AppShell";
+import { Routes, Route, useLocation } from "react-router-dom";
+import { TopBar } from "@/components/TopBar";
 import { ProtectedRoute } from "@/components/auth/ProtectedRoute";
 import { Home } from "@/pages/Home";
 import { Profile } from "@/pages/Profile";
 import { SignUp } from "@/pages/auth/SignUp";
 import { VerifyEmail } from "@/pages/auth/VerifyEmail";
+import { authClient } from "@/lib/auth/client";
 import "./App.css";
 
-function App() {
+function AppContent() {
+	const location = useLocation();
+	const { data: session } = authClient.useSession();
+
+	// Auth pages don't use the TopBar layout
+	const isAuthPage = location.pathname === "/signup" || location.pathname === "/verify-email";
+
+	// Only show TopBar if not on an auth page AND user is authenticated
+	// This prevents flash of TopBar while checking auth
+	const shouldShowTopBar = !isAuthPage && !!session;
+
 	return (
 		<Routes>
+			{/* Public auth routes - no TopBar */}
 			<Route path="/signup" element={<SignUp />} />
 			<Route path="/verify-email" element={<VerifyEmail />} />
 
+			{/* Protected routes with TopBar */}
 			<Route
 				path="/"
 				element={
 					<ProtectedRoute>
-						<AppShell>
+						{shouldShowTopBar ? (
+							<TopBar>
+								<Home />
+							</TopBar>
+						) : (
 							<Home />
-						</AppShell>
+						)}
 					</ProtectedRoute>
 				}
 			/>
 			<Route
 				path="/profile"
 				element={
 					<ProtectedRoute>
-						<AppShell>
+						{shouldShowTopBar ? (
+							<TopBar>
+								<Profile />
+							</TopBar>
+						) : (
 							<Profile />
-						</AppShell>
+						)}
 					</ProtectedRoute>
 				}
 			/>
 			<Route
 				path="*"
 				element={
 					<ProtectedRoute>
-						<AppShell>
+						{shouldShowTopBar ? (
+							<TopBar>
+								<Home />
+							</TopBar>
+						) : (
 							<Home />
-						</AppShell>
+						)}
 					</ProtectedRoute>
 				}
 			/>
 		</Routes>
 	);
 }
 
+function App() {
+	return <AppContent />;
+}
+
 export default App;