Secure Next.js Application Structure#

Next.js gives you a strong framework for shipping fast, but speed is no excuse to postpone security decisions. If even a small team sets a few ground rules up front, the result is a less fragile, more readable application that is healthier for SEO.

This guide is not tied to one framework version. Its focus is the practical set of rules that has accumulated since the App Router stabilised in 13.4, combined with the security decisions that go with them.

Threat Model: What Should the Client See, and What Belongs on the Server?#

A modern Next.js application and its boundaries:

[Browser]
   |
   |  (1) HTML / RSC payload / client JS
   v
[Next.js edge or node server]
   |
   |  (2) server action / route handler
   v
[DB / SMTP / third-party API]

Three boundaries; three different permission levels:

1. Everything sent to the browser is public. Any string that ends up in the bundle can be read by anyone. That is why a variable with the NEXT_PUBLIC_ prefix cannot keep a secret.
2. Server actions and route handlers are public HTTP endpoints. Every function that accepts a POST must carry an authorisation check.
3. The DB and third-party APIs are server-side. Only a server component, route handler, or server action should touch them.

The rule "hiding a button is not protection" applies here too: a button that is conditionally rendered on the client can still send a request to the endpoint from the network panel; the endpoint must do its own authorisation.

Trust Boundaries: Draw the Boundaries#

Request flow and control points:

Browser fetch('/api/contact', {method: 'POST'})
      |
      v
middleware.ts  ---- token present?   (presence check only; not real authz)
      |
      v
route.ts  ------ validate(input) -> authorize(user) -> rate limit
      |
      v
db.insert(...) / smtp.send(...) / thirdParty.fetch(...)
      |
      v
Response (same error message, zero stack trace)

Do not do authorisation in middleware; there, only check presence. The actual authorisation decision happens inside the handler, after the user context is loaded and compared against the resource owner.

Split Environment Variables in Two#

Variables that start with NEXT_PUBLIC_ go to the browser. So an API key, SMTP password, database password, or private token must never be held under that prefix.

A practical split:

Turning this split into a code-review rule reduces the data leaks you will create later.

With the server-only marker you can turn an accidental import of a data-access module into the Client Component tree into a build error. That does not make the returned value safe: a prop passed from a Server Component and the rendered content travel to the browser in the HTML/RSC response. The Next.js DAL example authorises on the server and returns only the necessary DTO fields. What matters is not whether a field exists in the env or the database, but whether it crosses the response boundary.

A typical example: if NEXT_PUBLIC_STRIPE_SECRET is defined by mistake, the secret may not appear in the next build output, but the naming error can be caught with a broad search:

grep -rn "NEXT_PUBLIC_" --include="*.ts" --include="*.tsx" -l |
  xargs grep -H "SECRET\|PASSWORD\|PRIVATE\|TOKEN\|KEY"

This search only produces naming-error candidates; a secret that does not match does not prove it is safe. If a public variable is genuinely referenced, its value can be embedded in the browser bundle at build time. Fixing a leaked value by renaming is not enough; key revocation/rotation and inspection of the published artifact are required.

One more principle for .env files: .env.local must not enter git; keep a single .env.example in the repo that contains the variable names and no values. In CI, rely on the platform's secret management rather than dotenv: Environment Variables on Vercel, systemd EnvironmentFile= on your own server, or Docker --env-file.

Make Route Handlers a Validation Layer#

Sending data from a form straight to email, a database, or a third-party API is risky. At minimum, a route handler should do these checks:

1. Are the required fields present?
2. Is the email format valid?
3. Is the text length reasonable?
4. Is the user sending requests too often?
5. Does the error message leak sensitive information?

These checks look simple but are the most commonly skipped points in real projects.

A minimal route handler skeleton:

import { z } from 'zod'
 
const schema = z.object({
  email: z.string().email().max(254),
  message: z.string().min(10).max(2000),
})
 
export async function POST(req: Request) {
  const body = await req.json().catch(() => null)
  const parsed = schema.safeParse(body)
  if (!parsed.success) {
    return Response.json({ error: 'invalid_input' }, { status: 400 })
  }
  // rate limit check here
  // business logic here
  return Response.json({ ok: true })
}

Returning a single invalid_input instead of a detailed validation error to the client does not leak what was tested. The same single-message approach applies to the 404/403 distinction: if "this resource does not exist" and "this is not open to you" are returned with different messages, endpoint discovery becomes easier.

Rate Limiting#

A per-IP counter merges users behind a NAT; a per-user counter alone can be defeated with new accounts. In a contact form, weigh IP together with the target/account context; in an authenticated API, weigh the actor together with the operation cost. A local Map does not provide a shared quota in a multi-process or serverless deployment. In shared storage, counter increments and expiry must be atomic; you should not need a separate cron to reset the window. In a 429 response, Retry-After is the wait information; the X-RateLimit-* fields are application convention, so do not assume these names are a universal HTTP standard.

POST /api/contact
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
Retry-After: 60
HTTP 429

Server Actions: The Authorisation Layer Goes Inside the Action#

Server Actions are functions that can be called as a form action or an event handler. Every server action is an endpoint that can be called directly from the browser via POST. Therefore:

• Verify the user session on the first line of every action.
• Check the owner when accessing a resource.
• Validate the input with zod or a similar schema.
• Return only the necessary fields in the response.

'use server'
export async function updateProfile(input: unknown) {
  const user = await getSessionUser()
  if (!user) throw new Error('unauthorized')
  const parsed = profileSchema.parse(input)
  await db.update(user.id, parsed)
}

Rather than rendering data that comes from the server inside a "use client" subtree, fetch it in a server component; this reduces the risk of leaking data on the client.

Manage Metadata and Canonical URLs Centrally#

The most common SEO problem is the same content repeating at different URLs. On multilingual sites this grows faster. If you use clear language roots like /en and /tr, produce the canonical and hreflang relationship explicitly on every page.

A good page should carry:

• A language-based canonical URL
• Alternate language links
• A descriptive title and description
• An Open Graph image
• Article, Breadcrumb, or WebSite JSON-LD schema

Example metadata generation:

export async function generateMetadata({ params }): Promise<Metadata> {
  const { lang } = await params
  return {
    alternates: {
      canonical: `/${lang}/posts/example`,
      languages: { en: '/en/posts/example', tr: '/tr/posts/example' },
    },
    openGraph: { images: ['/og/example.png'] },
  }
}

Separate Components by Behaviour#

Let the server component be the default. Use a client component only where state, an event handler, a theme, or a browser API is needed. This both reduces bundle size and keeps data access safer.

Example decision:

When a server component imports a 'use client' subtree, data passing into that subtree happens through serialisation. For that reason, send only the needed field (like id, title, isPublic) as a prop from server to client; do not download the raw DB record as-is.

Detection and Mitigation Workflow#

Ways to detect a security weakness:

Each row is a code-review checklist item. Copy this list into your PR template; every PR should touch one item.

Mitigation workflow:

1. Reproduce the finding in staging.
2. Apply the fix with the smallest possible surface.
3. Test in production mode with next build && next start; the dev server behaves differently.
4. Write a regression test that exercises the old behaviour.
5. Report the change with its commit hash.

Version Differences: Next 13 -> 14 -> 15#

• Next 13.4+: the App Router is stable, the app/ directory and server components are standard.
• Next 14: Server Actions became stable; form actions are now native. The bundled metadata API is the same, but streaming SSR is more mature.
• Next 15: params and searchParams now return asynchronously (a Promise); the old sync usage is deprecated. Cache behaviour is more conservative: GET route handlers are not cached by default.
• Middleware/Proxy: the runtime and naming depend on the installed Next.js version; do not pick a library on the assumption of "always Edge". Either way, authorisation in the data-access layer must remain independent of the early route check.
• next.config.js: small settings like poweredByHeader: false, reactStrictMode: true, and an images.remotePatterns allowlist narrow the defence surface.

Keep these differences as a note on behaviour, not a version checklist, by looking at the next field in package.json. Re-verify route handler cache behaviour after an upgrade.

// next.config.js
module.exports = {
  poweredByHeader: false,
  reactStrictMode: true,
  images: { remotePatterns: [{ protocol: 'https', hostname: 'cdn.example.com' }] },
}

ASCII: Security Control Points#

Request
  |
  v
[1] middleware: is the session cookie present?
  |  if not: 302 /login
  v
[2] route handler: validate with zod
  |  on failure: 400 {error: 'invalid_input'}
  v
[3] authz: is the current user the owner of this resource?
  |  if not: 404 (do not leak existence)
  v
[4] rate limit: quota per IP/user
  |  if exceeded: 429 + Retry-After
  v
[5] business logic + DB / SMTP / API
  v
Response: only the necessary fields, a generic error message

Each box is a line of code; the five layers should not be squeezed into a one-page middleware, but each should be an explicit file and test.

Conclusion#

A secure Next.js structure does not require a large framework change. Correct env separation, validated route handlers, language-based metadata, and a server-component default deliver a serious quality improvement even in small teams. The real difference is turning these rules from "things to remember" into "items in the PR template".

Security Headers#

What to add via next.config.js:

module.exports = {
  poweredByHeader: false,
  reactStrictMode: true,
  async headers() {
    return [{
      source: '/:path*',
      headers: [
        { key: 'X-Content-Type-Options', value: 'nosniff' },
        { key: 'X-Frame-Options', value: 'DENY' },
        { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
        { key: 'Permissions-Policy', value: 'camera=(), microphone=()' },
        { key: 'Content-Security-Policy', value: "default-src 'self'" },
      ],
    }]
  },
}

This CSP value is not a Next.js policy to copy straight into production: it can also block the bootstrap/hydration scripts you need. A nonce must be generated with cryptographic randomness, change per response, and be bound into both the CSP and the permitted scripts. First observe the needed resources in report-only mode, then turn on enforcement and exercise the production page's hydration and action flow. Build this link instead of adding unsafe-inline; also prevent a nonce-bearing HTML response from being reused in a shared CDN cache.

Authentication Approach#

NextAuth/Auth.js manages session and callback flows. Set session cookies httpOnly and secure in production, then choose SameSite for the actual cross-site callback and embedding requirements (Lax is a common default, not a universal rule). Generate the secret using the installed Auth.js/NextAuth version's supported configuration and keep a rotation plan. Keep refresh/session tokens out of localStorage; XSS can expose tokens stored there.

Form Security: CSRF and SameSite#

Server Actions have a framework check that compares the Origin against the Host or trusted proxy header; this does not mean separate Route Handlers are automatically protected too. A state-changing handler authorised by a cookie needs an explicit CSRF design. SameSite uses the "site" boundary, not the origin boundary; on its own it does not close an attacker-controlled sibling subdomain scenario. Re-auth is an extra control for sensitive operations, not a replacement for CSRF prevention.

Logging and Error Handling#

In production, never send console.log(user) or a raw error stack trace to the client. Use a central server-side logger; record the request ID, actor, action, resource or policy decision, and outcome needed for investigation, with access and retention limits. IP addresses and user IDs may be personal data, so collect only what the incident and audit purpose requires. Return a generic client error such as { error: 'internal_error' }.

Deploy and Secret Rotation#

This cycle turns changing a secret on a live system from a one-off panic into a routine.

CI/CD Side#

Set up a CI pipeline that does not need secrets to run next build. If env variables carry the NEXT_PUBLIC_ prefix they are embedded in the build output; so do not pass secrets as build arguments. Running a leak hunt script like grep -R "NEXT_PUBLIC_.*SECRET" in CI is a cheap guarantee before deploy.

Example Checklist (Copy Into Your PR Template)#

• New env variables were added to .env.example, without values.
• No secret without the NEXT_PUBLIC_ prefix is sent to the browser.
• The route handler/action validates input with zod.
• The authorisation check is inside the action, on the first line.
• A rate limit was applied.
• The error message is generic; the stack trace does not reach the client.
• Canonical/hreflang metadata is generated per page.
• Headers are defined in next.config.js.
• No console.log remains; the logger is used.

Pasting this list into your PR template takes security decisions out of the realm of "things to remember".

Related Research & Internal References#

• Private Pages, noindex, and Authentication in Next.js - Why hiding a page is not the same as protecting it.
• Server Actions Authorisation - Treating every action as a public endpoint.
• Security Logging Design - Structuring the server-side log this guide relies on.