chore: first class support for nuxt (#454)

Chrilleweb · web-flow · commit 7bae585b1009 · 2026-06-28T13:42:49.000+02:00
diff --git a/.changeset/ripe-ducks-flash.md b/.changeset/ripe-ducks-flash.md
@@ -0,0 +1,5 @@
+---
+'dotenv-diff': minor
+---
+
+added first class support for nuxt
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 Scan your codebase to detect every environment variable reference. It helps you catch missing, unused, duplicated, and misused variables early, before they cause runtime errors.
 
-First-class support for SvelteKit and Next.js. Also works well in modern JavaScript/TypeScript projects and frameworks like Node.js, Nuxt, and Vue — or any other setup where you want reliable .env file comparison.
+First-class support for SvelteKit, Next.js, and Nuxt. Also works well in modern JavaScript/TypeScript projects and frameworks like Node.js and Vue — or any other setup where you want reliable .env file comparison.
 
 [![Coverage Status](https://codecov.io/gh/Chrilleweb/dotenv-diff/branch/main/graph/badge.svg)](https://codecov.io/gh/Chrilleweb/dotenv-diff)
 [![npm version](https://img.shields.io/npm/v/dotenv-diff.svg)](https://www.npmjs.com/package/dotenv-diff)
@@ -52,7 +52,7 @@ Easily integrate dotenv-diff into your Git hooks or CI/CD pipelines to enforce e
 
 ## Framework-Specific Warnings
 
-In SvelteKit and Next.js projects, dotenv-diff detects framework-specific
+In SvelteKit, Next.js, and Nuxt projects, dotenv-diff detects framework-specific
 environment variable misuses.
 
 Example warning:
diff --git a/docs/frameworks/index.md b/docs/frameworks/index.md
@@ -8,6 +8,7 @@ This section explains which framework-specific environment variable are currentl
 
 - [SvelteKit warnings](./sveltekit_warnings.md)
 - [Next.js warnings](./nextjs_warnings.md)
+- [Nuxt warnings](./nuxt_warnings.md)
 
 ---
 
@@ -19,6 +20,7 @@ E.g.
 
 - If `@sveltejs/kit` is present, SvelteKit rules are enabled.
 - If `next` is present, Next.js rules are enabled.
-- If neither is detected, framework-specific warnings are skipped.
+- If `nuxt` is present, Nuxt rules are enabled.
+- If none is detected, framework-specific warnings are skipped.
 
 ---
diff --git a/docs/frameworks/nuxt_warnings.md b/docs/frameworks/nuxt_warnings.md
@@ -0,0 +1,56 @@
+# Nuxt warnings
+
+`dotenv-diff` includes Nuxt-specific rules to catch unsafe or unreliable environment variable usage.
+
+This page reflects the currently implemented rule behavior and targets Nuxt 3.
+
+## Background
+
+Nuxt exposes runtime configuration through `runtimeConfig` (private, server-only) and `runtimeConfig.public` (exposed to the client), accessed via `useRuntimeConfig()`.
+
+In production, `.env` files are **not** read at runtime, and `process.env` is **not** populated in the browser. Environment variables only override runtime config when prefixed with `NUXT_` (private) or `NUXT_PUBLIC_` (public).
+
+## 1 `process.env` in client/universal code
+
+`process.env` is unreliable outside server code: it is not available in the browser, and `.env` files are not read at runtime in production.
+
+```vue
+<script setup lang="ts">
+const key = process.env.API_SECRET; // ⚠️
+</script>
+```
+
+Warning:
+
+`process.env is not available in the browser; use useRuntimeConfig() instead`
+
+## 2 Sensitive-looking `NUXT_PUBLIC_` names trigger exposure warnings
+
+If a `NUXT_PUBLIC_` variable contains `SECRET`, `PRIVATE`, or `PASSWORD`, a warning is produced — these values are exposed to the browser.
+
+```ts
+process.env.NUXT_PUBLIC_API_SECRET;
+```
+
+Warning:
+
+`Potential sensitive environment variable exposed to the browser`
+
+## What is allowed
+
+`process.env` is allowed in server-only contexts without framework warnings:
+
+- The Nitro `server/` directory (`server/api`, `server/routes`, `server/middleware`, etc.)
+- `.server.` suffixed files (for example `plugins/auth.server.ts`)
+- `nuxt.config.{ts,js,mjs,cjs}` (where env vars feed `runtimeConfig`)
+
+## Summary of rules
+
+- `process.env` in client/universal code → use `useRuntimeConfig()`
+- Sensitive names in `NUXT_PUBLIC_*` → warning
+
+## Best practices
+
+- Use `runtimeConfig` / `useRuntimeConfig()` instead of reading `process.env` directly in app code
+- Only put browser-safe values under `runtimeConfig.public` / `NUXT_PUBLIC_*`
+- Keep secrets in server-only code paths (`server/`, `.server.` files)
diff --git a/docs/index.md b/docs/index.md
@@ -53,6 +53,7 @@ If you choose not to create a file, `dotenv-diff` will still scan your codebase
 | [Framework Warnings (Index)](./frameworks/index.md) | Framework detection and links to supported framework rules |
 | [SvelteKit warnings](./frameworks/sveltekit_warnings.md) | SvelteKit-specific env validation rules |
 | [Next.js warnings](./frameworks/nextjs_warnings.md) | Next.js-specific env validation rules |
+| [Nuxt warnings](./frameworks/nuxt_warnings.md) | Nuxt-specific env validation rules |
 
 ---
 
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -2,7 +2,7 @@
 
 Scan your codebase to detect every environment variable reference. It helps you catch missing, unused, duplicated, and misused variables early, before they cause runtime errors.
 
-First-class support for SvelteKit and Next.js. Also works well in modern JavaScript/TypeScript projects and frameworks like Node.js, Nuxt, and Vue — or any other setup where you want reliable .env file comparison.
+First-class support for SvelteKit, Next.js, and Nuxt. Also works well in modern JavaScript/TypeScript projects and frameworks like Node.js and Vue — or any other setup where you want reliable .env file comparison.
 
 [![Coverage Status](https://codecov.io/gh/Chrilleweb/dotenv-diff/branch/main/graph/badge.svg)](https://codecov.io/gh/Chrilleweb/dotenv-diff)
 [![npm version](https://img.shields.io/npm/v/dotenv-diff.svg)](https://www.npmjs.com/package/dotenv-diff)
@@ -52,7 +52,7 @@ Easily integrate dotenv-diff into your Git hooks or CI/CD pipelines to enforce e
 
 ## Framework-Specific Warnings
 
-In SvelteKit and Next.js projects, dotenv-diff detects framework-specific
+In SvelteKit, Next.js, and Nuxt projects, dotenv-diff detects framework-specific
 environment variable misuses.
 
 Example warning:
diff --git a/packages/cli/src/config/types.ts b/packages/cli/src/config/types.ts
@@ -4,7 +4,7 @@ import { type SecretFinding } from '../core/security/secretDetectors.js';
 /**
  * Supported frameworks
  */
-export type SupportedFramework = 'sveltekit' | 'nextjs';
+export type SupportedFramework = 'sveltekit' | 'nextjs' | 'nuxt';
 
 /**
  * Result of framework detection (may be unsupported)
diff --git a/packages/cli/src/core/frameworks/frameworkDetector.ts b/packages/cli/src/core/frameworks/frameworkDetector.ts
@@ -48,6 +48,14 @@ export function detectFramework(cwd: string): FrameworkDetection {
       };
     }
 
+    // Check for Nuxt
+    if (deps['nuxt']) {
+      return {
+        framework: 'nuxt',
+        version: deps['nuxt'],
+      };
+    }
+
     return { framework: 'unknown' };
   } catch {
     return { framework: 'unknown' };
diff --git a/packages/cli/src/core/frameworks/frameworkValidator.ts b/packages/cli/src/core/frameworks/frameworkValidator.ts
@@ -1,6 +1,10 @@
 import type { EnvUsage, FrameworkWarning } from '../../config/types.js';
 import { detectFramework } from './frameworkDetector.js';
-import { applySvelteKitRules, applyNextJsRules } from './index.js';
+import {
+  applySvelteKitRules,
+  applyNextJsRules,
+  applyNuxtRules,
+} from './index.js';
 
 /**
  * Validates environment variable usages against framework-specific rules
@@ -20,6 +24,7 @@ export function frameworkValidator(
   for (const u of usages) {
     if (framework === 'sveltekit') applySvelteKitRules(u, warnings);
     if (framework === 'nextjs') applyNextJsRules(u, warnings, fileContentMap);
+    if (framework === 'nuxt') applyNuxtRules(u, warnings);
   }
 
   return warnings;
diff --git a/packages/cli/src/core/frameworks/index.ts b/packages/cli/src/core/frameworks/index.ts
@@ -1,2 +1,3 @@
 export { applySvelteKitRules } from './sveltekitRules.js';
 export { applyNextJsRules } from './nextJsRules.js';
+export { applyNuxtRules } from './nuxtRules.js';
diff --git a/packages/cli/src/core/frameworks/nuxtRules.ts b/packages/cli/src/core/frameworks/nuxtRules.ts
@@ -0,0 +1,73 @@
+import type { EnvUsage, FrameworkWarning } from '../../config/types.js';
+import { normalizePath } from '../helpers/normalizePath.js';
+
+/**
+ * Nuxt environment variable validation rules.
+ *
+ * Background (Nuxt 3):
+ *  - Runtime configuration lives in `runtimeConfig` (private, server-only) and
+ *    `runtimeConfig.public` (exposed to the client) and is read via
+ *    `useRuntimeConfig()`.
+ *  - In production, `.env` files are NOT read at runtime, and `process.env` is
+ *    not populated in the browser. Direct `process.env` access in
+ *    client/universal code is therefore unreliable — `useRuntimeConfig()`
+ *    should be used instead.
+ *  - Environment variables only override runtime config when prefixed with
+ *    `NUXT_` (private) or `NUXT_PUBLIC_` (public).
+ *
+ * @param u - The environment variable usage information
+ * @param warnings - The array to push warnings into
+ */
+export function applyNuxtRules(
+  u: EnvUsage,
+  warnings: FrameworkWarning[],
+): void {
+  // Normalize path separators for cross-platform consistency
+  const normalizedFile = normalizePath(u.file);
+
+  // Ignore node_modules
+  if (normalizedFile.includes('/node_modules/')) {
+    return;
+  }
+
+  // nuxt.config.* is allowed to read process.env (it feeds runtimeConfig)
+  const isConfigFile = /(^|\/)nuxt\.config\.(ts|js|mjs|cjs)$/.test(
+    normalizedFile,
+  );
+
+  // Server-only contexts in Nuxt:
+  //  - the Nitro `server/` directory (api, routes, middleware, plugins, utils)
+  //  - `.server.` suffixed files (e.g. plugins/foo.server.ts, Foo.server.vue)
+  const isServerFile =
+    /(^|\/)server\//.test(normalizedFile) ||
+    /\.server\.(ts|js|mjs|vue)$/.test(normalizedFile);
+
+  // process.env is unreliable in client/universal code: not available in the
+  // browser and .env files are not read at runtime in production.
+  if (u.pattern === 'process.env' && !isServerFile && !isConfigFile) {
+    warnings.push({
+      variable: u.variable,
+      reason:
+        'process.env is not available in the browser; use useRuntimeConfig() instead',
+      file: normalizedFile,
+      line: u.line,
+      framework: 'nuxt',
+    });
+    return; // Stop processing other rules for this usage
+  }
+
+  // Warn if NUXT_PUBLIC_ contains sensitive keywords (exposed to the browser)
+  if (
+    u.variable.startsWith('NUXT_PUBLIC_') &&
+    /SECRET|PRIVATE|PASSWORD/.test(u.variable)
+  ) {
+    warnings.push({
+      variable: u.variable,
+      reason: 'Potential sensitive environment variable exposed to the browser',
+      file: normalizedFile,
+      line: u.line,
+      framework: 'nuxt',
+    });
+    return; // Stop processing other rules for this usage
+  }
+}
diff --git a/packages/cli/src/core/helpers/compareCodePoint.ts b/packages/cli/src/core/helpers/compareCodePoint.ts
@@ -0,0 +1,18 @@
+/**
+ * Compares two strings by UTF-16 code point order.
+ *
+ * Unlike {@link String.prototype.localeCompare}, this is fully deterministic
+ * across operating systems and locales. `localeCompare` relies on the host's
+ * ICU/collation data, which can order strings differently between platforms
+ * (e.g. on Windows it may sort ".env.zzz" before ".env.aaa"), making CLI
+ * output non-deterministic. Use this for any ordering the user can observe.
+ *
+ * @param a - The first string.
+ * @param b - The second string.
+ * @returns -1 if a < b, 1 if a > b, 0 if equal.
+ */
+export function compareCodePoint(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
diff --git a/packages/cli/src/services/envDiscovery.ts b/packages/cli/src/services/envDiscovery.ts
@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import type { Discovery } from '../config/types.js';
 import { DEFAULT_ENV_FILE, DEFAULT_EXAMPLE_FILE } from '../config/constants.js';
+import { compareCodePoint } from '../core/helpers/compareCodePoint.js';
 
 /**
  * Arguments for the discoverEnvFiles function.
@@ -34,7 +35,7 @@ export function discoverEnvFiles({
       (f) =>
         f.startsWith(DEFAULT_ENV_FILE) && !f.startsWith(DEFAULT_EXAMPLE_FILE),
     )
-    .sort((a, b) => (b === DEFAULT_ENV_FILE ? 1 : a.localeCompare(b)));
+    .sort((a, b) => (b === DEFAULT_ENV_FILE ? 1 : compareCodePoint(a, b)));
 
   let primaryEnv = envFiles.includes(DEFAULT_ENV_FILE)
     ? DEFAULT_ENV_FILE
diff --git a/packages/cli/src/services/matrixDiscovery.ts b/packages/cli/src/services/matrixDiscovery.ts
@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { DEFAULT_ENV_FILE } from '../config/constants.js';
+import { compareCodePoint } from '../core/helpers/compareCodePoint.js';
 
 /**
  * Matches `.env` itself or any `.env.*` variant (e.g. `.env.local`,
@@ -25,7 +26,7 @@ export function discoverMatrixFiles(cwd: string): string[] {
     .sort((a, b) => {
       if (a === DEFAULT_ENV_FILE) return -1;
       if (b === DEFAULT_ENV_FILE) return 1;
-      return a.localeCompare(b);
+      return compareCodePoint(a, b);
     });
 }
 
diff --git a/packages/cli/src/ui/scan/printFrameworkWarnings.ts b/packages/cli/src/ui/scan/printFrameworkWarnings.ts
@@ -20,6 +20,7 @@ import { normalizePath } from '../../core/helpers/normalizePath.js';
 const FRAMEWORK_LABELS: Record<DetectedFramework, string> = {
   nextjs: 'Next.js',
   sveltekit: 'SvelteKit',
+  nuxt: 'Nuxt',
   unknown: 'Unknown Framework',
 };
 
diff --git a/packages/cli/test/e2e/frameworks/cli.nuxt.e2e.test.ts b/packages/cli/test/e2e/frameworks/cli.nuxt.e2e.test.ts
diff --git a/packages/cli/test/unit/core/frameworks/frameworkDetector.test.ts b/packages/cli/test/unit/core/frameworks/frameworkDetector.test.ts
diff --git a/packages/cli/test/unit/core/frameworks/frameworkValidator.test.ts b/packages/cli/test/unit/core/frameworks/frameworkValidator.test.ts
diff --git a/packages/cli/test/unit/core/frameworks/nuxtRules.test.ts b/packages/cli/test/unit/core/frameworks/nuxtRules.test.ts
diff --git a/packages/cli/test/unit/core/helpers/compareCodePoint.test.ts b/packages/cli/test/unit/core/helpers/compareCodePoint.test.ts
diff --git a/packages/cli/test/unit/services/matrixDiscovery.test.ts b/packages/cli/test/unit/services/matrixDiscovery.test.ts
diff --git a/packages/cli/test/unit/ui/scan/printFrameworkWarnings.test.ts b/packages/cli/test/unit/ui/scan/printFrameworkWarnings.test.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'dotenv-diff': minor
 +---
++
 +added first class support for nuxt
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`export { applySvelteKitRules } from './sveltekitRules.js';`
`2`	`2`	`export { applyNextJsRules } from './nextJsRules.js';`
	`3`	`+export { applyNuxtRules } from './nuxtRules.js';`