Next.js warnings

dotenv-diff includes a set of Next.js-specific rules that help you avoid unsafe or invalid environment variable usage. Next.js has strict separation between server-side and client-side code, and only variables prefixed with NEXT_PUBLIC_ may be exposed to the browser. This page explains all warnings dotenv-diff may produce when scanning Next.js projects.

1. Client components may only access NEXT_PUBLIC_ variables

Any file containing "use client" runs in the browser, and therefore can only access environment variables prefixed with NEXT_PUBLIC_.

Button.tsx 
"use client";
console.log(process.env.SECRET_TOKEN);

Warning:
Client components can only access NEXT_PUBLIC_ environment variables

2. Server-only environment variables are allowed in API routes

Next.js allows private environment variables to be accessed in server-only files without any warnings. dotenv-diff will correctly detect this and produce no issues.

app/api/user/route.ts 
export async function GET() {
  console.log(process.env.PRIVATE_KEY);
}

Allowed — no warnings

3. import.meta.env is not supported in Next.js

Next.js does not use Vite-style environment variables. Using import.meta.env will always produce a warning.

app/api/user/route.ts 
export async function GET() {
  console.log(import.meta.env.PRIVATE_KEY);
}

Warning:
Next.js uses process.env, not import.meta.env (Vite syntax)

4. Sensitive data must not be marked as NEXT_PUBLIC_

dotenv-diff warns if a NEXT_PUBLIC_ variable appears to contain sensitive data based on common keywords such as SECRET, PRIVATE or PASSWORD. This can be tricky and sometimes cause false positives, so review these warnings carefully.

app/api/user/route.ts 
export async function GET() {
  console.log(process.env.NEXT_PUBLIC_SECRET_PASSWORD);
}

Warning:
Potential sensitive environment variable exposed to the browser

Summary of All Rules

  • Client components → may only use NEXT_PUBLIC_*
  • Server files (API routes, route handlers) → may use private variables
  • import.meta.env → not supported in Next.js

Best Practices

  • Use NEXT_PUBLIC_* only for variables intended for the browser.
  • Never expose secrets through NEXT_PUBLIC_.
  • Keep private variables inside API routes or server components.
← SvelteKit Ignoring Comments →