AGENTS.md — apps/web-next

Next.js 15 reference application using App Router. Demonstrates consuming feature packages via tRPC, using @repo/core-trpc/next for client setup, and importing UI components from @repo/core-ui.

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

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

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

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 `<TrpcProvider>` from `@repo/core-trpc/next`
`src/app/providers.tsx`	Client component for tRPC + React Query setup
`src/app/page.tsx`	Home page — navigation + marketing content
`src/app/blog/[slug]/page.tsx`	Dynamic blog post route
`src/app/api/trpc/[trpc]/route.ts`	tRPC fetch adapter endpoint
`e2e/`	Playwright end-to-end tests

tRPC Setup

The tRPC endpoint handler (in src/app/api/trpc/[trpc]/route.ts):

import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
import { appRouter } from "@repo/core-api";

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

export { handler as GET, handler as POST };

The provider (in src/app/providers.tsx):

"use client";
import { TrpcProvider } from "@repo/core-trpc/next";

export function Providers({ children }: React.ReactNode) {
  return <TrpcProvider>{children}</TrpcProvider>;
}

Dependencies

Dependency	Purpose
`@repo/core-api`	`appRouter` for tRPC endpoint
`@repo/core-trpc/next`	Next.js tRPC client + provider
`@repo/core-ui`	Design system components
`@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:

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: packages/core-trpc/AGENTS.md
UI components: packages/core-ui/AGENTS.md

3.2 KiB Raw Blame History