Skip to main content

Next.js 16 with App Router (Web)

Overview​

The QMS frontend uses Next.js 16 with the App Router, built on React 19. The App Router provides file-system routing, layouts, server components, and improved data fetching patterns.

Project layout (apps/web/src/app)​

src/app/
├── layout.tsx           # Root layout
├── page.tsx             # Root page
├── (auth)/              # Grouped routes
│   └── login/page.tsx
├── employees/
│   ├── layout.tsx
│   └── page.tsx
└── components/          # Shared UI components

Key App Router concepts​

  • app/layout.tsx provides persistent UI and common providers
  • app/page.tsx is the route entry point
  • app/route.ts supports server-only request handlers (for edge/server actions)
  • loading.tsx and error.tsx support per-route UX
  • Server Components by default; use 'use client' for client components

Data fetching patterns​

  • Use server components to fetch data on the server when possible (fast TTFB and SEO)
  • Use TanStack Query (see State & Data doc) for client caching and background revalidation
  • Prefer route-level loading with Suspense and streaming for large pages

Routing and nested layouts​

  • Use nested layout.tsx files for subtrees (e.g., employees) to share UI and data
  • Use useRouter() in client components for navigation

API integration​

  • QMS exposes API under /api/v1 via the backend
  • Use environment variable NEXT_PUBLIC_API_BASE_URL to point to API

Environment variables​

  • NEXT_PUBLIC_API_BASE_URL — API base URL available in browser
  • NEXT_PUBLIC_API_VERSION — API version path

Rendering strategy​

  • Prefer server rendering for initial load and SEO
  • Use client components for interactive widgets (tables, modals)
  • Use edge/server functions for lightweight server handlers when needed

Testing​

  • Unit test components with React Testing Library and Jest
  • Integration/e2e tests via Playwright/Selenium Grid (see testing docs)

Best Practices​

  • Keep components small and focused
  • Move data fetching to higher-level components when possible
  • Use shared UI primitives in src/components and packages/schemas for types
  • Keep accessibility (a11y) in mind — keyboard navigation, labels, and ARIA

Resources​