TypeScript, scaffolded with --typescript

Types pay for themselves the first time a refactor would silently break call sites.

App Router with Server Components by default; fetch on the server, ship the browser only what it needs

It is the single biggest lever for shipping less JavaScript to the browser.

Push "use client" down to the smallest interactive leaf; never mark a whole page client for one button

Once a file carries the directive, every module it imports and child it renders joins the client bundle.

Keep page.tsx, layout.tsx, and route.ts thin; data access, validation, and integrations live in lib/

A route's job is to wire data to UI, not own fetching, parsing, or validation.

Four layers: thin routes (app/), server-only data access (lib/data/), Zod validation (lib/validation/), isolated integrations (lib/integrations/), each talking only to the layer below

Every kind of logic gets one home and dependencies stay one-directional, so the skeleton scales from a weekend to years.

Never import a database client or vendor SDK inside a component or route handler; one module per external service

It couples UI to infrastructure and makes the data layer impossible to reuse or swap.

Treat params, searchParams, headers(), and cookies() as Promises and always await them

In Next.js 16 they are no longer plain objects, so synchronous access fails typechecking and throws at runtime.

Validate and type external data into a named type once at the edge; never pass res.json() or any any-typed value into the tree

res.json() is typed any and any spreads, so untyped data at the boundary becomes untyped data everywhere.

Writes go through a Server Action that validates input with a Zod schema before the data layer sees it

Invalid input never reaches the database.

ESLint wired in from the first commit, enforcing no-unused-vars and no stray console

Problems surface while they are still cheap to fix and the conventions cannot quietly erode.

Pin the Next.js version (e.g. next@16.x) in real projects

A pinned version will not silently jump a major and break under you later.

Reach for Next.js whenever the deliverable is HTML in a browser that also needs server-side logic

That shape covers the large majority of builds and reaching for it there is never wrong.

Never put persistent sockets, on-device native, long-running compute, or static-only content inside Next.js; run the right tool beside it over an API

Bolting those onto a Next.js app produces a fragile hybrid.

Use a dedicated socket server (Phoenix Channels, Go) or a managed service like Ably or Pusher

Request/response handlers cannot hold thousands of long-lived connections and serverless bills brutally for them.

Use a Python service behind a queue-and-worker model; Next.js takes the upload, enqueues, and shows status

Serverless has time limits and cold starts while the ML tooling and time budget live in Python.

Decide per surface, not per project, and run the fit checklist before scaffolding

Most real products mix tools and the expensive failure is sunk-cost commitment after the architecture sets.

Exactly three roles (display, body, mono); never set a condensed display face on body copy

Three roles create hierarchy without a ransom-note page, and condensed faces wreck paragraph readability.

Call each next/font loader exactly once in app/fonts.ts and import the object everywhere, declaring subsets: ["latin"]

Each loader call hosts a separate instance, so calling it twice ships the same font twice and breaks preloading.

Pick exactly ONE accent reserved for emphasis; never add a second to balance it

The accent earns its weight precisely because it is rare, and a second accent halves the impact of both.

Never set body copy in the accent color; keep it on affordances only

The accent marks where to act while reading wants a high-contrast neutral, not a saturated hue that fails contrast.

Near-black like #0b0b0c for dark and off-white like #fafafa for light, never pure #000 or #fff

Pure black crushes shadows and vibrates against white, leaving no headroom for a layered surface system.

Body text must clear WCAG AA 4.5:1 (large text 3:1) on the actual surface it sits on

Contrast is the step people skip and it decides whether the product is usable.

Two layers, a raw scale and a semantic role layer that points at it; components touch only semantic roles, never raw hex

Raw values rarely change but roles get reassigned constantly, so the split lets you re-theme by editing one place.

Components read only token utilities (bg-accent, ring-hairline); never hardcode hex, rgb(), one-off grays, or arbitrary brackets

A hardcoded shade stops tracking the token, so the next theme change leaves the component the wrong color.

A token change is the only way to restyle the brand; never edit components to re-theme

If re-theming requires editing components, they are holding colors they should be borrowing and the system has drifted.

Expose semantic roles via @theme inline, and give --accent-foreground its own token

The inline keyword makes utilities resolve to var() at runtime so reassigning a variable actually re-themes.

Cap body copy at a 66ch measure, negative tracking on large display, positive on small caps

Measure is the single biggest lever on readability and past it the eye loses the next line's start.

Use bg-surface-raised plus ring-1 ring-hairline plus shadow-soft-md, a ring not a hard border

A ring sits outside the box model so the layout never shifts by a pixel on hover or focus.

Style the smallest screen first (unprefixed), then layer sm:/md:/lg: to widen; never start desktop and patch down

A layout born on the hardest screen works everywhere while squeezing a desktop layout down makes every override a patch.

Give anything tappable a 44x44px hit area and contain overflow so the page never scrolls sideways on mobile

Fingers are not cursors and one element wider than the viewport is the most common mobile bug.

Put dark values directly on :root, resolve the stored theme with a tiny synchronous inline script before paint, and add suppressHydrationWarning to <html>

Dark is the product so it must render with zero conditions met, and effects run after paint which is exactly when the flash happens.

Keep the dangerouslySetInnerHTML string a fixed literal, never interpolate request data, and validate the stored value is exactly "light" or "dark"

A fixed literal introduces no injection surface and validation ensures a tampered entry can only produce a known-good attribute.

Below lg, collapse nav into a static hamburger that opens a side drawer with a real close X inside it

The morph-to-X animation reads as generic and a drawer with a real close button is clearer about what is happening.

Prefer container queries (@container) over viewport breakpoints for components that adapt to their container

The component stays responsive wherever you drop it, not just relative to the whole page.

Always verify with auth.getUser() on the server through one cached Data Access Layer function; never trust getSession()

getUser() cryptographically re-verifies the JWT while getSession() just reads the cookie a forged value could fake.

Never prefix the service role key with NEXT_PUBLIC_ or reference it from any client file; server-only, for trusted webhooks and admin work

It bypasses RLS entirely, and once inlined into the bundle a value is public forever with rotation the only recovery.

Enable RLS on every table the anon key can reach and open access one minimal policy at a time

The default posture is deny and access is opened deliberately, which is what makes the anon key safe to expose.

Split the browser and server clients into separate files (lib/supabase/client.ts and server.ts), both on the anon key

The separation is structural, not a matter of remembering which import is safe where.

Validate every auth form with a Zod schema inside a server action before calling Supabase, with a real password policy, accept-terms, and honeypot

Validation belongs at the boundary in a mutation, and the policy, terms, and honeypot stop weak passwords and bots.

Allowlist any next/returnTo value to a path starting with '/', else fall back to /dashboard

A user-controlled redirect target is an open redirect used for phishing and to bounce sessions off-site.

Embed relations in one query to avoid N+1, and never cache a user-dependent query unless the cache key includes that user

N+1 multiplies round trips and caching user-specific results without a per-user key leaks data.

Supabase Postgres through the Supavisor transaction-mode pooler on port 6543; reserve direct port 5432 for migrations

Transient functions talking to Postgres directly exhaust the connection slot limit during traffic spikes.

Supabase Auth with @supabase/ssr in the App Router, email+password plus Google OAuth

It is the auth stack the whole page is built on for a side project on Supabase.

Index every column you filter, join, or order by (notably the tenant FK and composites), confirmed by explain analyze

Postgres does not auto-index foreign keys and unindexed WHERE columns turn into fatal sequential scans at scale.

Use keyset (cursor) pagination instead of OFFSET

OFFSET makes Postgres read and discard rows so deep pages get slower, while keyset rides the index at constant cost.

Refresh expiring sessions in proxy (the Next.js 16 rename of middleware), never enforce access there

The docs are explicit that proxy is for optimistic checks only and real authorization belongs in the data layer.

Treat every Server Action and route handler as a public endpoint reachable by direct POST; never treat the UI as access control

An exported Server Action is reachable even when no component renders its button.

Three checks in order inside every handler: validate input with Zod, authenticate, then authorize by ownership

Skipping the ownership check is the IDOR bug, the most common way a logged-in user reads or deletes another user's data.

Read process.env only in server code, add import 'server-only' to every secret-touching module, and never give a secret a NEXT_PUBLIC_ prefix

server-only turns an accidental client import into a build error and NEXT_PUBLIC_ inlines the value into shipped JavaScript forever.

Treat NEXT_PUBLIC_ as publishing to the world; never add it to silence a missing-env error, move the read to the server instead

The error means a secret is being read on the client and the correct fix is server-side reading, not exposure.

Never commit .env.local or any file with a real credential; commit .env.example with blank values

A secret in git history is leaked even after deletion, so real values must never reach the repository.

One server-only DAL owns every DB call and process.env read, runs authorization, and is the single audit surface

Auditing one server-only module beats grepping the whole app for stray queries, secrets, and missing checks.

Parameterize via tagged template or query builder; never interpolate user input into a query string

String interpolation in a query is SQL injection waiting to happen.

Map to a minimal DTO with only the fields the UI renders; never pass a raw DB row or full User object across the boundary

Every field on a passed object is serialized into the client payload, so the unrendered fields leak.

Nonce-based CSP minted in proxy.ts, fresh per request; never use 'unsafe-inline' in script-src, allow 'unsafe-eval' only in dev

Only scripts tagged with the exact per-request token run, which is exactly what an injected XSS payload lacks.

Shared Redis-backed limiter (Upstash, sliding window) in production; never a per-process Map, with an in-memory dev fallback

A module-level Map resets per serverless cold start, so the counter must be visible to every instance to limit anything.

Model expected errors as return values; throw only unexpected ones to an error boundary, never render error.message or a raw DB error

A leaked stack trace or raw DB error is a reconnaissance gift to an attacker.

Run next build and grep .next/static for known secret strings to confirm nothing leaked

A secret string appearing under .next/static proves it leaked into the browser bundle.

Submit forms through a server action that validates every field with Zod first; never fetch a third party or expose a provider key from the client

It keeps API keys and provider calls on the server and treats all client input as untrusted before any field is used.

Resend behind one uncached POST handler that validates first, builds the client second, sends last

Email is a side effect on untrusted input that needs one trusted choke point and mutations must never be cached.

Keep from on a verified domain and set replyTo to the visitor; never spoof from with the visitor's address

Spoofing from gets you marked as spam and breaks SPF and DKIM.

HTML-escape every user-supplied value before substituting it, and build action URLs from trusted server state only

Raw form input can break layout or smuggle a tracking pixel and an attacker-controlled value must never become the link target.

Build with HTML tables, never flexbox or grid, and always send a plain-text fallback

Outlook renders with Word's engine so tables are the only layout that renders the same across clients, and plain text aids deliverability.

Use a controlled dialog that names the target and disables while pending, never window.confirm, and re-check ownership server-side

window.confirm cannot show context and the modal is UX, not authorization, since a fetch client skips it entirely.

Always ship app/not-found.tsx as the app-wide catch-all for unmatched URLs

The root not-found doubles as the catch-all for any unmatched URL across the app.

Add a CSS-hidden honeypot rejected when filled plus a per-IP rate limit, instead of a captcha

Together they stop the bulk of automated spam without forcing a captcha on real users.

Drive UI from the server action's returned state via useActionState, tie each error to its input with aria-describedby, disable submit while pending

Typed returned state plus ARIA wiring gives accessible inline errors and clear pending feedback.

Set metadataBase once in the root layout and an explicit alternates.canonical on every indexable page

Relative OG and canonical URLs resolve against it and the canonical is the strongest signal against duplicate-content dilution.

Never rely on robots.txt disallow to protect admin, account, or API paths; gate sensitive routes with real authorization

robots.txt is a public, polite request that tells everyone exactly where to look.

Validate params shape before fetching and never echo unsanitized user input into title or description

A crafted slug reaching an internal service is request forgery, not an SEO bug.

Load GA4 via next/script at afterInteractive, mounted once in app/layout.tsx referencing NEXT_PUBLIC_GA_ID literally, rendering nothing when unset

afterInteractive keeps the tag off the critical path, per-page mounting double-counts, and a computed env key silently no-ops.

Load the loader once via next/script afterInteractive, render units through a client component with a silent try/catch; place units only in finished content, never click your own ads

A missing ad must never break the page, and self-clicks or empty pages are policy violations that get accounts permanently banned.

Load the CMP beforeInteractive and default analytics_storage to denied until the visitor opts in

Collecting nothing until consent is the secure-by-default posture that keeps you on the right side of GDPR.

Use title.template plus title.default in the root layout and the opengraph-image.tsx file convention via ImageResponse

Child pages inherit the brand suffix for free and the file convention auto-wires og:image at higher priority than config.

Sign the ref value (HMAC or signed JWT) in an httpOnly cookie and verify the signature before trusting it

A raw ?ref= value is attacker-editable and lets anyone credit themselves or burn a competitor.

Never credit a commission from the browser; compute amounts server-side from the verified gross payment and your own tier table

There must be no step where editing a URL or replaying a request can manufacture a credit.

Claim attribution once, idempotently keyed on the new user id, and record the conversion inside the payment webhook after the row commits

An atomic RPC keyed on the user prevents double-attribution and ties the commission to real settled money.

Reverse or void the conversion when a commission-earning payment is refunded or charged back

A paid-out commission on refunded revenue is a direct loss, so commission must track real settled money.

Make attribution best-effort and never block the redirect; swallow errors and continue

A failed attribution is a bookkeeping problem but a blocked sign-in is a lost customer.

Grant access only from the signed provider webhook, never from the browser checkout redirect

The browser can be closed, replayed, or forged, while the webhook is a signed server-to-server call.

Verify the signature against the raw req.text() body before parsing, never req.json()

The signature is computed over the exact bytes, so parsing first invalidates verification.

Re-fetch the payment from the provider API by id and trust that for amount, currency, and status

The webhook body is only a spoofable hint while the provider API is authoritative.

Insert under a unique constraint keyed on payment id (and event id) and treat a 23505 violation as an already-processed no-op

Providers retry and fire sibling events per payment, so a non-idempotent grant can grant twice.

Set amounts and SKU on the server from my own pricing table, never from a client-sent price

A client-supplied amount is a free-product exploit.

Register at an at-cost registrar like Cloudflare (or Porkbun, Namecheap) and check the renewal price, never just the first-year promo

At-cost registrars charge wholesale while others quietly gouge on renewals.

Never buy domain privacy, premium DNS, or SSL add-ons

WHOIS privacy is free at decent registrars and Vercel issues and renews TLS for free.

Move Vercel to Pro the same day a project becomes commercial, never run commercial work on Hobby

Vercel Hobby forbids commercial use, so this is a licensing rule independent of traffic.

Decide access by querying a live entitlement (active and not expired), not a boolean flag flipped once

Expiry, refunds, and downgrades need a queryable source of truth, not a stale flag.

Launch on free tiers (Vercel Hobby, Supabase, Resend, Sentry, GA4) and upgrade one line at a time only when its specific trigger fires

Every tool has a production-usable free tier, so pre-buying Pro pays for headroom you have not earned.

Set every production env var in Vercel settings scoped to Production, Preview, or Development, never ship them in the repo

Committed secrets get published to GitHub and separate scopes stop a preview from writing production data.

Run eslint directly as its own script step in both the ship gate and CI, never next lint

next lint is removed and next build no longer runs the linter, so skipping this means lint never runs.

Run one GitHub Actions verify job of five steps (typecheck, lint, check:content, test, build) on every PR and push to main

A green Vercel build only proves it compiled, so types, lint, content, and tests need their own gate.

Use vitest run, never bare vitest, for the CI test step

Bare vitest stays in watch mode and CI hangs forever.

Require the verify check and up-to-date branches, require a PR with one approval, and disallow bypass for everyone including admins

A gate admins can bypass does not exist, because the one midnight bypass is when the broken build ships.

Point the domain at Vercel with exactly an A record on the apex and a CNAME on www, deleting stale records first and keeping Cloudflare DNS-only

The apex cannot be a CNAME, and stale or orange-cloud-proxied records are the top reasons a domain will not connect.

Never treat implemented as shipped; shipping includes brand, edge cases, empty states, the phone view, and verifying the rendered live output

A passing build only confirms it compiled, nothing about whether the page looks right or works.

Deploy to Vercel via GitHub push with main as production, feature branches as previews, and run npm run ship locally first

Previews build from the exact commit that ships and the local gate makes CI a backstop, not a surprise.

Pin the same Node major (20.x or 22.x) locally, in CI, and on Vercel

Matching versions means a green build locally and in CI almost certainly means Vercel is green too.

Open the live page, click every button, check both themes, resize to phone, verify the share card, and ship a real favicon with no dead links

Each check catches a class of bug the build never will, and a default icon or 404 is the loudest unfinished tell.

Cache only what is identical for everyone and tag it; never cache a per-user response under a key that omits the user

A user-specific response under a shared key leaks one user's data to another.

Use next/image with width, height, and sizes, never a raw full-resolution img tag

Next serves a fitted modern-format image and reserves layout space to avoid CLS.

Every logging path must swallow its own errors and never rethrow

Logging is a side effect on the hot path and must never take down the request it only observes.

Keep PII out of log fields and the msg string by default, with key-based redaction in the logger as a backstop

Doing redaction in the logger stops any call site leaking personal data, but it cannot catch concatenated values.

Use NEXT_PUBLIC_SENTRY_DSN in the browser, keep SENTRY_AUTH_TOKEN secret, and set deleteSourcemapsAfterUpload so maps strip from the public bundle

A server-only DSN captures nothing client-side while a leaked token or shipped source map exposes your source.

Run client instrumentation only from instrumentation-client.ts, not the legacy sentry.client.config.ts

Next 16 only executes client instrumentation from instrumentation-client.ts.

Never paste a generic policy template you never read; treat any data-flow change (analytics, processor, OAuth scope) as shipping with a policy edit

A policy describing data flows you do not have is a promise you are silently breaking.

Cache rarely-changing shared reads with use cache plus cacheLife, invalidate by tag, and wrap request-time parts in Suspense

Recomputing identical data per request wastes work while tags keep precise control over staleness.

Default to cursor (keyset) pagination for feeds and paginate every list that can grow, using offset only for small fixed page-number UIs

An unbounded findMany stalls the page as the table grows, while keyset seeks straight to the cursor row at constant cost.

Emit one structured JSON line per event with a namespaced name (domain.action.outcome), forward warnings and errors to Sentry from the log helper, and await log.flush() before a serverless handler returns

Queryable events beat free text, helper-level forwarding reports every error with no call-site changes, and flushing stops a freezing instance dropping sends.

Ship privacy, terms, disclaimer, and data-deletion pages under one indexable /legal prefix, linked from the footer and signup with stored consent

These are the gates Google sign-in, AdSense, and app stores check, and a page no one can find does not count.

Log decisions worth an incident review (payment received, webhook rejected, rate limit, auth failure, job done or failed), not entered-function chatter

A handful of well-named events per flow beats a hundred console.logs that bury the signal.