# AGENTS.md — apps/web-next

Next.js 15 reference application using App Router. Demonstrates consuming feature packages via tRPC and importing UI components from `@repo/core-ui`. Both `@repo/core-trpc` and `@repo/core-ui` are optional packages — scaffold them with `pnpm turbo gen core-package trpc` / `ui` if needed.

## Purpose

Thin app showcasing how features work end-to-end. Business logic lives in feature packages (`@repo/auth`, `@repo/blog`, etc.); UI primitives live in `@repo/core-ui`; this app is mostly routes, layouts, and component composition.

## Port: 3000

```bash
pnpm dev --filter @repo/web-next   # http://localhost:3000
```

Requires `@repo/cms` and PostgreSQL running to fetch live data:

```bash
docker compose up -d postgres       # PostgreSQL on port 5432
pnpm dev --filter @repo/cms        # Payload admin on port 3001
pnpm dev --filter @repo/web-next   # Next.js on port 3000
```

## Key Files

| File | Purpose |
|---|---|
| `src/app/layout.tsx` | Root layout — wraps app with `<Providers>` |
| `src/app/providers.tsx` | Client component wrapper (add tRPC/React Query here after scaffolding `@repo/core-trpc`) |
| `src/app/page.tsx` | Home page — navigation + marketing content |
| `src/app/blog/[slug]/page.tsx` | Dynamic blog post route |
| `e2e/` | Playwright end-to-end tests |

## tRPC Setup (optional)

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

1. Create `src/app/api/trpc/[trpc]/route.ts`:

```typescript
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
import { appRouter } from "@repo/core-api";
import { bindAll } from "../../../../server/bind-production";

const handler = async (req: Request) => {
  await bindAll();
  return fetchRequestHandler({
    endpoint: "/api/trpc",
    req,
    router: appRouter,
    createContext: () => ({}),
  });
};

export { handler as GET, handler as POST };
```

2. Update `src/app/providers.tsx`:

```typescript
"use client";
import { NextTrpcProvider } from "@repo/core-trpc/next";

export function Providers({ children }: { children: React.ReactNode }) {
  return <NextTrpcProvider trpcUrl="/api/trpc">{children}</NextTrpcProvider>;
}
```

## Dependencies

| Dependency | Purpose |
|---|---|
| `@repo/core-api` | `appRouter` for tRPC endpoint |
| `@repo/core-trpc/next` | Next.js tRPC client + provider (optional — scaffold first) |
| `@repo/core-ui` | Design system components (optional — scaffold first) |
| `@repo/auth`, `@repo/blog`, etc. | Feature packages (indirectly via core-api) |
| `next` | Next.js 15 framework |
| `@trpc/server` | tRPC server (fetch adapter) |

## Test conventions

- Unit tests colocated: `src/app/blog/article-list.test.tsx`
- Vitest environment: `jsdom`
- e2e tests in `e2e/` folder: `*.spec.ts`
- Run: `pnpm test --filter @repo/web-next` (units) or `pnpm test:e2e` (Playwright)

## E2E Test Setup

Playwright config in `e2e/playwright.config.ts`:

```typescript
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  webServer: {
    command: "pnpm dev",
    port: 3000,
    reuseExistingServer: !process.env.CI,
  },
  use: { ...devices["Desktop Chrome"].use },
});
```

Run: `pnpm test:e2e` starts the dev server and runs all `.spec.ts` files.

## 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`