tanstack-start-template: Instructions file for Codex

TanStack Start Agent Guide

Core Philosophy

• Strong end-to-end type safety (database → server → router → client); no any or type casting.
• Server-first, progressively enhanced flows; UI hydrates cleanly but works without JS.
• Performance by design: static imports, parallel data fetching, targeted cache updates.

Architecture

• src/routes/: File-based routes with loaders, guards, pending/error components.
• src/features/: Feature slices with UI, hooks, and server functions (*.server.ts).
• src/lib/server/: Server utilities (database, auth, email, env).
• src/components/ui/: Shadcn/ui primitives and shared components.
• Database access via Convex queries/mutations and setupFetchClient.

Golden Rules

• Keep imports static and synchronous inside server modules; no dynamic imports in server functions.
• One server function, one responsibility. Compose higher-level flows by orchestrating smaller server functions.
• Use Convex queries/mutations for data operations with automatic type generation.
• Reuse provided auth guards (routeAuthGuard, routeAdminGuard, requireAuth, requireAdmin)—do not reimplement session checks.
• Keep UI components pure; business logic lives in hooks or server functions.
• Never commit files with git unless explicitly requested by the user.

Key Patterns

Routes

export const Route = createFileRoute('/app')({
  pendingMs: 150,
  pendingMinMs: 250,
  pendingComponent: ShellSkeleton,
  component: AppLayout,
  errorComponent: DashboardErrorBoundary,
});

function AppLayout() {
  const navigate = useNavigate();
  const location = useLocation();
  const { isAuthenticated, isPending } = useAuth();
  const redirectRef = useRef(false);
  const redirectTarget = location.href ?? '/app';

  useEffect(() => {
    if (isPending) return;

    if (!isAuthenticated) {
      if (redirectRef.current) return;

      redirectRef.current = true;
      void navigate({
        to: '/login',
        search: { redirect: redirectTarget },
        replace: true,
      }).catch(() => {
        redirectRef.current = false;
      });
    } else {
      redirectRef.current = false;
    }
  }, [isAuthenticated, isPending, navigate, redirectTarget]);

  if (isPending || !isAuthenticated) {
    return <ShellSkeleton />;
  }

  return (
    <AppChrome>
      <Outlet />
    </AppChrome>
  );
}