Danijel Martinek
ae456a5436
- AGENTS.md (root): marks core-ui as optional in the package table and boundary rules; points per-package docs to the .hbs template - apps/storybook/AGENTS.md: rewrites around no-core-ui-by-default; stories glob and globals.css import described as post-scaffold steps - apps/web-next/AGENTS.md: cross-reference updated to template file - apps/web-tanstack/AGENTS.md: cross-reference updated to template file - docs/architecture/data-flow-explainer.html: core-ui bullet notes optional status + generator command Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
115 lines
4.0 KiB
Markdown
115 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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`
|