React + Next.js

Bootstrap Next.js, configure SSR, Cognito auth, and API routes.

Next.js is the default stack for SEO-sensitive pages, authenticated portals, and server-rendered dashboards deployed on Vercel.

Create the project

bash

npx create-next-app@latest web-portal --yes --typescript --app --src-dir
cd web-portal
pnpm add zustand aws-amplify
pnpm dev

Project structure

plaintext

src/
├── app/              # App Router pages and layouts
│   ├── (auth)/       # Public auth routes
│   ├── (dashboard)/  # Protected routes
│   └── api/          # Route handlers
├── components/
├── lib/              # Auth, API client, utilities
└── stores/

Environment variables

dotenv

NEXT_PUBLIC_API_URL=http://localhost:4000/api
NEXT_PUBLIC_COGNITO_USER_POOL_ID=us-east-1_xxxxx
NEXT_PUBLIC_COGNITO_CLIENT_ID=xxxxxxxx
NEXT_PUBLIC_COGNITO_DOMAIN=auth.company.com

Auth middleware

typescript

// src/middleware.ts
import { NextRequest, NextResponse } from "next/server";
 
export function middleware(request: NextRequest) {
  const token = request.cookies.get("access_token");
  if (!token && !request.nextUrl.pathname.startsWith("/login")) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/((?!login|api|_next/static|_next/image|favicon.ico).*)"],
};

Server vs client components

Pattern	Use
Server Component	Data fetching, SEO metadata, static layout
Client Component	Interactivity, browser APIs, Zustand stores
Route Handler	API proxy, webhooks, server-side mutations

Verify auth flow

Login redirects to Cognito hosted UI.
Callback sets session cookies/tokens.
Protected routes render after auth check.
API calls include Bearer token.
Token refresh works without re-login.
Logout clears session and redirects to login.

Pre-PR checklist

bash

pnpm lint && pnpm typecheck && pnpm test && pnpm build