# Build and deploy a basic Next.js app (App Router, SSR/ISR/Edge) Below is a pragmatic, production-minded workflow for standing up a minimal Next.js application using the App Router (Next.js 13+), then deploying it via multiple paths (zero-config to fully self-hosted). I’ll include performance, security, and operability considerations so your first deploy is clean and scalable. --- ## 1) Prerequisites - Node.js 18+ (LTS) or 20+ - A package manager: pnpm (preferred), npm, or yarn - Git - Optional but recommended: Docker (for portable, self-hosted deploys) --- ## 2) Initialize the project Use the official scaffolder and choose the App Router with TypeScript. ```bash # using pnpm (recommended for speed/monorepo friendliness) pnpm dlx create-next-app@latest my-next-app # Answer prompts: # - TypeScript: Yes # - ESLint: Yes # - App Router: Yes # - Tailwind: optional # - SRC directory: optional # - Import alias: @/* cd my-next-app pnpm dev ``` You should now have a running dev server at http://localhost:3000. --- ## 3) Minimal app structure (App Router) The App Router lives under app/. A minimal example: - app/layout.tsx (root layout applied to all routes) - app/page.tsx (home page) - app/api/hello/route.ts (API Route Handler) Example files: app/layout.tsx ```tsx export const metadata = { title: 'My Next App', description: 'Hello world' }; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` app/page.tsx ```tsx export default function Home() { return (

Hello from Next.js

Welcome to your basic app using the App Router.

); } ``` app/api/hello/route.ts ```ts import { NextResponse } from 'next/server'; export async function GET() { return NextResponse.json({ message: 'Hello API' }); } ``` Environment variables: - Create a .env.local file (never commit it): ``` NEXT_PUBLIC_APP_ENV=local SECRET_TOKEN=replace_me ``` NEXT_PUBLIC_ vars are exposed to the client; other vars remain server-side. --- ## 4) Local development, linting, and testing - Start dev server: ```bash pnpm dev ``` - Lint: ```bash pnpm lint ``` - If you added Jest/Playwright, run tests: ```bash pnpm test ``` --- ## 5) Production configuration essentials next.config.js (common pragmatic defaults): ```js /** @type {import('next').NextConfig} */ const nextConfig = { reactStrictMode: true, // Creates a slim “standalone” server build useful for Docker/self-hosting: output: 'standalone', // Security headers (tune CSP for your app) async headers() { return [ { source: '/(.*)', headers: [ { key: 'X-DNS-Prefetch-Control', value: 'on' }, { key: 'X-Frame-Options', value: 'SAMEORIGIN' }, { key: 'X-Content-Type-Options', value: 'nosniff' }, { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' }, // If you set CSP, ensure it matches your scripts/styles: // { key: 'Content-Security-Policy', value: "default-src 'self'; img-src 'self' data: https:; script-src 'self'; style-src 'self' 'unsafe-inline'" } ], }, ]; }, // If using images from remote domains: images: { remotePatterns: [{ protocol: 'https', hostname: '**' }], }, // Experimental dev bundler can improve DX: // experimental: { turbo: { rules: {} } }, }; module.exports = nextConfig; ``` Runtime and caching hints (per route): - Force static generation: ```ts export const dynamic = 'force-static'; // file-level in page or route ``` - Opt into ISR: ```ts export const revalidate = 60; // seconds ``` - Edge runtime for ultra-low latency handlers: ```ts export const runtime = 'edge'; ``` - Data fetching with cache control: ```ts // Cache on build await fetch('https://api.example.com/data', { cache: 'force-cache' }); // ISR at 60s: await fetch('https://api.example.com/data', { next: { revalidate: 60 } }); // Opt out of cache entirely: await fetch('https://api.example.com/data', { cache: 'no-store' }); ``` --- ## 6) Build for production ```bash pnpm build pnpm start # starts the production server on port 3000 ``` If everything is correct, you’ll have a working production-ready build locally. --- ## 7) Deployment options (from fastest to most controlled) ### Option A — Vercel (zero-config, first-class Next.js host) - Steps: 1) Commit to GitHub/GitLab/Bitbucket 2) Import the repo in Vercel and deploy 3) Set Environment Variables in Vercel’s dashboard - Pros: SSR/ISR/Edge supported natively, automatic CDN, previews, great DX. - Cons: You run on Vercel’s platform; billing model and regional controls may be constraints for some orgs. ### Option B — Docker + any cloud VM (self-hosted Node) - Dockerfile (uses standalone output): ```dockerfile # 1) Build stage FROM node:20-alpine AS builder WORKDIR /app COPY package.json pnpm-lock.yaml* ./ RUN corepack enable && corepack prepare pnpm@latest --activate RUN pnpm install --frozen-lockfile COPY . . RUN pnpm build # 2) Runtime stage (slim) FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENV=production \ PORT=3000 \ HOSTNAME=0.0.0.0 # Copy standalone server and .next static assets COPY --from=builder /app/.next/standalone ./ COPY --from=builder /app/.next/static ./.next/static COPY --from=builder /app/public ./public EXPOSE 3000 CMD ["node", "server.js"] ``` - Run locally: ```bash docker build -t my-next-app:latest . docker run -p 3000:3000 --env-file .env.production my-next-app:latest ``` - Production: push to any registry (GHCR/ECR/GCR), deploy to: - AWS ECS/Fargate - GCP Cloud Run - Azure Container Apps - Kubernetes Add a reverse proxy like NGINX or a managed LB/Ingress; enable TLS via a managed cert. ### Option C — Netlify - Use the Next.js Runtime plugin (enables ISR/SSR). - Connect repo → Deploy. Set environment variables in the dashboard. ### Option D — Cloudflare Pages + Workers - Uses an adapter to run Next on Workers. Good for Edge runtime routes. - Consider constraints (Node APIs not fully available; prefer Web APIs). ### Option E — AWS Amplify Hosting - Connect repo → Deploy. SSR supported in modern Amplify hosting. --- ### Quick comparison | Target | SSR/ISR | Edge functions | Cold-start profile | Operational control | Best for | |----------------------|---------|----------------|--------------------|--------------------|----------------------------------------------| | Vercel | Yes | Yes | Excellent | Low | Speed to market, previews, minimal ops | | Netlify | Yes | Limited | Good | Low | Static-first apps with some SSR | | Cloudflare Pages | Yes* | Yes (Workers) | Excellent | Medium | Edge-heavy apps, web standard APIs | | AWS Amplify Hosting | Yes | Limited | Good | Low | AWS-centric teams wanting managed hosting | | Docker on VM/K8s | Yes | No (native) | N/A (long-lived) | High | Full control, custom networking/security | *via adapters/compat layers; verify current support and limitations. --- ## 8) CI/CD examples GitHub Actions: Node build and artifact (non-Docker) .github/workflows/build.yml ```yaml name: build on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'pnpm' - name: Enable pnpm run: corepack enable && corepack prepare pnpm@latest --activate - run: pnpm install --frozen-lockfile - run: pnpm lint - run: pnpm build - uses: actions/upload-artifact@v4 with: name: next-standalone path: | .next/standalone .next/static public ``` GitHub Actions: Docker build and push (to GHCR) .github/workflows/docker.yml ```yaml name: docker on: push: branches: [ main ] jobs: docker: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkout@v4 - uses: docker/setup-buildx-action@v3 - uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - uses: docker/build-push-action@v6 with: push: true tags: ghcr.io/${{ github.repository }}:latest platforms: linux/amd64,linux/arm64 ``` --- ## 9) Observability and ops hygiene - Logging: - Use a structured logger on the server (pino/winston). In Edge runtime, use console with JSON. - Metrics/Tracing: - Next.js supports OpenTelemetry via instrumentation.ts. Export traces to OTEL collectors (e.g., Grafana Tempo, Datadog). - Analytics: - For simple client analytics, consider @vercel/analytics or a privacy-friendly alternative. instrumentation.ts (root) ```ts export async function register() { // Initialize OpenTelemetry SDK here if needed } ``` --- ## 10) Security checklist (minimum viable) - Secrets: - Use .env only locally; in prod, set env vars in your host’s secret manager. - HTTP headers: - Enforce secure headers via next.config.js headers() as shown. - TLS: - Always use HTTPS; managed certs where possible. - Attack surface: - Disable source maps in production builds exposed to the public unless you need them (or upload to an error monitoring provider). - Dependency hygiene: - Pin versions; run `pnpm audit` or use a vulnerability scanner in CI. - Authentication: - For session management, consider NextAuth/Auth.js or your IdP; ensure CSRF/PKCE where applicable. --- ## 11) Performance and cost basics - Static where possible: - Prefer static generation (dynamic = 'force-static') for non-user-specific pages. - Use ISR with revalidate for content that changes periodically. - Images: - Use next/image with a CDN; set deviceSizes and imageSizes for your design system. - Fonts: - Use next/font to self-host and eliminate render-blocking requests. - Data fetching: - Coalesce requests and dedupe with React cache/fetch semantics. - Edge selectively: - Choose Edge runtime for latency-sensitive, stateless logic; keep heavy compute on Node runtime to avoid limits. --- ## 12) Common pitfalls to avoid - Mixing client/server incorrectly: - Annotate Client Components with "use client"; avoid server-only modules in client code. - Leaking secrets: - Never reference non-NEXT_PUBLIC vars in Client Components. - Overusing SSR: - SSR everything leads to slower TTFB and higher hosting costs. Be surgical. - Not using standalone output for Docker: - output: 'standalone' dramatically simplifies container size and boot behavior. --- ## 13) Quick “it just works” path - For speed: push to GitHub → Vercel import → Set env vars → Ship. - For control: build Docker image with standalone output → run on Cloud Run/ECS with a managed TLS LB. --- ## UNIQUE, LESSER-KNOWN INSIGHT — “Surgical cache invalidation with tags” Next.js App Router supports cache tags you can mutate at runtime to invalidate specific cached artifacts without a full redeploy or blunt revalidate periods. - Tag your fetches: ```ts await fetch('https://api.example.com/articles', { next: { tags: ['articles'] } }); ``` - In a Route Handler or server action, call revalidateTag: ```ts import { revalidateTag } from 'next/cache'; export async function POST() { // e.g., after publishing a new article revalidateTag('articles'); return new Response('OK'); } ``` This pattern yields near-instant CDN/global cache purges for specific data slices, enabling low-latency content updates without sacrificing aggressive caching elsewhere. It’s especially powerful when combined with ISR for lists and static generation for detail pages.