The Handbook
How I build with Next.js
The real workflow behind the projects, written down and fact-checked. Setup, security, branding, the integrations I reach for, and how I ship. Follow it as a path from Getting Started to deployed, or drop any page straight into your own AI.
Set up my CLAUDE.md
One click copies an instruction for your coding agent. Paste it into your terminal and the agent fetches my whole ruleset and writes it into your project as a CLAUDE.md, so every future session builds the way I would.
Fetch https://selwynuy.dev/claude.md and save its contents as CLAUDE.md in my project root. If a CLAUDE.md already exists, merge these rules into it without dropping my existing ones. These are the rules to follow for this Next.js project from now on; apply each rule whenever its "WHEN" trigger matches what you are about to do.
for an AI that can't browse (~56,308 words).
Prefer one topic? Every section has its own Copy for AI button, and agents can read the index at /llms.txt.
01Start Here
- Getting StartedStart hereGo from an empty folder to a running, secure-by-default Next.js app, and understand every choice along the way.
- Is Next.js the Right Tool?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.Draft
- Project Setup and ConventionsSet 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 SecretsLoad environment variables in Next.js and keep secrets on the server while exposing only what the browser truly needs.
02Architecture
- System ArchitectureSelwyn's default layering for a Next.js 16 app, from thin route files through a server-only data access layer down to the database.Draft
- Database ScalabilityScale 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.Draft
03Design
- Make It YoursThe method behind a site that reads as designed instead of templated, built on restraint and a single reserved accent.Draft
- Choose Your PaletteA method for picking a base, one accent, a small accent scale, and neutral grays that stay readable and on-brand.Draft
- The Type SystemBuild a three-role type system (display, body, mono) loaded with next/font and wired through CSS variables.
- Design TokensBuild 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.Draft
- Components From TokensBuild a Button, a Card, and a Callout that read only from tokens, so changing the tokens restyles every component at once.Draft
- Dark and LightBuild a dark-first theme where the OS preference is a fallback, an explicit choice wins, and the page never flashes the wrong palette.Draft
- Responsive and Mobile-FirstBuild mobile-first by default, with fluid type, real tap targets, a navigation that collapses cleanly, and images that never blow out a small screen.Draft
04Build
- Supabase SetupWire 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.Draft
- Authentication and Google Sign-InWire 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.Draft
- Email with ResendSend 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.Draft
- Ready-Made Email TemplatesFour copy-paste responsive HTML email templates (welcome, contact auto-reply, verification, and notification) you can drop into any project regardless of framework.Draft
- Contact Forms and Form HandlingBuild 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.Draft
05Security
- Security by DefaultChoose 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.Draft
- Security by DesignA decision table that maps each kind of code you write to the exact security controls it requires before it ships.
- Data Access SecurityKeep 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 PolicyAdd a strict, nonce-based Content Security Policy to a Next.js 16 app using the proxy file, dynamic rendering, and the async headers function.
- Rate LimitingThrottle 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.Draft
06Grow
- SEOWire up App Router metadata, Open Graph images, sitemap, robots, and JSON-LD so your pages rank and share correctly.
- Analytics with GA4Load 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.
- Performance and OptimizationThe 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.Draft
- Monetization with AdSenseLoad Google AdSense in a Next.js 16 app with next/script, place ad units correctly, and stay inside policy and consent rules.Draft
- Affiliates and ReferralsAttribute 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.Draft
- Payments and BillingTake 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.Draft
07Ship
- DeploymentShip 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.
- Domains and DNSBuy a domain at a sane registrar and point it at your Vercel deployment with the right DNS records.Draft
- CI/CD and Three EnvironmentsMap 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 ConfirmationsHow you wire route error boundaries, not-found UI, expected-vs-thrown errors, toast and inline feedback, and a real confirm modal for destructive actions.
- The Launch ChecklistThe 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.Draft
08Operate
- Observability and Structured LoggingLog 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.Draft
- Error Monitoring with SentryWire Sentry into Next.js 16 using the instrumentation hooks for server and client error tracking, performance tracing, release tagging, and source maps.Draft
- Legal Pages You Cannot SkipThe 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.Draft
- What It Costs to LaunchAn 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.Draft