create-tigra 2.3.0 → 2.4.0

package/bin/create-tigra.js

@@ -216,7 +216,18 @@ async function main() {
         }
 
         // Create .developer-role file (default: fullstack = no restrictions)
-        await fs.writeFile(path.join(targetDir, '.developer-role'), 'fullstack\n', 'utf-8');
+        const developerRoleContent = [
+          'fullstack',
+          '# Available roles (change the first line to switch):',
+          '#',
+          '#   frontend   - Can edit client/ only. Cannot edit server/ files. Can read everything.',
+          '#   backend    - Can edit server/ only. Cannot edit client/ files. Can read everything.',
+          '#   fullstack  - Can edit everything. No restrictions.',
+          '#',
+          '# You can also switch roles using the /role command in Claude.',
+          '',
+        ].join('\n');
+        await fs.writeFile(path.join(targetDir, '.developer-role'), developerRoleContent, 'utf-8');
 
         spinner.succeed('Project scaffolded successfully!');
       } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tigra",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "Create a production-ready full-stack app with Next.js 16 + Fastify 5 + Prisma + Redis",
   "bin": {

package/template/_claude/hooks/restrict-paths.sh

@@ -14,9 +14,9 @@
 
 ROLE_FILE="$CLAUDE_PROJECT_DIR/.developer-role"
 
-# Read role from file, trim whitespace
+# Read role from first non-comment, non-empty line
 if [ -f "$ROLE_FILE" ]; then
-  ROLE=$(tr -d '[:space:]' < "$ROLE_FILE")
+  ROLE=$(grep -v '^\s*#' "$ROLE_FILE" | grep -v '^\s*$' | head -1 | tr -d '[:space:]')
 else
   ROLE=""
 fi

package/template/_claude/rules/server/project-conventions.md

@@ -215,7 +215,15 @@ const apiClient = axios.create({ ...httpClient.defaults, baseURL: 'https://api.e
 
 ## File Storage
 
-Upload directory structure: `uploads/users/{userId}/<media-type>/`
+### Directory Structure Principles
+
+Upload folders must be **scalable and manageable**. Never dump all files into a single flat directory (e.g., all product images under `/uploads/products/`). Instead, organize by **owner/entity ID** so each entity's files are isolated and easy to find, move, or delete.
+
+**Pattern**: `uploads/<domain>/{entityId}/<media-type>/`
+
+### User Uploads
+
+Structure: `uploads/users/{userId}/<media-type>/`
 
 | Media type | Path | Example |
 |---|---|---|
@@ -225,3 +233,22 @@ Upload directory structure: `uploads/users/{userId}/<media-type>/`
 - On account purge, delete the entire `uploads/users/{userId}/` directory via `deleteUserMedia()`.
 - Public URL pattern: `/uploads/users/{userId}/<media-type>/{filename}`
 - New media types follow the same pattern: add a subfolder under the user directory.
+
+### Domain Entity Uploads (Products, Articles, etc.)
+
+Structure: `uploads/<domain>/{entityId}/<media-type>/`
+
+| Domain | Media type | Path | Example |
+|---|---|---|---|
+| Products | Images | `uploads/products/{productId}/images/` | `uploads/products/prod-456/images/front-view.webp` |
+| Products | Thumbnails | `uploads/products/{productId}/thumbnails/` | `uploads/products/prod-456/thumbnails/front-view-thumb.webp` |
+| Articles | Cover | `uploads/articles/{articleId}/cover/` | `uploads/articles/art-789/cover/hero.webp` |
+| Articles | Content images | `uploads/articles/{articleId}/content/` | `uploads/articles/art-789/content/diagram-1.webp` |
+
+### Rules
+
+1. **Never use flat directories** — `uploads/products/img1.jpg, img2.jpg, ...` is forbidden. Always namespace by entity ID.
+2. **One folder per entity instance** — makes deletion, migration, and backup trivial (`rm -rf uploads/products/{id}/`).
+3. **Separate media types into subfolders** — don't mix avatars, thumbnails, and full-size images in the same folder.
+4. **Entity cleanup** — when an entity is deleted, remove its entire upload directory (e.g., `uploads/products/{productId}/`).
+5. **Consistent naming** — use kebab-case for filenames, domain plural for top-level folders (`products`, `articles`, `users`).

package/template/client/package.json

@@ -34,7 +34,6 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
-    "@tanstack/react-query-devtools": "^5.91.3",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",

package/template/client/src/app/globals.css

@@ -55,83 +55,85 @@
 
 :root {
   --radius: 0.625rem;
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
+  /* Claude palette: #f4f3ee (cream), #ffffff (white), #b1ada1 (warm gray), #c15f3c (orange) */
+  --background: oklch(0.964 0.007 97.5);
+  --foreground: oklch(0.205 0.015 92);
   --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
+  --card-foreground: oklch(0.205 0.015 92);
   --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.45 0.2 260);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.205 0.015 92);
+  --primary: oklch(0.597 0.135 39.9);
+  --primary-foreground: oklch(1 0 0);
+  --secondary: oklch(0.935 0.009 97.5);
+  --secondary-foreground: oklch(0.3 0.015 92);
+  --muted: oklch(0.935 0.009 97.5);
+  --muted-foreground: oklch(0.748 0.017 91.6);
+  --accent: oklch(0.935 0.009 97.5);
+  --accent-foreground: oklch(0.3 0.015 92);
   --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.45 0.2 260);
+  --border: oklch(0.895 0.012 97.5);
+  --input: oklch(0.895 0.012 97.5);
+  --ring: oklch(0.597 0.135 39.9);
   --success: oklch(0.52 0.17 155);
   --success-foreground: oklch(1 0 0);
-  --warning: oklch(0.75 0.18 75);
-  --warning-foreground: oklch(0.2 0 0);
+  --warning: oklch(0.75 0.15 70);
+  --warning-foreground: oklch(0.25 0.015 92);
   --info: oklch(0.55 0.15 240);
   --info-foreground: oklch(1 0 0);
-  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-1: oklch(0.597 0.135 39.9);
   --chart-2: oklch(0.6 0.118 184.704);
   --chart-3: oklch(0.398 0.07 227.392);
-  --chart-4: oklch(0.828 0.189 84.429);
-  --chart-5: oklch(0.769 0.188 70.08);
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0 0);
-  --sidebar-primary: oklch(0.205 0 0);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.97 0 0);
-  --sidebar-accent-foreground: oklch(0.205 0 0);
-  --sidebar-border: oklch(0.922 0 0);
-  --sidebar-ring: oklch(0.708 0 0);
+  --chart-4: oklch(0.828 0.12 84);
+  --chart-5: oklch(0.748 0.017 91.6);
+  --sidebar: oklch(0.95 0.007 97.5);
+  --sidebar-foreground: oklch(0.205 0.015 92);
+  --sidebar-primary: oklch(0.3 0.015 92);
+  --sidebar-primary-foreground: oklch(0.964 0.007 97.5);
+  --sidebar-accent: oklch(0.935 0.009 97.5);
+  --sidebar-accent-foreground: oklch(0.3 0.015 92);
+  --sidebar-border: oklch(0.895 0.012 97.5);
+  --sidebar-ring: oklch(0.597 0.135 39.9);
 }
 
 .dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.205 0 0);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.205 0 0);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.6 0.2 260);
-  --primary-foreground: oklch(0.145 0 0);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.708 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.985 0 0);
+  /* Dark mode: inverted Claude palette with same warm undertone */
+  --background: oklch(0.185 0.012 92);
+  --foreground: oklch(0.93 0.007 97.5);
+  --card: oklch(0.235 0.012 92);
+  --card-foreground: oklch(0.93 0.007 97.5);
+  --popover: oklch(0.235 0.012 92);
+  --popover-foreground: oklch(0.93 0.007 97.5);
+  --primary: oklch(0.66 0.135 39.9);
+  --primary-foreground: oklch(0.185 0.012 92);
+  --secondary: oklch(0.28 0.012 92);
+  --secondary-foreground: oklch(0.93 0.007 97.5);
+  --muted: oklch(0.28 0.012 92);
+  --muted-foreground: oklch(0.65 0.015 91.6);
+  --accent: oklch(0.28 0.012 92);
+  --accent-foreground: oklch(0.93 0.007 97.5);
   --destructive: oklch(0.704 0.191 22.216);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.6 0.2 260);
+  --border: oklch(1 0.007 97.5 / 12%);
+  --input: oklch(1 0.007 97.5 / 15%);
+  --ring: oklch(0.66 0.135 39.9);
   --success: oklch(0.6 0.17 155);
   --success-foreground: oklch(1 0 0);
-  --warning: oklch(0.8 0.18 75);
-  --warning-foreground: oklch(0.2 0 0);
+  --warning: oklch(0.8 0.15 70);
+  --warning-foreground: oklch(0.25 0.015 92);
   --info: oklch(0.65 0.15 240);
   --info-foreground: oklch(1 0 0);
-  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-1: oklch(0.66 0.135 39.9);
   --chart-2: oklch(0.696 0.17 162.48);
-  --chart-3: oklch(0.769 0.188 70.08);
-  --chart-4: oklch(0.627 0.265 303.9);
-  --chart-5: oklch(0.645 0.246 16.439);
-  --sidebar: oklch(0.205 0 0);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.269 0 0);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.556 0 0);
+  --chart-3: oklch(0.769 0.12 70);
+  --chart-4: oklch(0.627 0.18 303.9);
+  --chart-5: oklch(0.645 0.17 16.439);
+  --sidebar: oklch(0.235 0.012 92);
+  --sidebar-foreground: oklch(0.93 0.007 97.5);
+  --sidebar-primary: oklch(0.66 0.135 39.9);
+  --sidebar-primary-foreground: oklch(0.93 0.007 97.5);
+  --sidebar-accent: oklch(0.28 0.012 92);
+  --sidebar-accent-foreground: oklch(0.93 0.007 97.5);
+  --sidebar-border: oklch(1 0.007 97.5 / 12%);
+  --sidebar-ring: oklch(0.66 0.135 39.9);
 }
 
 @layer base {

package/template/client/src/app/page.tsx

@@ -1,45 +1,76 @@
-'use client';
-
 import type React from 'react';
-import { LogOut } from 'lucide-react';
+import type { Metadata } from 'next';
+
+import Image from 'next/image';
 
-import { Button } from '@/components/ui/button';
-import { Skeleton } from '@/components/ui/skeleton';
-import { useAppSelector } from '@/store/hooks';
-import { useAuth } from '@/features/auth/hooks/useAuth';
 import { APP_NAME } from '@/lib/constants/app.constants';
 
-export default function WelcomePage(): React.ReactElement {
-  const { user } = useAppSelector((state) => state.auth);
-  const { logout, isLoggingOut } = useAuth();
+export const metadata: Metadata = {
+  title: APP_NAME,
+  description: `Welcome to ${APP_NAME} — generated with create-tigra`,
+};
 
+export default function WelcomePage(): React.ReactElement {
   return (
-    <div className="flex min-h-dvh flex-col">
-      <header className="flex items-center justify-between px-6 py-4">
-        <span className="text-lg font-semibold tracking-tight text-foreground">
+    <div className="relative flex min-h-dvh flex-col items-center justify-center overflow-hidden px-6">
+      {/* Ambient glow */}
+      <div
+        aria-hidden="true"
+        className="pointer-events-none absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2"
+      >
+        <div className="motion-safe:animate-pulse h-64 w-64 rounded-full bg-primary/15 blur-3xl md:h-96 md:w-96" />
+      </div>
+
+      {/* Content */}
+      <div className="relative z-10 flex max-w-md flex-col items-center text-center">
+        {/* Logo */}
+        <div className="mb-8">
+          <Image
+            src="/logo.png"
+            alt={`${APP_NAME} logo`}
+            width={160}
+            height={160}
+            priority
+            className="h-32 w-32 md:h-40 md:w-40"
+          />
+        </div>
+
+        <h1 className="text-3xl font-bold tracking-tight text-foreground md:text-4xl">
           {APP_NAME}
-        </span>
-        <Button
-          variant="ghost"
-          size="sm"
-          onClick={logout}
-          disabled={isLoggingOut}
-          className="text-muted-foreground transition-colors duration-150 hover:text-foreground"
-        >
-          <LogOut className="mr-2 h-4 w-4" />
-          Sign out
-        </Button>
-      </header>
-
-      <main className="flex flex-1 items-center justify-center">
-        {user ? (
-          <h1 className="text-3xl font-light tracking-tight text-foreground">
-            Welcome, {user.firstName}
-          </h1>
-        ) : (
-          <Skeleton className="h-9 w-64" />
-        )}
-      </main>
+        </h1>
+
+        <p className="mt-3 text-base text-muted-foreground md:text-lg">
+          Generated with{' '}
+          <span className="font-semibold text-foreground">create-tigra</span>
+        </p>
+
+        <div className="mt-8 flex flex-col gap-3 sm:flex-row sm:gap-4">
+          <a
+            href="https://github.com/BehzodKarimov/create-tigra"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex min-h-11 items-center justify-center rounded-lg bg-primary px-5 py-2.5 text-sm font-medium text-primary-foreground shadow-sm transition-all duration-200 active:scale-[0.97] md:hover:brightness-110"
+          >
+            Documentation
+          </a>
+          <a
+            href="https://github.com/BehzodKarimov/create-tigra/issues"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex min-h-11 items-center justify-center rounded-lg border border-border bg-secondary px-5 py-2.5 text-sm font-medium text-secondary-foreground transition-all duration-200 active:scale-[0.97] md:hover:bg-accent"
+          >
+            Report an issue
+          </a>
+        </div>
+
+        <p className="mt-12 font-mono text-xs text-muted-foreground md:text-sm">
+          Edit{' '}
+          <code className="rounded-md bg-muted px-1.5 py-0.5">
+            src/app/page.tsx
+          </code>{' '}
+          to get started
+        </p>
+      </div>
     </div>
   );
 }

package/template/client/src/app/providers.tsx

@@ -4,7 +4,6 @@ import type React from 'react';
 import { useState } from 'react';
 
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import { Provider as ReduxProvider } from 'react-redux';
 import { ThemeProvider } from 'next-themes';
 import { Toaster } from 'sonner';
@@ -36,7 +35,6 @@ export function Providers({ children }: { children: React.ReactNode }): React.Re
           </AuthInitializer>
           <Toaster position="top-right" richColors />
         </ThemeProvider>
-        {process.env.NODE_ENV === 'development' && <ReactQueryDevtools initialIsOpen={false} />}
       </QueryClientProvider>
     </ReduxProvider>
   );

package/template/client/src/components/common/SafeImage.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import type React from 'react';
+
+import Image from 'next/image';
+import type { ImageProps } from 'next/image';
+
+/**
+ * Wraps Next.js <Image> to bypass the optimization proxy for localhost URLs.
+ *
+ * Next.js refuses to fetch images from loopback IPs (127.0.0.1, ::1) through
+ * its optimization proxy — even when remotePatterns allows localhost. This is
+ * a security restriction to prevent SSRF attacks.
+ *
+ * SafeImage detects localhost/loopback URLs and sets `unoptimized` so the
+ * image loads directly via a regular <img> tag. In production with a real
+ * domain, images are optimized normally.
+ */
+
+const LOOPBACK_PATTERNS = [
+  'localhost',
+  '127.0.0.1',
+  '0.0.0.0',
+  '[::1]',
+] as const;
+
+function isLoopbackUrl(src: ImageProps['src']): boolean {
+  if (typeof src !== 'string') return false;
+
+  try {
+    const url = new URL(src);
+    return LOOPBACK_PATTERNS.some((pattern) => url.hostname === pattern);
+  } catch {
+    // Relative path or invalid URL — not a loopback issue
+    return false;
+  }
+}
+
+export const SafeImage = (props: ImageProps): React.ReactElement => {
+  const shouldSkipOptimization = isLoopbackUrl(props.src);
+
+  return (
+    <Image
+      {...props}
+      unoptimized={props.unoptimized || shouldSkipOptimization}
+    />
+  );
+};

package/template/client/src/features/auth/hooks/useAuth.ts

@@ -38,7 +38,7 @@ export const useAuth = (): UseAuthReturn => {
       dispatch(setUser(data.user));
       toast.success('Signed in successfully');
       const from = searchParams.get('from');
-      const redirectTo = from && from.startsWith('/') && !from.startsWith('//') ? from : '/';
+      const redirectTo = from && from.startsWith('/') && !from.startsWith('//') ? from : ROUTES.DASHBOARD;
       router.push(redirectTo);
     },
     onError: (error) => {
@@ -51,7 +51,7 @@ export const useAuth = (): UseAuthReturn => {
     onSuccess: (data) => {
       dispatch(setUser(data.user));
       toast.success('Account created successfully');
-      router.push(ROUTES.HOME);
+      router.push(ROUTES.DASHBOARD);
     },
     onError: (error) => {
       toast.error(getErrorMessage(error));

package/template/client/src/lib/api/axios.config.ts

@@ -9,9 +9,6 @@ const apiClient = axios.create({
   baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:8000/api/v1',
   timeout: 30000,
   withCredentials: true, // Send cookies with every request
-  headers: {
-    'Content-Type': 'application/json',
-  },
 });
 
 // No request interceptor needed — cookies are sent automatically
@@ -46,8 +43,15 @@ apiClient.interceptors.response.use(
       return Promise.reject(error);
     }
 
-    // Don't retry refresh endpoint itself
-    if (originalRequest.url === API_ENDPOINTS.AUTH.REFRESH) {
+    // Don't retry auth endpoints that don't use tokens —
+    // a 401 here means wrong credentials, not an expired token.
+    const noRetryEndpoints = [
+      API_ENDPOINTS.AUTH.LOGIN,
+      API_ENDPOINTS.AUTH.REGISTER,
+      API_ENDPOINTS.AUTH.REFRESH,
+      API_ENDPOINTS.AUTH.RESET_PASSWORD,
+    ];
+    if (noRetryEndpoints.includes(originalRequest.url ?? '')) {
       return Promise.reject(error);
     }
 
@@ -57,6 +61,8 @@ apiClient.interceptors.response.use(
       resetRefreshState();
     }
 
+    originalRequest._retry = true;
+
     if (isRefreshing) {
       return new Promise<void>((resolve, reject) => {
         failedQueue.push({ resolve, reject });
@@ -64,8 +70,6 @@ apiClient.interceptors.response.use(
         return apiClient(originalRequest);
       });
     }
-
-    originalRequest._retry = true;
     isRefreshing = true;
     refreshTimestamp = Date.now();
 
@@ -94,6 +98,9 @@ apiClient.interceptors.response.use(
         store.dispatch(logout());
 
         if (typeof window !== 'undefined') {
+          // Clear session indicator so middleware won't let user through
+          // to protected pages — prevents redirect loops
+          document.cookie = 'auth_session=; Max-Age=0; path=/; SameSite=Strict';
           window.location.href = ROUTES.LOGIN;
         }
       }

package/template/client/src/middleware.ts

@@ -2,8 +2,7 @@ import { NextResponse } from 'next/server';
 
 import type { NextRequest } from 'next/server';
 
-const protectedPaths = ['/', '/dashboard', '/profile', '/admin'];
-const authPaths = ['/login', '/register'];
+const protectedPaths = ['/dashboard', '/profile', '/admin'];
 
 function isTokenExpired(token: string): boolean {
   try {
@@ -17,38 +16,33 @@ function isTokenExpired(token: string): boolean {
 
 export function middleware(request: NextRequest): NextResponse {
   const { pathname } = request.nextUrl;
-  const token = request.cookies.get('access_token')?.value;
+  const accessToken = request.cookies.get('access_token')?.value;
+  const authSession = request.cookies.get('auth_session')?.value;
 
-  const isProtectedPath = protectedPaths.some((path) =>
-    path === '/' ? pathname === '/' : pathname.startsWith(path)
-  );
+  const isProtectedPath = protectedPaths.some((path) => pathname.startsWith(path));
 
-  // No token at all — user is not logged in, redirect to login
-  if (isProtectedPath && !token) {
-    const loginUrl = new URL('/login', request.url);
-    loginUrl.searchParams.set('from', pathname);
-    return NextResponse.redirect(loginUrl);
-  }
-
-  // Expired token on protected path — allow through so client-side can attempt refresh.
-  // Delete the stale access_token so AuthInitializer starts fresh: getMe() → 401 → refresh.
-  if (isProtectedPath && token && isTokenExpired(token)) {
-    const response = NextResponse.next();
-    response.cookies.delete('access_token');
-    return response;
-  }
+  if (isProtectedPath) {
+    // No access_token AND no auth_session — truly unauthenticated
+    if (!accessToken && !authSession) {
+      const loginUrl = new URL('/login', request.url);
+      loginUrl.searchParams.set('from', pathname);
+      return NextResponse.redirect(loginUrl);
+    }
 
-  const isAuthPath = authPaths.some((path) => pathname.startsWith(path));
+    // No access_token BUT auth_session exists — session is alive,
+    // let through so client-side can do getMe() → 401 → refresh → retry
+    if (!accessToken && authSession) {
+      return NextResponse.next();
+    }
 
-  if (isAuthPath && token) {
-    if (isTokenExpired(token)) {
-      // Only delete the expired access token — keep the refresh token
-      // so the client-side interceptor can still recover the session
+    // Expired access_token — delete stale cookie, let through for client-side refresh
+    if (accessToken && isTokenExpired(accessToken)) {
       const response = NextResponse.next();
       response.cookies.delete('access_token');
       return response;
     }
-    return NextResponse.redirect(new URL('/', request.url));
+
+    return NextResponse.next();
   }
 
   return NextResponse.next();
@@ -56,11 +50,8 @@ export function middleware(request: NextRequest): NextResponse {
 
 export const config = {
   matcher: [
-    '/',
     '/dashboard/:path*',
     '/profile/:path*',
     '/admin/:path*',
-    '/login',
-    '/register',
   ],
 };

package/template/server/.env.example

@@ -94,6 +94,15 @@ JWT_REFRESH_EXPIRY="7d"
 # For production: generate a separate secret: openssl rand -base64 48
 # COOKIE_SECRET="change-this-to-a-different-secret-at-least-32-chars"
 
+# Cookie domain for cross-origin deployments
+# REQUIRED when client and API are on different subdomains:
+#   Client: https://app.example.com  |  API: https://api.example.com
+#   → Set COOKIE_DOMAIN=".example.com" (note the leading dot)
+# NOT needed when client and API share the same hostname (local dev, same-origin prod)
+# Without this, cookies are scoped to the API hostname only and the browser
+# will silently reject them on cross-origin requests (login appears to do nothing).
+# COOKIE_DOMAIN=".example.com"
+
 # ===================================================================
 # CORS (Cross-Origin Resource Sharing)
 # ===================================================================

package/template/server/.env.example.production

@@ -80,6 +80,14 @@ JWT_REFRESH_EXPIRY="7d"
 # Multiple origins separated by commas
 CORS_ORIGIN="https://yourdomain.com,https://app.yourdomain.com"
 
+# Cookie domain for cross-origin deployments
+# REQUIRED when client and API are on different subdomains:
+#   Client: https://app.example.com  |  API: https://api.example.com
+#   → Set COOKIE_DOMAIN=".example.com" (leading dot = all subdomains)
+# This enables cookies to be shared between client and API subdomains.
+# Without it, login will silently fail (server returns 200 but browser drops cookies).
+COOKIE_DOMAIN=".yourdomain.com"
+
 # ===================================================================
 # LOGGING
 # ===================================================================
@@ -102,6 +110,7 @@ SENTRY_DSN="https://YOUR_PUBLIC_KEY@o0.ingest.sentry.io/YOUR_PROJECT_ID"
 # [ ] DATABASE_URL uses secure credentials and SSL
 # [ ] JWT_SECRET is a strong random string (48+ chars)
 # [ ] CORS_ORIGIN is set to your exact frontend URL(s)
+# [ ] COOKIE_DOMAIN is set if client and API are on different subdomains
 # [ ] REDIS_URL uses authentication if Redis is exposed
 # [ ] LOG_LEVEL is set to info or warn
 # [ ] SENTRY_DSN is configured for error tracking

package/template/server/src/config/env.ts

@@ -39,6 +39,12 @@ const envSchema = z.object({
   // Separate secret for cookie signing (defaults to JWT_SECRET if not set)
   COOKIE_SECRET: z.string().min(32, 'COOKIE_SECRET must be at least 32 characters').optional(),
 
+  // Cookie domain for cross-origin deployments (client ≠ server hostname)
+  // Required when client and API are on different subdomains (e.g., app.example.com + api.example.com)
+  // Set to the shared parent domain with a leading dot: ".example.com"
+  // Leave empty for same-origin deployments or local development
+  COOKIE_DOMAIN: z.string().optional(),
+
   // --- CORS ---
   // In development: CORS_ORIGIN is optional (allows all origins)
   // In production: REQUIRED for security

package/template/server/src/libs/cookies.ts

@@ -4,6 +4,14 @@ import { parseDurationMs } from '@libs/auth.js';
 
 const isProduction = env.NODE_ENV === 'production';
 
+// Cross-origin deployment: client and API on different subdomains require sameSite 'none'.
+// Same-origin deployment (or local dev): 'strict' is the safest default.
+const isCrossOrigin = Boolean(env.COOKIE_DOMAIN);
+const sameSitePolicy = isProduction && isCrossOrigin ? 'none' as const : 'strict' as const;
+
+// When set, cookies are shared across subdomains (e.g., ".example.com" covers app.example.com + api.example.com)
+const cookieDomain = env.COOKIE_DOMAIN || undefined;
+
 const ACCESS_TOKEN_MAX_AGE_MS = parseDurationMs(env.JWT_ACCESS_EXPIRY, 15 * 60 * 1000);
 const REFRESH_TOKEN_MAX_AGE_MS = parseDurationMs(env.JWT_REFRESH_EXPIRY, 7 * 24 * 60 * 60 * 1000);
 
@@ -15,7 +23,8 @@ export function setAuthCookies(
   reply.setCookie('access_token', accessToken, {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/',
     maxAge: Math.floor(ACCESS_TOKEN_MAX_AGE_MS / 1000), // setCookie expects seconds
   });
@@ -23,24 +32,46 @@ export function setAuthCookies(
   reply.setCookie('refresh_token', refreshToken, {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/api/v1/auth',
     maxAge: Math.floor(REFRESH_TOKEN_MAX_AGE_MS / 1000),
   });
+
+  // Non-sensitive session indicator visible to Next.js middleware and client JS.
+  // Lets middleware distinguish "never logged in" from "access token expired but session alive."
+  reply.setCookie('auth_session', '1', {
+    httpOnly: false,
+    secure: isProduction,
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
+    path: '/',
+    maxAge: Math.floor(REFRESH_TOKEN_MAX_AGE_MS / 1000),
+  });
 }
 
 export function clearAuthCookies(reply: FastifyReply): void {
   reply.clearCookie('access_token', {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/',
   });
 
   reply.clearCookie('refresh_token', {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/api/v1/auth',
   });
+
+  reply.clearCookie('auth_session', {
+    httpOnly: false,
+    secure: isProduction,
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
+    path: '/',
+  });
 }

package/template/client/src/app/(auth)/layout.tsx

@@ -1,18 +0,0 @@
-import type React from 'react';
-
-import { APP_NAME } from '@/lib/constants/app.constants';
-
-export default function AuthLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}): React.ReactElement {
-  return (
-    <div className="flex min-h-dvh flex-col items-center justify-center px-4 py-12">
-      <span className="mb-8 text-xl font-semibold tracking-tight text-foreground">
-        {APP_NAME}
-      </span>
-      {children}
-    </div>
-  );
-}

package/template/client/src/app/(auth)/login/page.tsx

@@ -1,13 +0,0 @@
-import type React from 'react';
-
-import { LoginForm } from '@/features/auth/components/LoginForm';
-
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Sign in',
-};
-
-export default function LoginPage(): React.ReactElement {
-  return <LoginForm />;
-}

package/template/client/src/app/(auth)/register/page.tsx

@@ -1,13 +0,0 @@
-import type React from 'react';
-
-import { RegisterForm } from '@/features/auth/components/RegisterForm';
-
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Create account',
-};
-
-export default function RegisterPage(): React.ReactElement {
-  return <RegisterForm />;
-}

package/template/client/src/app/(main)/dashboard/page.tsx

@@ -1,22 +0,0 @@
-import type React from 'react';
-
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Dashboard',
-};
-
-export default function DashboardPage(): React.ReactElement {
-  return (
-    <div className="container mx-auto px-4 py-12 md:px-6 lg:px-8">
-      <div className="space-y-6">
-        <div>
-          <h1 className="text-3xl font-bold tracking-tight">Dashboard</h1>
-          <p className="mt-2 text-muted-foreground">
-            Welcome to your dashboard. This is where you&apos;ll manage everything.
-          </p>
-        </div>
-      </div>
-    </div>
-  );
-}

package/template/client/src/app/(main)/layout.tsx

@@ -1,11 +0,0 @@
-import type React from 'react';
-
-import { MainLayout } from '@/components/layout/MainLayout';
-
-export default function MainGroupLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}): React.ReactElement {
-  return <MainLayout>{children}</MainLayout>;
-}