# Selwyn Uy: Next.js Handbook

> An opinionated, fact-checked field guide to building production Next.js applications: project setup, security by default, integrations, growth, and shipping. Each section below is plain markdown you can hand directly to an AI to apply to your own project.

Author: Selwyn Uy (Full Stack Next.js Web Developer). Site: https://selwynuy.dev/. Each link is the raw markdown for one section.

## Start Here

- [Getting Started](https://selwynuy.dev/d/getting-started.md): Go from an empty folder to a running, secure-by-default Next.js app, and understand every choice along the way.
- [Project Setup and Conventions](https://selwynuy.dev/d/project-setup.md): Set up a Next.js 16 codebase that stays fast and legible with Server Components by default, thin routes, typed data, and client islands pushed down the tree.
- [Environment and Secrets](https://selwynuy.dev/d/environment-and-secrets.md): Load environment variables in Next.js and keep secrets on the server while exposing only what the browser truly needs.

## Design

- [The Type System](https://selwynuy.dev/d/type-system.md): Build a three-role type system (display, body, mono) loaded with next/font and wired through CSS variables.

## Security

- [Security by Design](https://selwynuy.dev/d/security-by-design.md): A decision table that maps each kind of code you write to the exact security controls it requires before it ships.
- [Data Access Security](https://selwynuy.dev/d/data-security.md): Keep sensitive fetching on the server, pass only safe fields to client components, centralize access in a server-only Data Access Layer, and use React taint APIs as a backstop.
- [Content Security Policy](https://selwynuy.dev/d/content-security-policy.md): Add a strict, nonce-based Content Security Policy to a Next.js 16 app using the proxy file, dynamic rendering, and the async headers function.

## Grow

- [SEO](https://selwynuy.dev/d/seo.md): Wire up App Router metadata, Open Graph images, sitemap, robots, and JSON-LD so your pages rank and share correctly.
- [Analytics with GA4](https://selwynuy.dev/d/analytics.md): Load Google Analytics 4 through next/script with an env-driven component that no-ops when the measurement ID is unset, then forward Core Web Vitals.

## Ship

- [Deployment](https://selwynuy.dev/d/deployment.md): Ship a Next.js 16 app to Vercel from a GitHub push, wire production environment variables, and gate every deploy behind a green typecheck, lint, and build.
- [CI/CD and Three Environments](https://selwynuy.dev/d/ci-cd-pipelines.md): Map local, staging, and production to a feature-PR-staging-main branch model gated by a GitHub Actions check that runs typecheck, lint, content guard, tests, and build on every pull request.
- [Errors, Feedback, and Confirmations](https://selwynuy.dev/d/error-handling-ux.md): How you wire route error boundaries, not-found UI, expected-vs-thrown errors, toast and inline feedback, and a real confirm modal for destructive actions.

## Optional

- [Is Next.js the Right Tool? (draft)](https://selwynuy.dev/d/nextjs-fit-check.md): A blunt rubric for when Next.js is the right default and when to reach for Astro, Expo, a Python queue, or a dedicated websocket server instead.
- [System Architecture (draft)](https://selwynuy.dev/d/system-architecture.md): Selwyn's default layering for a Next.js 16 app, from thin route files through a server-only data access layer down to the database.
- [Database Scalability (draft)](https://selwynuy.dev/d/database-scalability.md): Scale a Supabase Postgres database under serverless load with a transaction-mode pooler, indexes on the columns you filter and join, RLS that stays cheap, and keyset pagination instead of OFFSET.
- [Make It Yours (draft)](https://selwynuy.dev/d/branding-overview.md): The method behind a site that reads as designed instead of templated, built on restraint and a single reserved accent.
- [Choose Your Palette (draft)](https://selwynuy.dev/d/choose-your-palette.md): A method for picking a base, one accent, a small accent scale, and neutral grays that stay readable and on-brand.
- [Design Tokens (draft)](https://selwynuy.dev/d/design-tokens.md): Build a semantic token layer in CSS and expose it to Tailwind v4 so utilities read your variables and you re-theme by editing one place.
- [Components From Tokens (draft)](https://selwynuy.dev/d/components-from-tokens.md): Build a Button, a Card, and a Callout that read only from tokens, so changing the tokens restyles every component at once.
- [Dark and Light (draft)](https://selwynuy.dev/d/dark-and-light.md): Build a dark-first theme where the OS preference is a fallback, an explicit choice wins, and the page never flashes the wrong palette.
- [Responsive and Mobile-First (draft)](https://selwynuy.dev/d/responsive-design.md): Build mobile-first by default, with fluid type, real tap targets, a navigation that collapses cleanly, and images that never blow out a small screen.
- [Supabase Setup (draft)](https://selwynuy.dev/d/supabase-setup.md): Wire Supabase into a Next.js App Router project with a split browser and server client, the service role key kept server-only, and Row Level Security as the real access control.
- [Authentication and Google Sign-In (draft)](https://selwynuy.dev/d/authentication.md): Wire up email and password plus Google OAuth on Supabase, with verified sessions, a data access layer, validated inputs, rate limiting, and a callback that survives every failure mode.
- [Email with Resend (draft)](https://selwynuy.dev/d/email-with-resend.md): Send transactional email from a Next.js 16 POST route handler with Resend, keeping the API key server-side, validating input, and degrading gracefully when the key is unset.
- [Ready-Made Email Templates (draft)](https://selwynuy.dev/d/email-templates.md): Four copy-paste responsive HTML email templates (welcome, contact auto-reply, verification, and notification) you can drop into any project regardless of framework.
- [Contact Forms and Form Handling (draft)](https://selwynuy.dev/d/contact-and-forms.md): Build forms that submit through a server action with validation, a honeypot, rate limiting, accessible inline errors, and reliable email delivery, with no client-side secrets.
- [Security by Default (draft)](https://selwynuy.dev/d/security.md): Choose defaults so the insecure version is the one you have to go out of your way to write, then harden a typical Next.js app at the four boundaries that matter.
- [Rate Limiting (draft)](https://selwynuy.dev/d/rate-limiting.md): Throttle abuse-prone endpoints with a shared store that actually works across serverless instances, keyed by IP and hashed identity, with a safe in-memory fallback for local dev.
- [Performance and Optimization (draft)](https://selwynuy.dev/d/performance.md): The optimizations that actually move the needle in a Next.js app, from paginating large lists to caching deliberately, shipping fitted images, and killing the N+1 query before it ships.
- [Monetization with AdSense (draft)](https://selwynuy.dev/d/monetization-adsense.md): Load Google AdSense in a Next.js 16 app with next/script, place ad units correctly, and stay inside policy and consent rules.
- [Affiliates and Referrals (draft)](https://selwynuy.dev/d/affiliates-referrals.md): Attribute a signup to the link that brought it with a signed cookie, claim it once at signup, and pay a commission only when a verified payment lands, all decided server-side.
- [Payments and Billing (draft)](https://selwynuy.dev/d/payments-billing.md): Take money safely with a checkout flow and a webhook that verifies signatures, trusts the provider not the payload, stays idempotent under replays, and grants access exactly once.
- [Domains and DNS (draft)](https://selwynuy.dev/d/dns-and-domains.md): Buy a domain at a sane registrar and point it at your Vercel deployment with the right DNS records.
- [The Launch Checklist (draft)](https://selwynuy.dev/d/launch-checklist.md): The line between code that runs and a site that is done, branding, favicon, social card, design consistency, and the polish pass that decides whether your site reads as finished. An interactive checklist you can work through and tick off.
- [Observability and Structured Logging (draft)](https://selwynuy.dev/d/observability-logging.md): Log one JSON line per event with PII redacted, forward errors to Sentry from a single helper, and flush before a serverless function returns so nothing is lost.
- [Error Monitoring with Sentry (draft)](https://selwynuy.dev/d/sentry-setup.md): Wire Sentry into Next.js 16 using the instrumentation hooks for server and client error tracking, performance tracing, release tagging, and source maps.
- [Legal Pages You Cannot Skip (draft)](https://selwynuy.dev/d/legal-pages.md): The privacy policy, terms, disclaimer, and data-deletion pages every real app needs, why they gate Google sign-in and AdSense approval, and how to build them as proper indexable routes.
- [What It Costs to Launch (draft)](https://selwynuy.dev/d/cost-to-launch.md): An honest breakdown of what a production, scalable Next.js stack actually costs, from nearly free at launch to a predictable monthly bill as you grow.