npm install @tanstack/react-router @tanstack/router-devtools
npm install -D @tanstack/router-plugin
# Optional: Zod validation adapter
npm install @tanstack/zod-adapter zod

// vite.config.ts
import { TanStackRouterVite } from "@tanstack/router-plugin/vite";

export default defineConfig({
    plugins: [TanStackRouterVite(), react()], // Order matters!
});

src/routes/
├── __root.tsx         → createRootRoute() with <Outlet />
├── index.tsx          → createFileRoute('/')
└── posts.$postId.tsx  → createFileRoute('/posts/$postId')

import { createRouter, RouterProvider } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen' // Auto-generated by plugin

const router = createRouter({ routeTree })
<RouterProvider router={router} />

<Link to="/posts/$postId" params={{ postId: '123' }} />
<Link to="/invalid" /> // ❌ TypeScript error

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => ({ post: await fetchPost(params.postId) }),
  component: ({ useLoaderData }) => {
    const { post } = useLoaderData() // Fully typed!
    return <h1>{post.title}</h1>
  },
})

const postOpts = (id: string) => queryOptions({
  queryKey: ['posts', id],
  queryFn: () => fetchPost(id),
})

export const Route = createFileRoute('/posts/$postId')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData(postOpts(params.postId)),
  component: () => {
    const { postId } = Route.useParams()
    const { data } = useQuery(postOpts(postId))
    return <h1>{data.title}</h1>
  },
})

import { tanstackRouter } from "@tanstack/router-plugin/vite";

export default defineConfig({
    plugins: [
        tanstackRouter({
            target: "react",
            virtualRouteConfig: "./routes.ts", // Point to your routes file
        }),
        react(),
    ],
});

import {
    rootRoute,
    route,
    index,
    layout,
    physical,
} from "@tanstack/virtual-file-routes";

export const routes = rootRoute("root.tsx", [
    index("home.tsx"),
    route("/posts", "posts/posts.tsx", [
        index("posts/posts-home.tsx"),
        route("$postId", "posts/posts-detail.tsx"),
    ]),
    layout("first", "layout/first-layout.tsx", [
        route("/nested", "nested.tsx"),
    ]),
    physical("/classic", "file-based-subtree"), // Mix with file-based
]);

import { z } from "zod";

export const Route = createFileRoute("/products")({
    validateSearch: (search) =>
        z
            .object({
                page: z.number().catch(1),
                filter: z.string().catch(""),
                sort: z.enum(["newest", "oldest", "price"]).catch("newest"),
            })
            .parse(search),
});

import { zodValidator, fallback } from "@tanstack/zod-adapter";
import { z } from "zod";

const searchSchema = z.object({
    query: z.string().min(1).max(100),
    page: fallback(z.number().int().positive(), 1),
    sortBy: z.enum(["name", "date", "relevance"]).optional(),
});

export const Route = createFileRoute("/search")({
    validateSearch: zodValidator(searchSchema),
    // Type-safe: Route.useSearch() returns typed params
});

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId)
    if (!post) throw new Error('Post not found')
    return { post }
  },
  errorComponent: ({ error, reset }) => (
    <div>
      <p>Error: {error.message}</p>
      <button onClick={reset}>Retry</button>
    </div>
  ),
})

const router = createRouter({
  routeTree,
  defaultErrorComponent: ({ error }) => (
    <div className="error-page">
      <h1>Something went wrong</h1>
      <p>{error.message}</p>
    </div>
  ),
})

export const Route = createFileRoute('/posts/$postId')({
  notFoundComponent: () => <div>Post not found</div>,
})

import { redirect } from "@tanstack/react-router";

export const Route = createFileRoute("/dashboard")({
    beforeLoad: async ({ context }) => {
        if (!context.auth.isAuthenticated) {
            throw redirect({
                to: "/login",
                search: { redirect: location.pathname }, // Save for post-login
            });
        }
    },
});

// routes/(authenticated)/route.tsx - protects all children
export const Route = createFileRoute("/(authenticated)")({
    beforeLoad: async ({ context }) => {
        if (!context.auth.isAuthenticated) {
            throw redirect({ to: "/login" });
        }
    },
});

// main.tsx - pass auth state to router
function App() {
  const auth = useAuth() // Your auth hook

  return (
    <RouterProvider
      router={router}
      context={{ auth }} // Available in beforeLoad
    />
  )
}

// Server function with input validation
export const myFn = createServerFn({ method: "POST" })
    .inputValidator(
        z.object({
            name: z.string().min(2),
            age: z.number().min(18),
        }),
    )
    .handler(async ({ data }) => data);

// Client: Workaround to parse stringified issues
try {
    await mutation.mutate({ data: invalidData });
} catch (error) {
    if (error.message.startsWith("[")) {
        const issues = JSON.parse(error.message);
        // Now can use structured error data
        issues.forEach((issue) => {
            console.log(issue.path, issue.message);
        });
    }
}

// Route with param parsing
export const Route = createFileRoute("/posts/$postId")({
    params: {
        parse: (params) => ({
            postId: z.coerce.number().parse(params.postId),
        }),
    },
});

// Component: Use strict mode (default) for parsed params
function Component() {
    const { postId } = useParams(); // ✓ Parsed as number
    // const { postId } = useParams({ strict: false }) // ✗ String!

    // Or manually parse when using strict: false
    const params = useParams({ strict: false });
    const postId = Number(params.postId);
}

// ✗ Doesn't work: notFoundComponent on pathless layout
export const Route = createFileRoute('/(authenticated)')({
  beforeLoad: ({ context }) => {
    if (!context.auth) throw redirect({ to: '/login' })
  },
  notFoundComponent: () => <div>Protected 404</div>, // Not rendered!
})

// ✓ Works: Define on child routes instead
export const Route = createFileRoute('/(authenticated)/dashboard')({
  notFoundComponent: () => <div>Protected 404</div>,
})

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params, abortController }) => {
    await fetch(`/api/posts/${params.postId}`, {
      signal: abortController.signal,
    })
  },
  errorComponent: ({ error, reset }) => {
    // Check for undefined error (aborted request)
    if (!error) {
      return null // Or show loading state
    }
    return <div>Error: {error.message}</div>
  },
})

// Temporary workaround: Comment out tanstackStart() for tests
// vite.config.ts
export default defineConfig({
    plugins: [
        // tanstackStart(), // Disable for tests
        react(),
    ],
    test: { environment: "jsdom" },
});

// ✗ Wrong: void + throw crashes dev server
export const Route = createFileRoute("/posts")({
    loader: async () => {
        void fetch("/api/posts").then((r) => {
            throw new Error("boom"); // Crashes!
        });
    },
});

// ✓ Correct: Always await or catch
export const Route = createFileRoute("/posts")({
    loader: async () => {
        try {
            const data = await fetch("/api/posts");
            return data;
        } catch (error) {
            throw error; // Caught by errorComponent
        }
    },
});

// ✗ Wrong: Empty filter causes hang
tanstackStart({
    prerender: {
        enabled: true,
        filter: (route) => false, // No routes → hangs!
    },
});

// ✓ Correct: Ensure at least one route or disable
tanstackStart({
    prerender: {
        enabled: true,
        filter: (route) =>
            route.path === "/" || route.path.startsWith("/posts"),
    },
});

// Or temporarily disable
tanstackStart({
    prerender: { enabled: false },
});

// vite.config.ts - Make preview server accessible in Docker
export default defineConfig({
    preview: {
        host: true, // Bind to 0.0.0.0 instead of localhost
    },
    plugins: [
        devtools(),
        // nitro({ preset: "bun" }), // Remove temporarily if issues persist
        tanstackStart(),
        react(),
    ],
});

// ✗ Wrong: loaderData may not be available yet
export const Route = createFileRoute("/posts/$postId")({
    loader: async ({ params }) => {
        const post = await fetchPost(params.postId);
        return { post };
    },
    head: ({ loaderData }) => ({
        meta: [
            { title: loaderData.post.title }, // May be undefined!
        ],
    }),
});

// ✓ Correct: Explicitly await if needed
export const Route = createFileRoute("/posts/$postId")({
    loader: async ({ params }) => {
        const post = await fetchPost(params.postId);
        return { post };
    },
    head: async ({ loaderData }) => {
        await loaderData; // Ensure loaded
        return {
            meta: [{ title: loaderData.post.title }],
        };
    },
});

// Virtual routes: Use automatic code splitting
// vite.config.ts
tanstackRouter({
    target: "react",
    virtualRouteConfig: "./routes.ts",
    autoCodeSplitting: true, // Use automatic splitting
});

// Don't use createLazyFileRoute in virtual routes
// It will be replaced with createFileRoute automatically

// ✗ Wrong: NavigateOptions doesn't catch missing params
const options: NavigateOptions = {
    to: "/posts/$postId", // No TS error, but params required!
};

// ✓ Correct: Use useNavigate() return type
const navigate = useNavigate();
type NavigateFn = typeof navigate;
// Now type-safe across all usages

// ✗ Wrong: Missing leading slash
export const Route = createFileRoute("about")({
    /* ... */
});

// ✓ Correct: Always start with /
export const Route = createFileRoute("/about")({
    /* ... */
});

import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
    plugins: [TanStackRouterVite(), react(), cloudflare()],
});

// Worker: functions/api/posts.ts
export async function onRequestGet({ env }) {
    const { results } = await env.DB.prepare("SELECT * FROM posts").all();
    return Response.json(results);
}

// Router: src/routes/posts.tsx
export const Route = createFileRoute("/posts")({
    loader: async () => fetch("/api/posts").then((r) => r.json()),
});