fix: document ESM resolution workaround for validator and similar packages (#189) by yunus25jmi1 · Pull Request #193 · cloudflare/vinext

yunus25jmi1 · 2026-02-28T08:40:58Z

Summary

Fixes #189 - Documents workaround for third-party ESM packages that fail with Cannot find module errors in dev server.

Problem

Users importing certain ESM packages (like validator, uuid, date-fns/esm) encounter module resolution errors:

Cannot find module '\\node_modules.pnpm\\[email protected]\\node_modules\\validator\\es\\lib\\util\\assertString' 
imported from \\node_modules.pnpm\\[email protected]\\node_modules\\validator\\es\\lib\\isEmail.js

Root Cause

These packages have complex internal ESM import structures that Node.js module resolution handles differently than Vite. By default, Vite externalizes dependencies in SSR (loads them via native Node.js require/import), which can fail for packages with non-standard export patterns.

Solution

Add affected packages to ssr.noExternal in vite.config.ts to force them through Vite's transform pipeline:

export default defineConfig({
  plugins: [vinext()],
  ssr: {
    noExternal: ["validator"], // or whatever package is failing
  },
});

This is the same pattern already used for nuqs and better-auth in the ecosystem test fixtures.

Changes

Documentation: Added comprehensive troubleshooting section
Test Coverage: Added tests/fixtures/ecosystem/validator/ fixture
Ecosystem Test: Added test case verifying validator works in SSR

Testing

pnpm run test tests/ecosystem.test.ts -t "validator"
# ✓ validator > can import and use validator/es/lib/isEmail.js in SSR 280ms

Note

This is a documentation/guidance issue, not a bug. The workaround exists (Vite's ssr.noExternal), but wasn't documented. This PR makes it discoverable.

southpolesteve · 2026-03-03T23:20:00Z

/bigbonk review please

ask-bonk

Review Summary

This PR adds useful functionality: auto-detecting problematic ESM packages and propagating ssr.noExternal to the RSC environment, which fixes a real issue (#189). The test coverage is thorough and the core approach (merging user config with auto-detected packages, propagating to both rsc and ssr environments) is sound.

However, there are several issues that need to be addressed:

Must Fix

package-lock.json must not be committed — this is a pnpm monorepo. An npm lockfile is incorrect.
Wrong GitHub URL in code comment — references nicepkg/vinext instead of cloudflare/vinext.
Unrelated changes bundled in — The Space_Grotesk export (issue #190) and its test should be in a separate PR. This PR claims to fix #189 only.

Should Fix

Questionable package list — cuid and nanoid don't have the described ESM issue. uuid v9+ ships proper ESM. Only validator has a verified reproduction.
RegExp items silently dropped — Vite's resolve.noExternal supports RegExp; the comment claiming otherwise is inaccurate.

Minor

Fixture uses wrong Vite version — ^6.0.0 instead of the project's ^7.3.1.
Documentation references unverified version (v0.0.16+).

ask-bonk · 2026-03-03T23:23:09Z

package-lock.json

@@ -0,0 +1,5958 @@
+{


Must remove. This is a pnpm monorepo (uses pnpm-lock.yaml). A 5,958-line npm package-lock.json should not be committed — it's the wrong package manager's lockfile and will cause confusion.

ask-bonk · 2026-03-03T23:23:09Z

packages/vinext/src/index.ts

+ * Adding them to `resolve.noExternal` forces Vite to bundle them through
+ * its transform pipeline, which resolves extensionless imports correctly.
+ *
+ * See: https://github.com/nicepkg/vinext/issues/189


Wrong repository URL. The repo is cloudflare/vinext, not nicepkg/vinext.

Suggested change

* See: https://github.com/nicepkg/vinext/issues/189

* See: https://github.com/cloudflare/vinext/issues/189

ask-bonk · 2026-03-03T23:23:09Z

packages/vinext/src/index.ts

+  "validator",     // validator/es/lib/isEmail.js can't resolve ./util/assertString
+  "uuid",          // Similar ESM resolution issues
+  "date-fns",      // date-fns/esm has complex internal structure
+  "cuid",


cuid and nanoid do not have the ESM resolution issue described in the JSDoc comment above. Both ship clean ESM with proper exports maps. Adding packages speculatively to this allowlist forces Vite to bundle them through its transform pipeline unnecessarily, which:

Increases dev server startup time

Can break packages that rely on being externalized

Erodes trust in the list (users will question every entry)

uuid v9+ also ships proper ESM with file extensions. The comment "Similar ESM resolution issues" is unverified.

Recommendation: Only include packages with verified reproduction cases. Keep validator (verified in #189) and date-fns (known complex ESM internal structure). Remove cuid, nanoid, and verify uuid before including it.

ask-bonk · 2026-03-03T23:23:09Z

packages/vinext/src/index.ts

+  } else if (Array.isArray(userSsrNoExternal)) {
+    for (const item of userSsrNoExternal) {
+      if (typeof item === "string") packages.add(item);
+      // RegExp items are skipped — can't propagate to resolve.noExternal


The comment says RegExp items "can't propagate to resolve.noExternal" — this is inaccurate. Vite's resolve.noExternal does support RegExp values (it accepts string | RegExp | (string | RegExp)[] | true). If you're choosing to skip them for implementation simplicity, the comment should reflect that, e.g. "RegExp items are not propagated — only string package names are supported".

ask-bonk · 2026-03-03T23:23:09Z

packages/vinext/src/shims/font-google.ts

 export const JetBrains_Mono = createFontLoader("JetBrains Mono");
 export const Geist = createFontLoader("Geist");
 export const Geist_Mono = createFontLoader("Geist Mono");
+export const Space_Grotesk = createFontLoader("Space Grotesk");


This change (adding Space_Grotesk export) is for issue #190, not #189. It should be in a separate PR to keep the diff focused and reviewable. The PR title and description only mention #189.

ask-bonk · 2026-03-03T23:23:09Z

tests/fixtures/ecosystem/validator/package.json

+  },
+  "devDependencies": {
+    "vinext": "workspace:*",
+    "vite": "^6.0.0"


The project uses Vite 7 ("vite": "^7.3.1" in root package.json). This fixture should match the workspace version.

Suggested change

"vite": "^6.0.0"

"vite": "^7.3.1"

ask-bonk · 2026-03-03T23:23:09Z

.agents/skills/migrate-to-vinext/references/troubleshooting.md

+```
+
+**Cause:** Some ESM packages have complex internal import structures that Node.js module resolution can't handle when externalized. By default, Vite externalizes dependencies in SSR (loads them via Node.js) instead of transforming them through Vite's pipeline.
+


Where does v0.0.16+ come from? This version number should match the actual release version where this feature will ship. If uncertain, remove the version reference to avoid documenting an inaccurate version number.

ask-bonk · 2026-03-03T23:23:09Z

tests/fixtures/ecosystem/validator/vite.config.ts

+
+export default defineConfig({
+  plugins: [vinext()],
+  // No manual ssr.noExternal needed - vinext auto-detects validator!


"auto-detects" is somewhat misleading — it's a hardcoded allowlist check, not runtime detection of ESM issues. Consider:

Suggested change

// No manual ssr.noExternal needed - vinext auto-detects validator!

// No manual ssr.noExternal needed - vinext includes validator in its known problematic ESM packages list

ask-bonk · 2026-03-03T23:23:20Z

The review was submitted successfully. Here's a summary of what I flagged:

Review Posted on PR #193

Verdict: Changes Requested

Must Fix

package-lock.json (5,958 lines) — Must be removed. This is a pnpm monorepo; an npm lockfile is incorrect.
Wrong GitHub URL — Comment at index.ts:558 references nicepkg/vinext instead of cloudflare/vinext.
Unrelated changes — The Space_Grotesk export (issue Some google fonts may have issues [vite] Internal server error: (0 , __vite_ssr_import_2__.Space_Grotesk) is not a function #190) and its test in font-google.ts/font-google.test.ts should be a separate PR.

Should Fix

Speculative package list — cuid and nanoid in KNOWN_PROBLEMATIC_ESM_PACKAGES don't have the described ESM issue. uuid v9+ ships proper ESM. Only validator has a verified reproduction from the issue.
Inaccurate comment about RegExp — The code comment claims RegExp "can't propagate to resolve.noExternal", but Vite's API does support RegExp there.

Minor

Wrong Vite version in test fixture — uses ^6.0.0 instead of the project's ^7.3.1.
Unverified version reference (v0.0.16+) in troubleshooting docs.
Misleading "auto-detects" comment in fixture config — it's a hardcoded allowlist, not runtime detection.

github run

yunus25jmi1 · 2026-03-04T01:15:18Z

@elithrar @southpolesteve kindly review the changes.

yunus25jmi1 · 2026-03-05T00:33:55Z

kindly review the changes.

pkg-pr-new · 2026-03-05T00:53:27Z

Open in StackBlitz

npm i https://pkg.pr.new/vinext@193

commit: 20a020d

cloudflare#189) Vinext now automatically detects installed packages with broken ESM resolution and adds them to resolve.noExternal for both the rsc and ssr environments. This fixes 'Cannot find module' errors when using packages like validator that have extensionless internal ESM imports. Root cause: Vite externalizes dependencies for SSR by default, but some packages use extensionless imports (e.g. ./util/assertString) that fail under Node.js strict ESM resolution. Additionally, Vite 7's Environment API means ssr.noExternal only affects the ssr environment, not the rsc environment where server components run. Changes: - Add KNOWN_PROBLEMATIC_ESM_PACKAGES list (validator, date-fns) - Add collectNoExternalPackages() to merge user config with auto-detected packages - Propagate noExternal to both rsc and ssr environments - Add validator ecosystem test fixture and integration tests - Add troubleshooting documentation Fixes cloudflare#189

yunus25jmi1 · 2026-03-05T01:08:53Z

@southpolesteve The workflow is all green.

yunus25jmi1 force-pushed the fix/issue-189-validator-esm-resolution branch from acf79f1 to 7f935ff Compare February 28, 2026 09:09

ask-bonk bot requested changes Mar 3, 2026

View reviewed changes

yunus25jmi1 force-pushed the fix/issue-189-validator-esm-resolution branch from 02b9d86 to 69cdd65 Compare March 4, 2026 00:56

yunus25jmi1 force-pushed the fix/issue-189-validator-esm-resolution branch 2 times, most recently from 1d83370 to b7b5402 Compare March 5, 2026 00:52

yunus25jmi1 force-pushed the fix/issue-189-validator-esm-resolution branch from b7b5402 to e476e70 Compare March 5, 2026 01:05

	* See: https://github.com/nicepkg/vinext/issues/189
	* See: https://github.com/cloudflare/vinext/issues/189

		```

		Cause: Some ESM packages have complex internal import structures that Node.js module resolution can't handle when externalized. By default, Vite externalizes dependencies in SSR (loads them via Node.js) instead of transforming them through Vite's pipeline.

	// No manual ssr.noExternal needed - vinext auto-detects validator!
	// No manual ssr.noExternal needed - vinext includes validator in its known problematic ESM packages list

Conversation

yunus25jmi1 commented Feb 28, 2026

Summary

Problem

Root Cause

Solution

Changes

Testing

Note

Uh oh!

southpolesteve commented Mar 3, 2026

Uh oh!

ask-bonk bot left a comment

Choose a reason for hiding this comment

Review Summary

Must Fix

Should Fix

Minor

Uh oh!

ask-bonk bot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk bot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk bot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk bot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk bot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk bot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk bot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk bot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk bot commented Mar 3, 2026

Review Posted on PR #193

Must Fix

Should Fix

Minor

Uh oh!

yunus25jmi1 commented Mar 4, 2026

Uh oh!

yunus25jmi1 commented Mar 5, 2026

Uh oh!

pkg-pr-new bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yunus25jmi1 commented Mar 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pkg-pr-new bot commented Mar 5, 2026 •

edited

Loading