Sign in Subscribe
Software

Content-Security-Policy in Next.js: Environment-Aware Headers, connect-src Rules, and Realtime Pitfalls

Abhinav Singh

Abhinav Singh

— 5 min read
Content-Security-Policy in Next.js: Environment-Aware Headers, connect-src Rules, and Realtime Pitfalls

Content-Security-Policy (CSP) is often treated as a box to check: paste a template from OWASP, sprinkle a few nonces, and call it secure. But in modern application stacks especially those built on the Next.js App Router, React Server Components, and real-time GraphQL connections a static CSP is not just insufficient; it’s dangerous. It can silently block hydration, kill WebSocket upgrades, or collapse real-time telemetry flows without leaving meaningful traces.

In this deep dive, we’ll walk through the architecture, reasoning, and real-world pitfalls of implementing environment-aware CSP rules with headers() in the App Router. The focus is on one directive that causes disproportionate engineering pain: connect-src.

Along the way, I’ll share how we use environment-specific CSP at Hoomanely, where our fleet of SoM-based devices—Tracker, EverBowl, and EverHub—relies on real-time telemetry ingestion. While the frontends powering our internal dashboards are cloud-based rather than device-hosted, the same CSP considerations apply whenever you need streaming logs, live device health, or gated admin access to real-time channels.

Problem: Why CSP Breaks Modern Next.js Apps

A CSP is meant to restrict where scripts, images, fonts, and connections can originate. But the web of 2025 is no longer static HTML + JS. A modern Next.js app includes:

  • React Server Components that interleave server and client execution
  • Streaming responses that rely on hydration scripts
  • Edge-rendered layouts that preload data
  • GraphQL clients that batch requests and retry over multiple transports
  • Real-time connections using WebSockets, SSE, or AppSync subscriptions
  • Analytics and monitoring scripts that spin up background connect events

A static CSP template is usually unaware of these interactions. A single missing directive can cause failures like:

  • Hydration never starts because inline bootstrap scripts are blocked
  • WebSocket connections silently downgrade or fail
  • GraphQL subscriptions disconnect immediately
  • AppSync real-time endpoints are blocked
  • Inline nonce mismatches between RSC and client shell
  • Dev tools stop working (Next dev server is heavily dependent on ws://localhost connections)

And the worst part? Next.js will render the page without errors, leaving you debugging a "suspected race condition" when the culprit is simply a too-strict CSP.

This is why CSP must be environment-aware, not “copy-pasted once and deployed forever.”

Why It Matters: CSP Is Not One Policy - It's Three

A correct CSP is inherently tied to its environment:

1. Development

  • Requires localhost:* connections
  • Requires WebSocket dev channel
  • Often uses eval-like constructs internally
  • Uses inline scripts for fast refresh
  • Requires permissive connect-src

2. Staging

  • Requires real backend domains
  • Needs AppSync/GraphQL endpoints
  • Still requires debugging and observability tools
  • Should be stricter than dev but not prod

3. Production

  • Must eliminate unsafe code
  • Must use nonces or hashes for bootstrap scripts
  • Must explicitly allow only real domains
  • Must support real-time connections without wildcard fallbacks

Trying to use one CSP for these three worlds will produce fragile, brittle apps.

A well-designed CSP should be flexible where it must be, strict where it can be.

Architecture: Designing an Environment-Aware CSP Model

A resilient CSP for the App Router typically adopts a layered approach:

Layer 1: Core Structure

A predictable CSP for Next.js App Router apps often includes:

default-src 'self';
script-src 'self' 'nonce-{nonce}';
style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:;
font-src 'self';
connect-src <dynamic>;

Everything in this template is stable except connect-src.
This is where DX, real-time communication, and production lockdown collide.

Layer 2: The connect-src Expansion Pack

To support real-time systems, connect-src must anticipate:

  • REST fetches
  • GraphQL queries/mutations
  • GraphQL subscription endpoints
  • AppSync real-time endpoint
  • WebSocket fallback transports
  • SSE event streams
  • Analytics ingestion
  • CDN-backed prefetching

These connections vary dramatically across environments.

Layer 3: Per-Environment Merge Rules

A practical pattern:

connect-src 'self' http://localhost:* ws://localhost:* https://*.ngrok.io data:;

Why so permissive?

  • Fast Refresh uses WebSockets
  • Vite-style tools (if present) use event streams
  • Dev tunnels need wildcard domains
  • Errors appear instantly instead of failing silently

Staging

connect-src 'self' https://staging-api.example.com wss://staging-rt.example.com https://*.amazonaws.com;

Why?

  • Mirrors production
  • Allows real-time debugging
  • Restricts localhost
  • Supports CDN + AppSync

Production

connect-src 'self' https://api.example.com wss://rt.example.com https://<region>.amazonaws.com;

Why?

  • Clear, tight allow-list
  • Supports production AppSync & subscription URLs
  • Eliminates wildcard domains
  • Eliminates localhost and eval-based tools

Implementation: headers() API and Dynamic CSP

The App Router’s headers() hook lets you generate CSP per request.

Pseudo-pattern:

export function headers() {
  const env = process.env.APP_ENV;

  return [
    {
      source: "/(.*)",
      headers: [
        {
          key: "Content-Security-Policy",
          value: generateCsp(env),
        },
      ],
    },
  ];
}

Where generateCsp() returns environment-specific policies.

You can also insert per-request nonce like:

const nonce = crypto.randomUUID();

Used to unlock Next.js' RSC bootstrap script.

Real-World Usage: Where CSP Intersects IoT Dashboards

At Hoomanely, our internal tools visualize telemetry from:

  • Tracker devices (motion, altitude, external events)
  • EverBowl (body temperature, audio events, weight curves)
  • EverHub (edge inference and pipeline decisions)

Much of this data is streamed via GraphQL subscriptions or WebSocket-backed SSE.

Because real-time data is essential for validating device behavior, we run dashboards in three environments: dev, staging, production. Each environment has different transports and endpoints.

A strict but environment-unaware CSP would:

  • Block EverHub’s real-time decision logs
  • Block Tracker live positional traces
  • Block EverBowl audio event streaming
  • Prevent dev tools from connecting

By designing a configurable, environment-aware connect-src, we ensure:

  • Real-time flows in development stay fluid
  • Staging reproduces the production environment accurately
  • Production stays secure without DX sacrifices

This balance is essential in multi-device ecosystems where telemetry is time-sensitive.

Common Pitfalls: Why Realtime Breaks Silently

Engineers often encounter these issues when adding a CSP to Next.js:

1. WebSockets Blocked by Missing wss:// Domains

Next.js dev server uses WS heavily. AppSync subscriptions use a different connection URL than GraphQL queries. Forgetting the wss:// endpoint silently kills real-time features.

2. SSE Fails Because of Missing EventStream MIME Allowances

Not all real-time solutions use WebSockets.
Some require:

connect-src …;

plus ensuring no other directive blocks them.

3. Hydration Fails Because Inline Scripts Are Restricted

Next.js injects a minimal inline script to bootstrap the RSC boundary. This requires a nonce. Without it:

  • the JS bundle loads
  • the client never hydrates

4. AppSync Real-time Endpoint Not Matching Your GraphQL URL

AWS AppSync uses a secondary endpoint for subscriptions:

https://xxxxxxxx.appsync-realtime-api.<region>.amazonaws.com

Many engineers allow only:

https://xxxxxxxx.appsync-api.<region>.amazonaws.com

and subscriptions fail instantly.

5. Preload and Prefetch Requests Blocked Under connect-src

Next.js issues background requests for:

  • RSC preloads
  • Pre-rendered route segments
  • Optimistic client navigations

If connect-src doesn’t include your CDN + data source domain, prefetching dies, increasing TTFB.

Takeaways

1. CSP is not static—it’s a living specification tied to environments.
Development needs freedom; production demands precision.

2. connect-src is the hardest part of CSP for modern, real-time apps.
WebSockets, AppSync, SSE, analytics, and RSC preloads all require explicit allowances.

3. Next.js App Router relies on inline scripts that require nonce-based unlocking.
Missing this breaks hydration silently.

4. Environment-aware CSP design prevents common debugging rabbit holes.
Write code that generates CSP per environment—not a single template.

5. In multi-device IoT ecosystems, real-time data is non-negotiable.
CSP must secure production without strangling live telemetry.

Read more