create-tigra 3.0.3 → 3.1.0

package/template/client/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
+    "dev": "node ./scripts/next-dev.cjs",
     "build": "next build",
     "start": "next start",
     "lint": "eslint src/",
@@ -16,11 +16,11 @@
     "@reduxjs/toolkit": "^2.11.2",
     "@sentry/nextjs": "^10.62.0",
     "@tanstack/react-query": "^5.90.21",
-    "axios": "^1.13.5",
+    "axios": "^1.20.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.563.0",
-    "next": "16.2.9",
+    "next": "16.3.5",
     "next-themes": "^0.4.6",
     "radix-ui": "^1.4.3",
     "react": "19.2.3",
@@ -41,7 +41,7 @@
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "eslint": "^9",
-    "eslint-config-next": "16.2.9",
+    "eslint-config-next": "16.3.5",
     "shadcn": "^3.8.4",
     "tailwindcss": "^4",
     "tw-animate-css": "^1.4.0",

package/template/client/scripts/next-dev.cjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("node:child_process");
+
+const DEFAULT_MAX_OLD_SPACE_SIZE = "768";
+const nextBin = require.resolve("next/dist/bin/next");
+
+function applyOldSpaceLimit(nodeOptions, sizeMb) {
+  if (/(^|\s)--max[-_]old[-_]space[-_]size(=|\s|$)/.test(nodeOptions)) {
+    return nodeOptions;
+  }
+
+  return [nodeOptions, `--max-old-space-size=${sizeMb}`].filter(Boolean).join(" ").trim();
+}
+
+const env = { ...process.env };
+env.NEXT_DISABLE_MEM_OVERRIDE = "1";
+env.NODE_OPTIONS = applyOldSpaceLimit(
+  env.NODE_OPTIONS || "",
+  env.NEXT_DEV_MAX_OLD_SPACE_SIZE || DEFAULT_MAX_OLD_SPACE_SIZE,
+);
+
+const args = [
+  nextBin,
+  "dev",
+  "--webpack",
+  "--disable-source-maps",
+  "--no-server-fast-refresh",
+  ...process.argv.slice(2),
+];
+
+const child = spawn(process.execPath, args, { stdio: "inherit", env });
+
+child.on("error", (error) => {
+  console.error(error);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 0);
+});

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

@@ -0,0 +1,9 @@
+import type React from 'react';
+
+export default function AuthRouteLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>): React.ReactElement {
+  return <main className="flex min-h-dvh items-center justify-center p-4">{children}</main>;
+}

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

@@ -0,0 +1,7 @@
+import type React from 'react';
+
+import { RouteLoadingShell } from '@/components/common/RouteLoadingShell';
+
+export default function AuthRouteLoading(): React.ReactElement {
+  return <RouteLoadingShell className="min-h-dvh" />;
+}

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

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

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

@@ -0,0 +1,7 @@
+import type React from 'react';
+
+import { RouteLoadingShell } from '@/components/common/RouteLoadingShell';
+
+export default function MainRouteLoading(): React.ReactElement {
+  return <RouteLoadingShell />;
+}

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

@@ -91,6 +91,7 @@
   html {
     @apply bg-background;
     overflow-x: hidden;
+    scroll-behavior: smooth;
     -webkit-text-size-adjust: 100%;
     text-size-adjust: 100%;
   }
@@ -100,4 +101,7 @@
     overflow-x: hidden;
     touch-action: manipulation;
   }
+  html[data-smooth-navigation="pending"] body {
+    min-height: var(--smooth-navigation-min-height);
+  }
 }

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

@@ -1,11 +1,7 @@
 import type React from 'react';
 
-import { LoadingSpinner } from '@/components/common/LoadingSpinner';
+import { RouteLoadingShell } from '@/components/common/RouteLoadingShell';
 
 export default function Loading(): React.ReactElement {
-  return (
-    <div className="flex min-h-dvh items-center justify-center">
-      <LoadingSpinner size="lg" />
-    </div>
-  );
+  return <RouteLoadingShell className="min-h-dvh" />;
 }

package/template/client/src/app/not-found.tsx

@@ -1,10 +1,9 @@
 import type React from 'react';
 
-import Link from 'next/link';
-
 import { FileQuestion } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
+import { AppLink } from '@/components/common/AppLink';
 import { ROUTES } from '@/lib/constants/routes';
 
 export default function NotFound(): React.ReactElement {
@@ -16,7 +15,7 @@ export default function NotFound(): React.ReactElement {
         The page you're looking for doesn't exist or has been moved.
       </p>
       <Button asChild>
-        <Link href={ROUTES.HOME}>Go home</Link>
+        <AppLink href={ROUTES.HOME}>Go home</AppLink>
       </Button>
     </div>
   );

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

@@ -8,6 +8,7 @@ import { Provider as ReduxProvider } from 'react-redux';
 import { ThemeProvider } from 'next-themes';
 import { Toaster } from 'sonner';
 
+import { SmoothNavigationProvider } from '@/components/common/SmoothNavigationProvider';
 import { store } from '@/store';
 import { AuthInitializer } from '@/features/auth/components/AuthInitializer';
 
@@ -44,9 +45,11 @@ export function Providers({
           enableColorScheme={false}
           nonce={nonce}
         >
-          <AuthInitializer>
-            {children}
-          </AuthInitializer>
+          <SmoothNavigationProvider>
+            <AuthInitializer>
+              {children}
+            </AuthInitializer>
+          </SmoothNavigationProvider>
           <Toaster position="top-right" richColors />
         </ThemeProvider>
       </QueryClientProvider>

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

@@ -0,0 +1,84 @@
+'use client';
+
+import type React from 'react';
+import { forwardRef, useRef } from 'react';
+
+import NextLink, { type LinkProps as NextLinkProps } from 'next/link';
+
+import { useSmoothNavigation } from './SmoothNavigationProvider';
+
+type AnchorProps = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof NextLinkProps>;
+
+export type AppLinkProps = Omit<NextLinkProps, 'scroll'> & AnchorProps;
+
+export const AppLink = forwardRef<HTMLAnchorElement, AppLinkProps>(
+  ({ onClick, onNavigate, ...props }, ref): React.ReactElement => {
+    const { startNavigation } = useSmoothNavigation();
+    const pendingDestinationRef = useRef<string | null>(null);
+
+    return (
+      <NextLink
+        {...props}
+        ref={ref}
+        scroll={false}
+        onClick={(event) => {
+          onClick?.(event);
+          pendingDestinationRef.current = null;
+          if (
+            event.defaultPrevented ||
+            event.button !== 0 ||
+            event.metaKey ||
+            event.ctrlKey ||
+            event.shiftKey ||
+            event.altKey
+          ) {
+            return;
+          }
+
+          const anchor = event.currentTarget;
+          const destination = new URL(anchor.href);
+          const current = new URL(window.location.href);
+          const opensElsewhere = Boolean(anchor.target && anchor.target !== '_self');
+          const isHashOnly =
+            destination.pathname === current.pathname &&
+            destination.search === current.search &&
+            Boolean(destination.hash);
+
+          if (
+            opensElsewhere ||
+            anchor.hasAttribute('download') ||
+            destination.origin !== current.origin ||
+            isHashOnly
+          ) {
+            return;
+          }
+
+          // onNavigate runs after onClick only for client-side navigations. Wait
+          // for it so a consumer can still prevent navigation without briefly
+          // showing a loader or starting the scroll animation.
+          pendingDestinationRef.current = destination.href;
+        }}
+        onNavigate={(event) => {
+          let navigationPrevented = false;
+          onNavigate?.({
+            preventDefault: () => {
+              navigationPrevented = true;
+              event.preventDefault();
+            },
+          });
+          if (navigationPrevented) {
+            pendingDestinationRef.current = null;
+            return;
+          }
+
+          if (pendingDestinationRef.current) {
+            startNavigation(pendingDestinationRef.current);
+            pendingDestinationRef.current = null;
+          }
+        }}
+      />
+    );
+  }
+);
+
+AppLink.displayName = 'AppLink';

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

@@ -1,9 +1,9 @@
 import type React from 'react';
 
-import Link from 'next/link';
 import { FileQuestion } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
+import { AppLink } from './AppLink';
 
 interface EmptyStateProps {
   title: string;
@@ -24,7 +24,7 @@ export const EmptyState = ({
     <p className="mb-4 text-muted-foreground">{description}</p>
     {actionLabel && actionHref && (
       <Button asChild>
-        <Link href={actionHref}>{actionLabel}</Link>
+        <AppLink href={actionHref}>{actionLabel}</AppLink>
       </Button>
     )}
   </div>

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

@@ -3,10 +3,11 @@
 import type React from 'react';
 import { Suspense, useCallback } from 'react';
 
-import { useRouter, useSearchParams, usePathname } from 'next/navigation';
+import { useSearchParams, usePathname } from 'next/navigation';
 import { ChevronLeft, ChevronRight } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
+import { useAppRouter } from '@/hooks/useAppRouter';
 
 interface PaginationProps {
   page: number;
@@ -14,7 +15,7 @@ interface PaginationProps {
 }
 
 const PaginationInner = ({ page, totalPages }: PaginationProps): React.ReactElement => {
-  const router = useRouter();
+  const router = useAppRouter();
   const pathname = usePathname();
   const searchParams = useSearchParams();
 

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

@@ -0,0 +1,21 @@
+import type React from 'react';
+
+import { LoadingSpinner } from './LoadingSpinner';
+import { cn } from '@/lib/utils';
+
+/**
+ * Shared fallback for route transitions that are waiting on server data.
+ * Keep this intentionally generic so feature pages can later replace it with
+ * a layout-matching skeleton without changing the navigation contract.
+ */
+interface RouteLoadingShellProps {
+  className?: string;
+}
+
+export const RouteLoadingShell = ({ className }: RouteLoadingShellProps): React.ReactElement => {
+  return (
+    <div className={cn('flex min-h-[calc(100dvh-8rem)] items-center justify-center p-6', className)}>
+      <LoadingSpinner size="lg" />
+    </div>
+  );
+};

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

@@ -0,0 +1,151 @@
+'use client';
+
+import type React from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+
+import { usePathname, useSearchParams } from 'next/navigation';
+
+import { RouteLoadingShell } from './RouteLoadingShell';
+
+const MAX_SMOOTH_SCROLL_MS = 1500;
+const NAVIGATION_FAILSAFE_MS = 30_000;
+
+interface SmoothNavigationContextValue {
+  startNavigation: (destination: string) => void;
+}
+
+const SmoothNavigationContext = createContext<SmoothNavigationContextValue | null>(null);
+
+interface SmoothNavigationProviderProps {
+  children: React.ReactNode;
+}
+
+export const SmoothNavigationProvider = ({
+  children,
+}: SmoothNavigationProviderProps): React.ReactElement => {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const [isNavigating, setIsNavigating] = useState(false);
+  const animationFrameRef = useRef<number | null>(null);
+  const destinationRef = useRef<string | null>(null);
+  const originRef = useRef<string | null>(null);
+  const navigationTimeoutRef = useRef<number | null>(null);
+  const timeoutRef = useRef<number | null>(null);
+
+  const clearTransitionState = useCallback((): void => {
+    if (animationFrameRef.current !== null) {
+      window.cancelAnimationFrame(animationFrameRef.current);
+      animationFrameRef.current = null;
+    }
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    const root = document.documentElement;
+    delete root.dataset.smoothNavigation;
+    root.style.removeProperty('--smooth-navigation-min-height');
+  }, []);
+
+  const finishNavigation = useCallback((): void => {
+    if (navigationTimeoutRef.current !== null) {
+      window.clearTimeout(navigationTimeoutRef.current);
+      navigationTimeoutRef.current = null;
+    }
+    destinationRef.current = null;
+    originRef.current = null;
+    setIsNavigating(false);
+  }, []);
+
+  const cancelNavigation = useCallback((): void => {
+    finishNavigation();
+    clearTransitionState();
+  }, [clearTransitionState, finishNavigation]);
+
+  const startNavigation = useCallback((destination: string): void => {
+    clearTransitionState();
+
+    const root = document.documentElement;
+    const documentHeight = Math.max(root.scrollHeight, document.body.scrollHeight, root.clientHeight);
+
+    // The route fallback can be shorter than the outgoing page. Preserve its
+    // height until scrolling reaches the top so the browser cannot clamp the
+    // scroll position and turn a smooth transition into an instant jump.
+    root.dataset.smoothNavigation = 'pending';
+    root.style.setProperty('--smooth-navigation-min-height', `${documentHeight}px`);
+
+    window.scrollTo({ top: 0, left: 0, behavior: 'smooth' });
+
+    const startedAt = window.performance.now();
+    const monitorScroll = (): void => {
+      const timedOut = window.performance.now() - startedAt >= MAX_SMOOTH_SCROLL_MS;
+      if (Math.abs(window.scrollY) <= 1 || timedOut) {
+        clearTransitionState();
+        return;
+      }
+      animationFrameRef.current = window.requestAnimationFrame(monitorScroll);
+    };
+
+    animationFrameRef.current = window.requestAnimationFrame(monitorScroll);
+    timeoutRef.current = window.setTimeout(clearTransitionState, MAX_SMOOTH_SCROLL_MS + 100);
+
+    const destinationUrl = new URL(destination, window.location.href);
+    const destinationKey = `${destinationUrl.pathname}${destinationUrl.search}`;
+    const currentKey = `${window.location.pathname}${window.location.search}`;
+    if (destinationKey === currentKey) {
+      return;
+    }
+
+    destinationRef.current = destinationKey;
+    originRef.current = currentKey;
+    setIsNavigating(true);
+    if (navigationTimeoutRef.current !== null) {
+      window.clearTimeout(navigationTimeoutRef.current);
+    }
+    navigationTimeoutRef.current = window.setTimeout(cancelNavigation, NAVIGATION_FAILSAFE_MS);
+  }, [cancelNavigation, clearTransitionState]);
+
+  useEffect(() => {
+    const currentKey = `${pathname}${searchParams.size > 0 ? `?${searchParams.toString()}` : ''}`;
+    if (
+      destinationRef.current === currentKey ||
+      (originRef.current !== null && originRef.current !== currentKey)
+    ) {
+      // The new route can commit before the smooth scroll reaches the top.
+      // Hide the overlay without releasing the preserved document height. A
+      // changed key also handles redirects whose URL differs from the request.
+      finishNavigation();
+    }
+  }, [finishNavigation, pathname, searchParams]);
+
+  useEffect(
+    () => () => {
+      if (navigationTimeoutRef.current !== null) {
+        window.clearTimeout(navigationTimeoutRef.current);
+      }
+      clearTransitionState();
+    },
+    [clearTransitionState]
+  );
+
+  const value = useMemo(() => ({ startNavigation }), [startNavigation]);
+
+  return (
+    <SmoothNavigationContext.Provider value={value}>
+      {children}
+      {isNavigating && (
+        <div className="fixed inset-0 z-40 overflow-hidden bg-background" aria-busy="true">
+          <RouteLoadingShell className="min-h-dvh" />
+        </div>
+      )}
+    </SmoothNavigationContext.Provider>
+  );
+};
+
+export const useSmoothNavigation = (): SmoothNavigationContextValue => {
+  const context = useContext(SmoothNavigationContext);
+  if (!context) {
+    throw new Error('useSmoothNavigation must be used within SmoothNavigationProvider');
+  }
+  return context;
+};

package/template/client/src/components/layout/Header.tsx

@@ -3,11 +3,11 @@
 import type React from 'react';
 import { useState, useCallback, useEffect, useRef } from 'react';
 
-import Link from 'next/link';
 import { useTheme } from 'next-themes';
 import { Sun, Moon, Menu, X, LogOut } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
+import { AppLink } from '@/components/common/AppLink';
 import { useAppSelector } from '@/store/hooks';
 import { useAuth } from '@/features/auth/hooks/useAuth';
 import { APP_NAME } from '@/lib/constants/app.constants';
@@ -50,18 +50,18 @@ export const Header = (): React.ReactElement => {
   return (
     <header className="sticky top-0 z-50 border-b border-border/50 bg-background/80 backdrop-blur-md">
       <div className="container mx-auto flex h-16 items-center justify-between px-4 md:px-6 lg:px-8">
-        <Link
+        <AppLink
           href={ROUTES.HOME}
           className="text-xl font-bold tracking-tight transition-colors duration-150 active:opacity-70 md:hover:text-primary"
         >
           {APP_NAME}
-        </Link>
+        </AppLink>
 
         <nav className="hidden items-center gap-2 md:flex">
           {isAuthenticated ? (
             <>
               <Button variant="ghost" size="sm" asChild>
-                <Link href={ROUTES.DASHBOARD}>Dashboard</Link>
+                <AppLink href={ROUTES.DASHBOARD}>Dashboard</AppLink>
               </Button>
               <span className="text-sm text-muted-foreground">
                 {user?.firstName}
@@ -79,10 +79,10 @@ export const Header = (): React.ReactElement => {
           ) : (
             <>
               <Button variant="ghost" size="sm" asChild>
-                <Link href={ROUTES.LOGIN}>Sign in</Link>
+                <AppLink href={ROUTES.LOGIN}>Sign in</AppLink>
               </Button>
               <Button size="sm" asChild>
-                <Link href={ROUTES.REGISTER}>Get started</Link>
+                <AppLink href={ROUTES.REGISTER}>Get started</AppLink>
               </Button>
             </>
           )}
@@ -134,9 +134,9 @@ export const Header = (): React.ReactElement => {
             {isAuthenticated ? (
               <>
                 <Button variant="ghost" className="w-full justify-start" asChild>
-                  <Link href={ROUTES.DASHBOARD} onClick={closeMobileMenu}>
+                  <AppLink href={ROUTES.DASHBOARD} onClick={closeMobileMenu}>
                     Dashboard
-                  </Link>
+                  </AppLink>
                 </Button>
                 <Button
                   variant="ghost"
@@ -154,14 +154,14 @@ export const Header = (): React.ReactElement => {
             ) : (
               <>
                 <Button variant="ghost" className="w-full justify-start" asChild>
-                  <Link href={ROUTES.LOGIN} onClick={closeMobileMenu}>
+                  <AppLink href={ROUTES.LOGIN} onClick={closeMobileMenu}>
                     Sign in
-                  </Link>
+                  </AppLink>
                 </Button>
                 <Button className="w-full" asChild>
-                  <Link href={ROUTES.REGISTER} onClick={closeMobileMenu}>
+                  <AppLink href={ROUTES.REGISTER} onClick={closeMobileMenu}>
                     Get started
-                  </Link>
+                  </AppLink>
                 </Button>
               </>
             )}

package/template/client/src/features/admin/hooks/useAdminSessions.ts

@@ -1,9 +1,9 @@
 'use client';
 
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { useRouter } from 'next/navigation';
 import { toast } from 'sonner';
 
+import { useAppRouter } from '@/hooks/useAppRouter';
 import { getErrorMessage } from '@/lib/utils/error';
 import { adminService } from '../services/admin.service';
 import { adminKeys } from './useAdminUsers';
@@ -49,7 +49,7 @@ interface UseForceExpireSessionReturn {
 
 export const useForceExpireSession = (): UseForceExpireSessionReturn => {
   const queryClient = useQueryClient();
-  const router = useRouter();
+  const router = useAppRouter();
 
   const mutation = useMutation({
     mutationFn: (sessionId: string) => adminService.deleteSession(sessionId),

package/template/client/src/features/admin/hooks/useAdminUsers.ts

@@ -1,9 +1,9 @@
 'use client';
 
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { useRouter } from 'next/navigation';
 import { toast } from 'sonner';
 
+import { useAppRouter } from '@/hooks/useAppRouter';
 import { getErrorMessage } from '@/lib/utils/error';
 import { adminService } from '../services/admin.service';
 
@@ -82,7 +82,7 @@ interface UseUpdateUserStatusReturn {
 
 export const useUpdateUserStatus = (): UseUpdateUserStatusReturn => {
   const queryClient = useQueryClient();
-  const router = useRouter();
+  const router = useAppRouter();
 
   const mutation = useMutation({
     mutationFn: ({ userId, isActive }: { userId: string; isActive: boolean }) =>
@@ -114,7 +114,7 @@ interface UseUpdateUserRoleReturn {
 
 export const useUpdateUserRole = (): UseUpdateUserRoleReturn => {
   const queryClient = useQueryClient();
-  const router = useRouter();
+  const router = useAppRouter();
 
   const mutation = useMutation({
     mutationFn: ({ userId, role }: { userId: string; role: 'USER' | 'ADMIN' }) =>

package/template/client/src/features/auth/components/AuthInitializer.tsx

@@ -3,11 +3,12 @@
 import type React from 'react';
 import { useEffect } from 'react';
 
-import { usePathname, useRouter } from 'next/navigation';
+import { usePathname } from 'next/navigation';
 
 import { toast } from 'sonner';
 
 import { useAppSelector } from '@/store/hooks';
+import { useAppRouter } from '@/hooks/useAppRouter';
 import { ROUTES } from '@/lib/constants/routes';
 import { isErrorCode, ERROR_CODES } from '@/lib/utils/error';
 import { useCurrentUser } from '../hooks/useCurrentUser';
@@ -37,7 +38,7 @@ interface HttpLikeError {
 
 export const AuthInitializer = ({ children }: AuthInitializerProps): React.ReactElement => {
   const pathname = usePathname();
-  const router = useRouter();
+  const router = useAppRouter();
   const { isLoggingOut } = useAppSelector((state) => state.auth);
 
   // Skip getMe() on auth pages and during logout.