TanStack Start

"overrides": {
  "vite": "8.2.2",
  "@tanstack/react-query": "5.101.4",
  "@tanstack/query-core": "5.101.4",
  "@tanstack/react-router-ssr-query": "1.167.1",
  "@tanstack/react-router": "1.170.31",
  "@tanstack/react-start": "1.168.48",
  "@tanstack/router-core": "1.171.26",
  "@tanstack/start-client-core": "1.170.26",
  "@tanstack/start-server-core": "1.169.30"
}

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

export default rootRoute("__root.tsx", [
  // better-auth's endpoints, outside the signed-in layout.
  route("/api/auth/$", "api/auth/$.ts"),
  // A pathless LAYOUT, not `route("/")`: the product mounts its own index at `/`,
  // and two routes with that id fail at router construction.
  layout("app/route.tsx", [
    // App-owned: a route that needs a package the product may not import.
    route("/members", "app/members.tsx"),
    physical("", "../../../product/src/routes"),
  ]),
]);

import { makeQueryClient } from "@acme/api/query-client";
import { createRouter } from "@tanstack/react-router";
import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
import { DefaultErrorComponent } from "./default-error";
import { routeTree } from "./routeTree.gen";

export const getRouter = () => {
  const queryClient = makeQueryClient();
  const router = createRouter({
    routeTree,
    context: { queryClient },
    scrollRestoration: true,
    defaultPreloadStaleTime: 0,
    defaultErrorComponent: DefaultErrorComponent,
  });
  setupRouterSsrQueryIntegration({ router, queryClient });
  return router;
};

export function productQueryKey<
  const Product extends string,
  const Parts extends readonly unknown[],
>(product: Product, ...parts: Parts): readonly ["acme", 1, Product, ...Parts] {
  return ["acme", 1, product, ...parts];
}

import { productQueryKey } from "@acme/api/query-key";
import { queryOptions } from "@tanstack/react-query";

export const projectKeys = {
  all: () => productQueryKey("projects", "projects"),
  list: () => [...projectKeys.all(), "list"] as const,
  activity: () => [...projectKeys.all(), "activity"] as const,
};

const getProjectServer = () => import("../server/api.server");

export const projectsQueryOptions = () =>
  queryOptions({
    queryKey: projectKeys.list(),
    queryFn: async () => {
      const { listProjects } = await getProjectServer();
      return listProjects();
    },
    staleTime: 30_000,
  });

export const activityQueryOptions = () =>
  queryOptions({
    queryKey: projectKeys.activity(),
    queryFn: async () => {
      const { listActivity } = await getProjectServer();
      return listActivity();
    },
    staleTime: 30_000,
  });

import { useSuspenseQuery } from "@tanstack/react-query";
import { createFileRoute } from "@tanstack/react-router";
import {
  ActivitySection,
  activityQueryOptions,
  ProjectForm,
  ProjectList,
  ProjectListSkeleton,
  projectsQueryOptions,
} from "../../features/projects";

export const Route = createFileRoute("/_route/projects/")({
  head: () => ({ meta: [{ title: "Projects" }] }),
  loader: async ({ context: { queryClient } }) => {
    // Streamed: started here, NOT awaited. Its section suspends until the read lands.
    void queryClient.prefetchQuery(activityQueryOptions());
    // The frame: awaited (with Promise.all when there are several), so it is in the first HTML.
    await queryClient.ensureQueryData(projectsQueryOptions());
  },
  // On a client-side navigation: nothing for 300ms (under that it reads as instant), then the
  // skeleton for at least 300ms (so a loader landing at 320ms cannot strobe).
  pendingMs: 300,
  pendingMinMs: 300,
  pendingComponent: ProjectsPending,
  component: ProjectsPage,
});

function ProjectsPage() {
  const { data: projects } = useSuspenseQuery(projectsQueryOptions());
  return (
    <>
      <h1 className="font-semibold text-2xl">Projects</h1>
      <ProjectList projects={projects} />
      <ActivitySection />
      <ProjectForm />
    </>
  );
}

function ProjectsPending() {
  return (
    <>
      <h1 className="font-semibold text-2xl">Projects</h1>
      <ProjectListSkeleton />
    </>
  );
}

export const Route = createFileRoute("/_route/projects/$projectId")({
  loader: async ({ context, params }) => {
    const [project] = await Promise.all([
      context.queryClient.ensureQueryData(projectQueryOptions(params.projectId)),
      // The header's Publish button reads it, so it is loaded with the project
      // rather than fetched on hydration.
      context.queryClient.ensureQueryData(projectReadinessQueryOptions(params.projectId)),
      context.queryClient.ensureQueryData(labelsQueryOptions()),
    ]);
    return { crumb: project?.name ?? "Project" };
  },
  component: ProjectLayout,
});

/** Who is looking: the person, their sign-in and their active organization. */
export function viewerOf(client: QueryClient): string {
  const current = client.getQueryData<SessionIdentity>(sessionQueryKey);
  return hashKey([
    current?.user?.id ?? null,
    current?.session?.id ?? null,
    current?.session?.activeOrganizationId ?? null,
  ]);
}

/** A cached result's identity carries the viewer; prefix matching still uses the key alone. */
export function viewerQueryHash(client: QueryClient, key: QueryKey): string {
  return isSession(key) ? hashKey(key) : hashKey([viewerOf(client), key]);
}

/**
 * On a change of person, before anything renders the new session: cancel and remove every
 * private query, so an answer still in flight lands nowhere, and clear the mutation cache, so
 * a write that finishes late cannot invalidate the next person's data.
 */
export function forgetViewer(client: QueryClient): void {
  const privateQueries = {
    predicate: (query: { queryKey: QueryKey }) => !isSession(query.queryKey),
  };
  void client.cancelQueries(privateQueries);
  client.removeQueries(privateQueries);
  client.getMutationCache().clear();
}

/** Installed by `makeQueryClient`, before any seeding or hydration. */
export function watchViewer(client: QueryClient): () => void {
  let viewer = viewerOf(client);
  return client.getQueryCache().subscribe(({ query }) => {
    if (!isSession(query.queryKey)) return;
    const next = viewerOf(client);
    if (next === viewer) return;
    viewer = next;
    forgetViewer(client);
  });
}

declare module "@tanstack/react-query" {
  interface Register {
    mutationMeta: {
      success?: ToastContent;
      error?: ToastContent;
      silentSuccess?: boolean;
      /** Matches like `invalidateQueries`: a key invalidates its whole subtree. */
      invalidates?: readonly QueryKey[];
    };
  }
}

/** One client per server request: `getRouter` calls this, never module scope. */
export function makeQueryClient(): QueryClient {
  const queryClient: QueryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60_000,
        // Every result but the session's is cached under the viewer who asked for it.
        queryKeyHashFn: (key) => viewerQueryHash(queryClient, key),
      },
    },
    mutationCache: new MutationCache({
      onSuccess: async (_data, _variables, _result, mutation, { client }) => {
        // Cleared by a change of person while in flight: it belongs to the previous viewer.
        const cleared = !client
          .getMutationCache()
          .getAll()
          .some((current) => current.mutationId === mutation.mutationId);
        if (cleared) return;
        if (!mutation.meta?.silentSuccess) {
          notify.success(
            mutation.meta?.success ?? {
              title: "Done",
              description: "Your changes were saved.",
            },
          );
        }
        const invalidates = mutation.meta?.invalidates ?? [];
        // Returned so the mutation stays pending until the refetches settle —
        // callers awaiting `mutateAsync` see fresh data, not a stale flash.
        return Promise.all(
          invalidates.map((queryKey) => client.invalidateQueries({ queryKey })),
        );
      },
      onError: (error, _variables, _result, mutation) => {
        // "no active organisation: select or create one first" reads very
        // differently from a generic retry.
        const cause = error instanceof Error ? error.message : "";
        const declared = mutation.meta?.error;
        notify.error(
          declared
            ? {
                title: declared.title,
                description:
                  declared.description || cause || "Please try again.",
              }
            : {
                title: "Something went wrong",
                description: cause || "Please try again.",
              },
        );
      },
    }),
  });
  watchViewer(queryClient);
  return queryClient;
}

import { useMutation } from "@tanstack/react-query";
import type { CreateProjectRequest } from "../../../lib/sdk/projects/schemas";
import { projectKeys } from "../core/queries";

const getProjectServer = () => import("../server/api.server");

export function useProjectsController() {
  const create = useMutation({
    mutationFn: async (input: CreateProjectRequest) => {
      const { createProject } = await getProjectServer();
      return createProject({ data: input });
    },
    meta: {
      success: { title: "Project created", description: "" },
      error: { title: "Failed to create project", description: "" },
      invalidates: [projectKeys.all()],
    },
  });
  return { create };
}

test("initial route reads cannot opt out of SSR or silently fall back after a failed prefetch", () => {
  for (const file of [...routeFiles, ...loaderFiles]) {
    const source = readFileSync(root + file, "utf8");
    expect(source, file).not.toMatch(/ssr:\s*(?:false|["']data-only["'])/);
    expect(source, file).not.toMatch(/await\s+[\w.]*\.prefetchQuery\(/);
    expect(source, file).not.toMatch(/if\s*\(typeof window !== ["']undefined["']\) return/);
  }
});

/**
 * A streamed section: the loader started its read without waiting, the server sends the
 * skeleton first and the list when the read lands. A failed read shows its own error here;
 * the rest of the page stays.
 */
export function ActivitySection() {
  return (
    <section aria-labelledby="activity-heading" className="grid gap-3">
      <h2 id="activity-heading" className="font-semibold">
        Recent activity
      </h2>
      <CatchBoundary
        getResetKey={() => "activity"}
        errorComponent={ActivityError}
      >
        <Suspense fallback={<ActivitySkeleton />}>
          <ActivityList />
        </Suspense>
      </CatchBoundary>
    </section>
  );
}

function ActivityList() {
  const { data: activity } = useSuspenseQuery(activityQueryOptions());
  return (
    <ul className="divide-y">
      {activity.map((entry) => (
        <li key={entry.id} className="h-10 py-2">
          {entry.text}
        </li>
      ))}
    </ul>
  );
}

/** The list's own shape: same rows, same height, so nothing moves when the data lands. */
function ActivitySkeleton() {
  return (
    <ul
      aria-busy="true"
      aria-label="Loading recent activity"
      className="divide-y"
    >
      {["one", "two", "three"].map((row) => (
        <li key={row} className="h-10 py-2">
          <Skeleton className="h-5 w-2/3" />
        </li>
      ))}
    </ul>
  );
}

function ActivityError() {
  return (
    <p role="alert" className="text-destructive text-sm">
      Recent activity could not be loaded.
    </p>
  );
}

import { requireSession } from "@acme/auth/session.server";
import { createServerFn } from "@tanstack/react-start";
import { sdk } from "../../../lib/api/projects.server";
import { createProjectRequestSchema } from "../../../lib/sdk/projects/schemas";

// Each handler checks the session itself: the route's gate is not the authority.
export const listProjects = createServerFn({ method: "GET" }).handler(
  async () => {
    await requireSession();
    return sdk().projects.list();
  },
);

export const listActivity = createServerFn({ method: "GET" }).handler(
  async () => {
    await requireSession();
    return sdk().activity.list();
  },
);

export const createProject = createServerFn({ method: "POST" })
  .inputValidator(createProjectRequestSchema)
  .handler(async ({ data }) => {
    await requireSession();
    return sdk().projects.create(data);
  });

// Auto-generated Zod schemas - do not edit manually
import { z } from "zod";

export const taskStatusSchema = z.enum(["todo", "in_progress", "done"]);
export type TaskStatus = z.infer<typeof taskStatusSchema>;

export const createTaskRequestSchema = z.object({
  title: z.string(),
  assigneeId: z.string().optional(),
  dueDate: z.string().optional(),
});

import { createServiceSdk } from "@acme/api/service-sdk";
import { getRequest } from "@tanstack/react-start/server";
import { ApiRequestError, Client } from "../sdk/projects";

/** The Projects service as the signed-in viewer. */
export const sdk = createServiceSdk({
  product: "Projects",
  serviceUrl: () => (process.env.SERVICE_URL ?? "http://localhost:8090").replace(/\/+$/, ""),
  request: getRequest,
  client: (baseUrl, options) => new Client(baseUrl, options),
});
export { ApiRequestError };

async function execute(steps: Step[]): Promise<unknown> {
  const request = options.request();
  // One key for the logical call: a retry is the same write, never a second one.
  const idempotencyKey = crypto.randomUUID();
  const token = await serviceToken(request);
  try {
    return await run(token, idempotencyKey, steps);
  } catch (error) {
    if (!isRefusedToken(error)) throw error;
    await forgetServiceToken(request, token);
    return await run(await serviceToken(request), idempotencyKey, steps);
  }
}

export class ApiRequestError extends Error {
  code: string;
  details?: Record<string, unknown>;
  /** The HTTP status the service answered with, when the error came from a response. */
  status?: number;
  constructor(
    message: string,
    code: string,
    details?: Record<string, unknown>,
    status?: number,
  ) {
    super(message);
    this.name = "ApiRequestError";
    this.code = code;
    this.details = details;
    this.status = status;
  }
}

onError: (error, _variables, _result, mutation) => {
  // "no active organisation: select or create one first" reads very
  // differently from a generic retry.
  const cause = error instanceof Error ? error.message : "";
  const declared = mutation.meta?.error;
  notify.error(
    declared
      ? {
          title: declared.title,
          description:
            declared.description || cause || "Please try again.",
        }
      : {
          title: "Something went wrong",
          description: cause || "Please try again.",
        },
  );
},

import { betterAuth } from "better-auth";
import { memoryAdapter } from "better-auth/adapters/memory";
import { organization } from "better-auth/plugins";
import { tanstackStartCookies } from "better-auth/tanstack-start";

/**
 * The one better-auth server. Server-only: the catch-all API route imports it lazily, and
 * server functions read the session through it. Nothing else talks to identity.
 */
export const auth = betterAuth({
  baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:3000",
  secret: process.env.BETTER_AUTH_SECRET,
  // A real app passes its database adapter (drizzle, prisma, …); memory keeps the example small.
  database: memoryAdapter({}),
  session: {
    // The resolved session rides a short-lived signed cookie, so a request reads identity from
    // the cookie instead of the database; better-auth refreshes it when the session changes.
    cookieCache: { enabled: true, maxAge: 5 * 60 },
  },
  plugins: [
    organization(),
    // Must be last: it writes better-auth's cookies into TanStack Start's response.
    tanstackStartCookies(),
  ],
});

export type Session = typeof auth.$Infer.Session;

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

// `auth` is imported inside the handlers: a top-level import would put better-auth's server
// and its database driver in the client bundle, because this file is in the route tree.
const handle = async ({ request }: { request: Request }) =>
  (await import("@acme/auth/auth.server")).auth.handler(request);

export const Route = createFileRoute("/api/auth/$")({
  server: { handlers: { GET: handle, POST: handle } },
});

/** In the browser, through better-auth's client. Only a 401 means "signed out". */
async function fetchSession(): Promise<Session | null> {
  const { authClient } = await import("./auth-client");
  const { data, error } = await authClient.getSession();
  if (error?.status === 401) return null;
  if (error) throw new Error(error.message ?? "The session could not be read.");
  return data as Session | null;
}

/**
 * The session is a query: the root route seeds it on the server, so the first HTML already
 * knows who is signed in and the browser starts with it (no signed-out flash).
 */
export const sessionQueryOptions = () =>
  queryOptions({
    queryKey: sessionQueryKey,
    queryFn: async () =>
      typeof window === "undefined"
        ? (await import("./session.server")).getServerSession()
        : fetchSession(),
    staleTime: 5 * 60_000,
  });

import { sessionQueryOptions } from "@acme/auth/session";
import { ViewerBoundary } from "@acme/auth/viewer-boundary";
import type { QueryClient } from "@tanstack/react-query";
import {
  createRootRouteWithContext,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";
import type { ReactNode } from "react";

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient;
}>()({
  // The session is read on the server, through better-auth with the request's cookie, and
  // seeded into the cache: the first HTML knows who is signed in and the browser reuses it.
  beforeLoad: async ({ context }) => {
    await context.queryClient.ensureQueryData(sessionQueryOptions());
  },
  head: () => ({
    meta: [
      { charSet: "utf-8" },
      { name: "viewport", content: "width=device-width, initial-scale=1" },
    ],
  }),
  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <ViewerBoundary>{children}</ViewerBoundary>
        <Scripts />
      </body>
    </html>
  );
}

import { sessionQueryOptions } from "@acme/auth/session";
import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";

export const Route = createFileRoute("/_route")({
  // The gate runs on the server for the first request: a signed-out person is redirected
  // before any page renders. `ensureQueryData` asks better-auth when the cache has no answer,
  // so a gate never mistakes an empty cache for "signed out".
  beforeLoad: async ({ context }) => {
    const session = await context.queryClient.ensureQueryData(
      sessionQueryOptions(),
    );
    if (!session) throw redirect({ href: "/sign-in" });
  },
  component: AppLayout,
});

function AppLayout() {
  return (
    <main className="mx-auto grid max-w-3xl gap-6 p-6">
      <Outlet />
    </main>
  );
}

import { redirect } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { getRequest } from "@tanstack/react-start/server";
import { auth } from "./auth.server";

/** better-auth reads the incoming request's cookie: null when nobody is signed in. */
export const getServerSession = createServerFn({ method: "GET" }).handler(() =>
  auth.api.getSession({ headers: getRequest().headers }),
);

/**
 * Every server function calls this itself, first. A gate on the route only decides what the
 * page shows; it is not the authority, because a server function can be called without it.
 */
export async function requireSession() {
  const session = await auth.api.getSession({ headers: getRequest().headers });
  if (!session) throw redirect({ href: "/sign-in" });
  return session;
}

/**
 * better-auth signals every change it makes — sign-in, sign-out, an organization switch. The
 * session query forgets the previous person first (which clears their private queries), then
 * reads the new one.
 */
export async function followSessionSignal(client: QueryClient) {
  const { authClient } = await import("./auth-client");
  return authClient.$store.atoms.$sessionSignal.listen(() => {
    void client.cancelQueries({ queryKey: sessionQueryKey, exact: true });
    client.setQueryData(sessionQueryKey, null);
    void client
      .fetchQuery({ ...sessionQueryOptions(), staleTime: 0 })
      .catch(() => undefined); // still signed out in the cache: private data stays cleared
  });
}

import { sessionQueryKey, viewerOf } from "@acme/api/viewer";
import { useQueryClient } from "@tanstack/react-query";
import {
  Fragment,
  type ReactNode,
  useEffect,
  useSyncExternalStore,
} from "react";
import { followSessionSignal } from "./session";

/**
 * Remounts the page when the person changes, so no mounted component keeps showing what it
 * read for the previous one, and follows better-auth's session signal in the browser.
 */
export function ViewerBoundary({ children }: { children: ReactNode }) {
  const client = useQueryClient();
  const viewer = useSyncExternalStore(
    (onChange) =>
      client.getQueryCache().subscribe(({ query }) => {
        if (query.queryKey[0] === sessionQueryKey[0]) onChange();
      }),
    () => viewerOf(client),
    () => viewerOf(client),
  );
  useEffect(() => {
    const stop = followSessionSignal(client);
    return () => void stop.then((unsubscribe) => unsubscribe());
  }, [client]);
  return <Fragment key={viewer}>{children}</Fragment>;
}

import { z } from "zod";
import type { ProjectDraft } from "./draft";

type ProjectField = {
  path: "identity.name" | "trackerRef.system" | "trackerRef.issueId";
  label: string;
  required?: boolean;
};

const trackerRefSchema = z
  .object({ system: z.string().trim(), issueId: z.string().trim() })
  .refine((ref) => (ref.system === "") === (ref.issueId === ""), {
    message:
      "A tracker link needs both the system and the issue id, or neither.",
    path: ["issueId"],
  });

/** The form as data: the renderer draws its sections; the schema checks the draft. */
export const projectDefinition: {
  id: string;
  schema: z.ZodType<ProjectDraft, ProjectDraft>;
  sections: { title: string; fields: ProjectField[] }[];
} = {
  id: "project",
  schema: z.object({
    identity: z.object({
      name: z.string().trim().min(1, "A project needs a name."),
    }),
    trackerRef: trackerRefSchema,
  }),
  sections: [
    {
      title: "Project",
      fields: [{ path: "identity.name", label: "Name", required: true }],
    },
    {
      title: "Tracker link",
      fields: [
        { path: "trackerRef.system", label: "System" },
        { path: "trackerRef.issueId", label: "Issue id" },
      ],
    },
  ],
};

import type { CreateProjectRequest } from "../../../lib/sdk/projects/schemas";

export interface ProjectDraft {
  identity: { name: string };
  trackerRef: { system: string; issueId: string };
}

export function emptyProjectDraft(): ProjectDraft {
  return { identity: { name: "" }, trackerRef: { system: "", issueId: "" } };
}

/** Half a pair points nowhere, so it travels only when both halves are filled in. */
export function createProjectInput(draft: ProjectDraft): CreateProjectRequest {
  const system = draft.trackerRef.system.trim();
  const issueId = draft.trackerRef.issueId.trim();
  const linked = system !== "" && issueId !== "";
  return {
    name: draft.identity.name.trim(),
    ...(linked ? { trackerSystem: system, trackerIssueId: issueId } : {}),
  };
}

import { Button } from "@acme/ui/button";
import { Input } from "@acme/ui/input";
import { useForm } from "@tanstack/react-form";
import { projectDefinition } from "../form/definition";
import { createProjectInput, emptyProjectDraft } from "../form/draft";
import { useProjectsController } from "../hooks/use-projects-controller";

export function ProjectForm() {
  const { create } = useProjectsController();
  const form = useForm({
    defaultValues: emptyProjectDraft(),
    validators: { onSubmit: projectDefinition.schema },
    onSubmit: async ({ value, formApi }) => {
      await create.mutateAsync(createProjectInput(value));
      formApi.reset();
    },
  });

  return (
    <form
      className="grid gap-6"
      onSubmit={(event) => {
        event.preventDefault();
        void form.handleSubmit();
      }}
    >
      {projectDefinition.sections.map((section) => (
        <fieldset key={section.title} className="grid gap-3">
          <legend className="font-semibold">{section.title}</legend>
          {section.fields.map((field) => (
            <form.Field key={field.path} name={field.path}>
              {(input) => (
                <Input
                  label={field.label}
                  required={field.required}
                  value={input.state.value}
                  onBlur={input.handleBlur}
                  onChange={(event) => input.handleChange(event.target.value)}
                  error={input.state.meta.errors
                    .map((issue) => issue?.message)
                    .join(" ")}
                />
              )}
            </form.Field>
          ))}
        </fieldset>
      ))}
      <form.Subscribe selector={(state) => state.isSubmitting}>
        {(isSubmitting) => (
          <Button type="submit" disabled={isSubmitting}>
            Create project
          </Button>
        )}
      </form.Subscribe>
    </form>
  );
}

const form = useForm({
  defaultValues: { email: "", name: "" },
  onSubmit: async (values) => { await saveData(values) },
})

<form.Form>
  <form.Input name="email" label="Email" />
  <Button type="submit" disabled={form.isSubmitting}>Save</Button>
</form.Form>