agentic-dev-template/apps/web-tanstack/AGENTS.md

AGENTS.md — apps/web-tanstack

TanStack Start reference application using TanStack Router with file-based routing. Demonstrates that feature packages are framework-agnostic by consuming the same features as Next.js (via @repo/core-api) using TanStack's architecture instead.

Purpose

Proof that features are framework-portable. This app consumes the exact same feature packages as apps/web-next, but through TanStack Start's server/client architecture instead of Next.js App Router. Once @repo/core-trpc is scaffolded, it can use the same tRPC routers via TanstackTrpcProvider.

Port: 3002

pnpm dev --filter @repo/web-tanstack   # http://localhost:3002

When @repo/core-trpc is installed, this app requires a tRPC endpoint (from apps/web-next):

pnpm dev --filter @repo/web-next       # Serves tRPC at http://localhost:3000/api/trpc
pnpm dev --filter @repo/web-tanstack   # http://localhost:3002

Key Files

File	Purpose
src/routes/__root.tsx	Root layout — wraps all routes with <Outlet /> (add <TanstackTrpcProvider> after scaffolding @repo/core-trpc)
src/routes/index.tsx	Home page (/)
src/routes/blog/index.tsx	Blog listing (/blog)
src/routes/blog/$slug.tsx	Dynamic blog post (/blog/:slug)
e2e/	Playwright end-to-end tests

File-Based Routing

TanStack Router uses file-based routing where file paths map directly to URL routes:

File	URL
src/routes/__root.tsx	Root (all routes)
src/routes/index.tsx	/
src/routes/blog/index.tsx	/blog
src/routes/blog/$slug.tsx	/blog/:slug

Naming conventions:

• __root.tsx — special root layout
• index.tsx — index route for its directory
• $paramName.tsx — dynamic segment

tRPC Setup (optional)

@repo/core-trpc is not installed by default. After scaffolding with pnpm turbo gen core-package trpc:

1. Update src/routes/__root.tsx:

import { Outlet, createRootRoute } from "@tanstack/react-router";
import { TanstackTrpcProvider } from "@repo/core-trpc/tanstack";

export const Route = createRootRoute({
  component: () => (
    <TanstackTrpcProvider trpcUrl="http://localhost:3000/api/trpc">
      <Outlet />
    </TanstackTrpcProvider>
  ),
});

Note: trpcUrl must point to a running tRPC endpoint (e.g., from apps/web-next).

2. Fetch data in routes:

import { createFileRoute } from "@tanstack/react-router";
import { useTRPC } from "@repo/core-trpc";
import { useQuery } from "@tanstack/react-query";

export const Route = createFileRoute("/blog/$slug")({
  component: BlogPostPage,
});

function BlogPostPage() {
  const { slug } = Route.useParams();
  const trpc = useTRPC();
  const { data, isLoading } = useQuery(trpc.blog.getBySlug.queryOptions({ slug }));
  if (isLoading) return <p>Loading...</p>;
  return <article>{data?.title}</article>;
}

Dependencies

Dependency	Purpose
@repo/core-api	AppRouter type
@repo/core-trpc/tanstack	TanStack tRPC client + provider (optional — scaffold first)
@repo/core-ui	Design system components (optional — scaffold first)
@tanstack/react-router	File-based routing
@tanstack/react-query	Data fetching + caching
react / react-dom	React 19 runtime

Test conventions

• e2e tests in e2e/ folder: *.spec.ts
• Playwright config in e2e/playwright.config.ts
• Run: pnpm test:e2e (both Next.js and TanStack)

Parallel to apps/web-next e2e: validates that features work across frameworks.

Cross-References

• Feature packages: packages/{auth,blog,media,marketing-pages,navigation}/
• tRPC composition: packages/core-api/AGENTS.md
• tRPC client + provider (optional): scaffold @repo/core-trpc first, then see turbo/generators/templates/core-package/trpc/AGENTS.md.hbs
• UI components (optional): scaffold with pnpm turbo gen core-package ui, then see turbo/generators/templates/core-package/ui/AGENTS.md.hbs
• Next.js app (serves tRPC): apps/web-next/AGENTS.md