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. NEXT_PUBLIC_ variables cannot be used in server-only files

Next.js exposes NEXT_PUBLIC_* variables to the browser. These must never appear in server-only files such as API routes, route handlers, middleware, or .server.ts files.

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

Warning:
NEXT_PUBLIC_ variable used in server-only file

2. 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

3. 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

4. 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)

5. 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, TOKEN, KEY, 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(import.meta.env.NEXT_PUBLIC_SECRET_KEY);
}

Warning:
Sensitive data marked as public

Summary of All Rules

  • NEXT_PUBLIC_* → cannot be used in server-only modules
  • Client components → may only use NEXT_PUBLIC_*
  • Server files (API routes, route handlers) → may use private variables

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.
  • Be explicit about client/server boundaries using "use client".
← SvelteKit Ignoring Comments →