Cursor + Next.js: Environment Variable Security

The rule

Next.js inlines NEXT_PUBLIC_* values into client bundles at build time. Non-prefixed variables are only available in server code (route handlers, server components, server actions, middleware).

If a client component needs data that depends on a secret, fetch it through a route handler or server action instead of reading the secret in the browser.

Enforce the boundary with server-only

Put secret-reading config in a module that imports server-only. Any accidental import from a client component fails the build.

// lib/server-env.ts
import "server-only";

export const serverEnv = {
  stripeSecret: process.env.STRIPE_SECRET_KEY!,
  supabaseServiceRole: process.env.SUPABASE_SERVICE_ROLE_KEY!,
};

Add a Cursor rule

Project rules make the AI respect the boundary in future edits.

# .cursor/rules/secrets.mdc
- Never prefix secrets with NEXT_PUBLIC_.
- Only read STRIPE_SECRET_KEY, SUPABASE_SERVICE_ROLE_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, RESEND_API_KEY in files that import "server-only".
- Client components call route handlers or server actions for privileged work.

Checklist

• Only publishable values use NEXT_PUBLIC_
• Secret config lives behind import "server-only"
• .env* files are gitignored
• Production secrets are set in the host's env settings, not committed
• Built .next/static contains no secret prefixes

Copy-paste fix prompt

Scan this Next.js project for any NEXT_PUBLIC_ variable that holds a secret and for any client component that imports server config. Create lib/server-env.ts with `import "server-only"`, move secret reads there, and replace client usage with route handlers or server actions.

FAQ