fix(build): avoid __dirname shim conflicts and cover node_modules

packages/vinext/src/config/next-config.ts

@@ -14,6 +14,7 @@ import { PHASE_DEVELOPMENT_SERVER } from "vinext/shims/constants";
 import { normalizePageExtensions } from "../routing/file-matcher.js";
 import { isExternalUrl } from "./config-matchers.js";
 import { loadTsconfigPathAliasesForRoot } from "./tsconfig-paths.js";
+import { maskStringsAndComments } from "../utils/mask-source.js";
 
 /**
  * Parse a body size limit value (string or number) into bytes.
@@ -521,6 +522,68 @@ export function reassignsModuleExports(source: string): boolean {
   return /\bmodule\s*\.\s*exports\b\s*(?:=(?!=)|\.\s*[A-Za-z_$][\w$]*\s*=(?!=)|\[)/.test(source);
 }
 
+/**
+ * Detect which of the CJS-style identifiers (`__filename`, `__dirname`) the
+ * user already declares themselves with `const`, `let`, or `var`. Used by the
+ * injector to skip duplicate declarations that would otherwise fail with
+ * "Identifier `__dirname` has already been declared" under OXC/Rolldown.
+ *
+ * Skips identifiers that appear inside strings, template literals, and
+ * comments so a docstring like `/* sets __dirname *\/` doesn't suppress the
+ * shim. Recognizes plain bindings (`const __dirname = ...`), comma-continued
+ * declarators (`const x = 1, __dirname = ...`), and identifier destructuring
+ * (`const { __dirname } = ...` / `const { foo: __dirname } = ...`). Bare
+ * declarations without initializer (`let __dirname;`) are also caught — they
+ * still create a binding that collides with the injected `const`.
+ *
+ * False negatives are the safe failure mode: if we fail to detect a
+ * declaration, the existing collision error surfaces (no silent miscompile).
+ * False positives would skip the shim and turn an injected `const` into a
+ * ReferenceError, so the regex deliberately requires a binding keyword and
+ * skips string/template/comment contexts.
+ */
+export function findUserDeclaredCjsGlobals(source: string): {
+  __dirname: boolean;
+  __filename: boolean;
+} {
+  const declared = { __dirname: false, __filename: false };
+
+  // First pass: blank out comments / strings / template literals so
+  // identifiers inside them aren't matched. Indices stay aligned with the
+  // original source so the second-pass statement extraction can rely on
+  // positions when needed.
+  const masked = maskStringsAndComments(source);
+
+  // Second pass: for each `const|let|var` declarator statement, look at
+  // the head of the statement (up to the next `;` or top-level statement
+  // boundary) for `__dirname`/`__filename` appearing in a binding position.
+  //
+  // Binding position = preceded (after whitespace) by the declarator
+  // keyword itself, a comma, an opening brace, or a colon (object-pattern
+  // alias). Anything preceded by `=` is the initializer side and ignored,
+  // so `const x = __dirname;` does NOT count as declaring `__dirname`.
+  //
+  // The trailing negative lookahead `(?!\s*:)` ensures we do not treat the
+  // *property key* of an object-pattern alias as a binding. In
+  // `const { __dirname: localAlias } = ...`, the actual bound identifier
+  // is `localAlias`; the literal text `__dirname` is the source-side key,
+  // not a top-level declaration that would collide with the injector.
+  const declStmt = /\b(const|let|var)\b([^;]*)/g;
+  let stmt: RegExpExecArray | null;
+  while ((stmt = declStmt.exec(masked)) !== null) {
+    const body = stmt[2];
+    const bindingRegex = /(?:^|[,{:]|\b(?:const|let|var)\b)\s*(__dirname|__filename)\b(?!\s*:)/g;
+    let bind: RegExpExecArray | null;
+    while ((bind = bindingRegex.exec(body)) !== null) {
+      const name = bind[1];
+      if (name === "__dirname") declared.__dirname = true;
+      else if (name === "__filename") declared.__filename = true;
+    }
+    if (declared.__dirname && declared.__filename) break;
+  }
+  return declared;
+}
+
 /**
  * Vite plugin that prepends CJS-style globals (`__filename`, `__dirname`,
  * `module`, `exports`, `require`) to the next.config.* source before
@@ -588,12 +651,27 @@ function cjsGlobalsInjectorPlugin(configPath: string): {
           `export const ${VINEXT_CJS_INITIAL_KEY} = __vinextInitialExports;\n`
         : "";
 
+      // Skip injecting `__dirname` / `__filename` shims when the user has
+      // already declared the same identifier with `const` / `let` / `var`.
+      // OXC/Rolldown reject a duplicate `const` declaration with
+      // "Identifier `__dirname` has already been declared", which is a real
+      // pattern in next.config.ts files written for Next.js v16 (Next.js
+      // sometimes ships configs containing `const __dirname =
+      // fileURLToPath(import.meta.url)` to polyfill the ESM module scope).
+      // The user's own declaration carries the same value semantics we'd
+      // inject, so dropping our line is correct, not a behavioural change.
+      const userDeclared = findUserDeclaredCjsGlobals(code);
+
       // Preamble runs after ESM imports are hoisted; the const bindings shadow
       // any global lookups the source would otherwise perform.
+      const filenameLine = userDeclared.__filename
+        ? ""
+        : `const __filename = ${filenameLiteral};\n`;
+      const dirnameLine = userDeclared.__dirname ? "" : `const __dirname = ${dirnameLiteral};\n`;
       const preamble =
         `import { createRequire as __vinextCreateRequire } from "node:module";\n` +
-        `const __filename = ${filenameLiteral};\n` +
-        `const __dirname = ${dirnameLiteral};\n` +
+        filenameLine +
+        dirnameLine +
         `const require = __vinextCreateRequire(${requireBaseLiteral});\n` +
         moduleLines;
 

packages/vinext/src/index.ts

@@ -125,6 +125,7 @@ import {
   type BundleBackfillChunk,
 } from "./build/ssr-manifest.js";
 import { stripServerExports } from "./plugins/strip-server-exports.js";
+import { cjsGlobalsShimPlugin } from "./plugins/cjs-globals-shim.js";
 import { hasMdxFiles } from "./utils/mdx-scan.js";
 import { scanPublicFileRoutes } from "./utils/public-routes.js";
 import tsconfigPaths from "vite-tsconfig-paths";
@@ -2269,6 +2270,10 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
     },
     // Stub node:async_hooks in client builds — see src/plugins/async-hooks-stub.ts
     asyncHooksStubPlugin,
+    // Inject __dirname / __filename shims into bundled node_modules code that
+    // touches the CJS globals in ESM server output —
+    // see src/plugins/cjs-globals-shim.ts
+    cjsGlobalsShimPlugin,
     createInstrumentationClientTransformPlugin(() => instrumentationClientPath),
     // Dedup client references from RSC proxy modules — see src/plugins/client-reference-dedup.ts
     ...(options.experimental?.clientReferenceDedup ? [clientReferenceDedupPlugin()] : []),

packages/vinext/src/plugins/cjs-globals-shim.ts

@@ -0,0 +1,150 @@
+import type { Plugin } from "vite";
+import { maskStringsAndComments } from "../utils/mask-source.js";
+
+/**
+ * Detect whether the source contains a bare reference to `__dirname` or
+ * `__filename` outside of strings, template literals, and comments. Mirrors
+ * the conservative "skip masked spans first" strategy used by
+ * {@link findUserDeclaredCjsGlobals} so a docstring like
+ * `/* uses __dirname *\/` doesn't force the shim into modules that don't
+ * actually need it.
+ *
+ * The return value reports each identifier independently so the injected
+ * preamble can hoist only the bindings actually used by the module — keeping
+ * the per-module patch size minimal and avoiding spurious imports.
+ */
+export function detectCjsGlobalReferences(source: string): {
+  __dirname: boolean;
+  __filename: boolean;
+} {
+  // Quick reject: the strict masked scan below is comparatively expensive on
+  // hot paths (every node_modules .js/.mjs/.cjs goes through the transform
+  // pipeline), so first verify the source contains the identifier at all.
+  if (!/__dirname|__filename/.test(source)) {
+    return { __dirname: false, __filename: false };
+  }
+
+  const masked = maskStringsAndComments(source);
+
+  return {
+    __dirname: /\b__dirname\b/.test(masked),
+    __filename: /\b__filename\b/.test(masked),
+  };
+}
+
+/**
+ * Per-module preamble that defines `__dirname` / `__filename` for ESM-bundled
+ * CommonJS code. Used as the body of the {@link cjsGlobalsShimPlugin}
+ * transform output.
+ *
+ * The bindings are scoped to the transformed module (Vite's `transform`
+ * runs before bundling, so each module's source is patched independently).
+ * After Rolldown concatenates modules, the bindings become unique top-level
+ * `const`s in the bundle thanks to the bundler's identifier renaming.
+ *
+ * `import.meta.url` resolves to the *bundle's* output URL at runtime, not
+ * the original `node_modules` location. That is intentional: the goal of
+ * this shim is to prevent `ReferenceError: __dirname is not defined` for
+ * libraries that touch these identifiers defensively (e.g. `typeof
+ * __dirname === "string"`, log paths, debug strings). Libraries that load
+ * sibling assets through `__dirname` need to be externalized instead — a
+ * shim cannot recreate the original on-disk layout post-bundle.
+ *
+ * The helper imports are aliased so they cannot collide with user-declared
+ * names like `dirname` or `fileURLToPath` already imported by the module.
+ */
+export function buildCjsGlobalsShimPreamble(needs: {
+  __dirname: boolean;
+  __filename: boolean;
+}): string {
+  if (!needs.__dirname && !needs.__filename) return "";
+
+  const lines: string[] = [`import { fileURLToPath as __vinext_fileURLToPath } from "node:url";`];
+  if (needs.__dirname) {
+    lines.push(`import { dirname as __vinext_dirname } from "node:path";`);
+  }
+  if (needs.__filename) {
+    lines.push(`const __filename = __vinext_fileURLToPath(import.meta.url);`);
+  }
+  if (needs.__dirname) {
+    // Reuse the local __filename when we already declared it, otherwise
+    // compute it inline. Avoids declaring an unused __filename binding.
+    if (needs.__filename) {
+      lines.push(`const __dirname = __vinext_dirname(__filename);`);
+    } else {
+      lines.push(`const __dirname = __vinext_dirname(__vinext_fileURLToPath(import.meta.url));`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Vite plugin that injects local `__dirname` / `__filename` shims into
+ * third-party `node_modules` code that references those CJS globals but is
+ * bundled into an ESM server output (`"type": "module"`).
+ *
+ * Why: vinext's production server build emits ESM (`output.format: "esm"`,
+ * `package.json#type === "module"`). The Node ESM module scope does not
+ * expose the CJS-style `__dirname` / `__filename` globals, so any
+ * `node_modules` dependency that touches them — even defensively, like
+ * `typeof __dirname === "string"` or for log messages — crashes the bundled
+ * worker with `ReferenceError: __dirname is not defined in ES module scope`.
+ *
+ * vinext already injects these shims into the user's `next.config.ts`
+ * (see `config/next-config.ts`), but that transform is keyed to the config
+ * file path. Third-party packages bundled into the server entry need the
+ * same treatment, scoped per-module so user code declaring its own
+ * `__dirname` is unaffected.
+ *
+ * Scope:
+ *   - Only `node_modules` files (user code stays untouched — user-source
+ *     `__dirname` is a real bug we want to surface, not silently shim).
+ *   - Only `.js` / `.mjs` / `.cjs` extensions (TypeScript files inside
+ *     `node_modules` are unusual and typically pass through their own
+ *     compiler first).
+ *   - Only server-side environments (`ssr`, `rsc`). The browser environment
+ *     doesn't ship CJS globals at all and clients almost never reference
+ *     them — adding a shim there would inject `node:url` imports that the
+ *     browser-target build would have to externalize.
+ *
+ * Limitation: `import.meta.url` after bundling points at the *bundle*, not
+ * the original module location. Libraries that load sibling files through
+ * `__dirname` (native `.node` addons, embedded `.wasm`, etc.) should be
+ * externalized via `next.config.serverExternalPackages` instead. This shim
+ * only prevents the `ReferenceError`; it does not preserve filesystem
+ * semantics.
+ */
+export const cjsGlobalsShimPlugin: Plugin = {
+  name: "vinext:cjs-globals-shim",
+  enforce: "pre",
+
+  transform: {
+    filter: { id: /\/node_modules\/.+\.(?:m?js|cjs)(?:\?.*)?$/ },
+    handler(code, id) {
+      // Server-only: see plugin docstring. The Vite environment API exposes
+      // the current environment name to plugin handlers via `this.environment`.
+      const envName = this.environment?.name;
+      if (envName !== "ssr" && envName !== "rsc") return null;
+
+      // `id` is consumed by the Vite filter (the regex above admits ids
+      // with optional `?…` cache busters) and is not used inside the
+      // handler body — the transform only operates on the source text.
+      void id;
+
+      const needs = detectCjsGlobalReferences(code);
+      if (!needs.__dirname && !needs.__filename) return null;
+
+      const preamble = buildCjsGlobalsShimPreamble(needs);
+      return {
+        code: preamble + code,
+        // Source map is intentionally null: the preamble is prepended without
+        // line offsets in the original source map. A precise map would
+        // require MagicString plumbing; the trade-off here favours zero
+        // overhead in the hot transform path. Stack traces still resolve to
+        // the original source via the bundler's combined sourcemap once the
+        // module is concatenated.
+        map: null,
+      };
+    },
+  },
+};

packages/vinext/src/utils/mask-source.ts

@@ -0,0 +1,39 @@
+/**
+ * Source-masking helpers shared by the CJS-global shim plugins.
+ *
+ * Both the `next.config.ts` injector (`config/next-config.ts`) and the
+ * `node_modules` shim (`plugins/cjs-globals-shim.ts`) need to scan source
+ * code for bare identifier references / declarations *without* matching
+ * tokens that happen to appear inside string literals, template literals,
+ * or comments. They originally inlined the same regex; this module owns
+ * the canonical version so the two callers cannot drift apart.
+ */
+
+/**
+ * Single alternation that captures (and consumes) each kind of span we
+ * want to ignore. Order matters: the block-comment branch must come
+ * before the line-comment branch so `/* ... *\/` containing `//` is
+ * matched as one block, and string-literal branches must consume the
+ * full literal so embedded `*\/` or `//` don't terminate the wrong span.
+ *
+ * Template literals are matched segment-by-segment, stopping before
+ * `${` so the interpolation contents themselves remain visible to the
+ * scan (`__dirname` inside `${__dirname}/views` is a real reference).
+ */
+const MASK_REGEX =
+  /\/\*[\s\S]*?\*\/|\/\/[^\n]*|`(?:[^`\\$]|\\.|\$(?!\{))*`|"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g;
+
+/**
+ * Replace strings, template literals, and comments in `source` with an
+ * equal-length run of spaces. Preserves byte/character offsets so the
+ * returned string can be scanned with regexes whose match indices line up
+ * with positions in the original source — useful when callers later need
+ * to extract surrounding context (e.g. statement boundaries).
+ *
+ * Template-literal *expressions* (`${...}`) remain visible after masking
+ * because the regex stops before `${`. Identifiers used inside an
+ * interpolation are real references and must not be hidden.
+ */
+export function maskStringsAndComments(source: string): string {
+  return source.replace(MASK_REGEX, (m) => " ".repeat(m.length));
+}