Skip to content

docs: correct ESM import paths for Node.js compatibility - #2642

Open
codersjj wants to merge 1 commit into
validatorjs:masterfrom
codersjj:patch-1
Open

codersjj wants to merge 1 commit into
validatorjs:masterfrom
codersjj:patch-1

Conversation

@codersjj

Copy link
Copy Markdown

Updated the documentation to clarify that native Node.js ESM users should use the /lib path with a .js extension. The /es directory contains source code without file extensions in its internal imports, which causes ERR_MODULE_NOT_FOUND in native Node.js environments (as they don't perform automatic extension resolution).

@codecov

codecov Bot commented Dec 20, 2025 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (784e52a) to head (fb8838d).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff            @@
##            master     #2642   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          114       114           
  Lines         2572      2572           
  Branches       651       651           
=========================================
  Hits          2572      2572           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@WikiRik

WikiRik commented Dec 20, 2025

Copy link
Copy Markdown
Member

We should add tests for this as well, right? So we don't,t accidentally break this behaviour

@jorgevrgs

Copy link
Copy Markdown
Contributor

The /lib/*.js path this PR recommends is not safe for every validator under native Node ESM.

lib/isEmail.js and lib/isUUID.js only export default, so Node unwraps the function. Modules that also export locales do not collapse:

exports.default = isIBAN;
exports.locales = void 0;

A default import then binds to { default, locales }, and calling it throws TypeError: isIBAN is not a function.

Same shape in 13.15.35: isIBAN, isAlpha, isAlphanumeric, isMobilePhone, isPostalCode, isPassportNumber, isFloat.

import isIBAN from 'validator/lib/isIBAN.js';
typeof isIBAN;           // 'object'
Object.keys(isIBAN);     // ['default', 'locales']
isIBAN('DE89370400440532013000'); // TypeError
import isEmail from 'validator/lib/isEmail.js';
typeof isEmail; // 'function'

es/lib is still unloadable on Node (extensionless internals, #2387). The only import that works in both a bundler and unbundled Node ESM is the root default:

import validator from 'validator';
validator.isIBAN(value);

Please do not document /lib/*.js as the Node ESM path without calling out the locales modules, or this docs change will send people at isIBAN into the next crash.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants