Registry / communication / node-phonenumber

node-phonenumber

library1.0.0jsnpmunverified

node-phonenumber is a JavaScript port of Google's `libphonenumber` library, designed to parse, format, and validate international phone numbers within Node.js environments. The package is currently at version 1.0.0, with its last update occurring approximately 8 years ago (as of 2024). Due to its age, it is considered abandoned and no longer actively maintained. This means it likely contains outdated phone number metadata, which is critical for accurate validation and formatting of global telephone numbers, as these can change frequently. Modern alternatives like `libphonenumber-js` or `awesome-phonenumber` are actively maintained, include up-to-date data, offer ES module support, and provide TypeScript definitions, making them significantly better choices for new projects. This package primarily relies on CommonJS for module imports and does not offer native TypeScript support.

communication serialization

npm install node-phonenumber

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-PHONENUMBER

node-phonenumber

communicationjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

phone

✓ const phone = require('node-phonenumber');

✗ import phone from 'node-phonenumber';

This package is CommonJS-only. Attempting to use ES module syntax (import) will result in runtime errors.

PhoneNumberUtil

✓ const phoneUtil = phone.PhoneNumberUtil.getInstance();

✗ const phoneUtil = require('node-phonenumber').PhoneNumberUtil;

The PhoneNumberUtil class is accessed via the default export and requires calling `getInstance()` to get a functional utility object.

PhoneNumberFormat

✓ const PNF = phone.PhoneNumberFormat;

✗ const PNF = require('node-phonenumber').PhoneNumberFormat.INTERNATIONAL;

PhoneNumberFormat is an enum object. Access specific formats (e.g., INTERNATIONAL) as properties of this object.

Demonstrates parsing a phone number with a region code, formatting it to international standard, checking its validity, and extracting the country code.

const phone = require('node-phonenumber'); const phoneUtil = phone.PhoneNumberUtil.getInstance(); // Parse a phone number with country code 'MY' (Malaysia) const phoneNumber = phoneUtil.parse('0139348815', 'MY'); // Format the phone number to INTERNATIONAL format const toNumber = phoneUtil.format(phoneNumber, phone.PhoneNumberFormat.INTERNATIONAL); console.log(toNumber); // Expected output: +60 13-934 8815 // Example: check if the number is valid for the region const isValid = phoneUtil.isValidNumberForRegion(phoneNumber, 'MY'); console.log(`Is valid for MY: ${isValid}`); // Example: get country code console.log(`Country code: ${phoneNumber.getCountryCode()}`);

Debug

Known issues

breakingThis package is abandoned and has not been updated since 2016. It contains outdated `libphonenumber` data, which means it cannot accurately validate or format phone numbers, especially for newer regions or changes in existing numbering plans. Using it in production is highly discouraged.

fix

Migrate to actively maintained alternatives like `libphonenumber-js` (recommended) or `google-libphonenumber` which provide up-to-date metadata and ongoing support.

affects: >=1.0.0

gotchaThe package is CommonJS-only and does not support ES module `import` syntax. Attempting to use `import` will lead to runtime errors, particularly in modern Node.js environments configured for ESM.

fix

Ensure all imports for `node-phonenumber` use the `require()` syntax: `const phone = require('node-phonenumber');`. Consider transpilation for mixed CJS/ESM projects or migrating to an ESM-compatible library.

affects: >=1.0.0

gotchaThere are no official TypeScript type definitions (`.d.ts` files) shipped with this package, nor are they available on DefinitelyTyped. This will lead to poor developer experience and potential type-related issues in TypeScript projects.

fix

Either use `any` types for imports or consider migrating to a library like `libphonenumber-js` which includes first-party TypeScript definitions.

affects: >=1.0.0

gotchaThe `PhoneNumberUtil` object requires `getInstance()` to be called. Directly accessing methods on `phone.PhoneNumberUtil` without `getInstance()` will result in `TypeError: Cannot read properties of undefined` or similar, as the utility methods are on the instance, not the static class.

fix

Always initialize `PhoneNumberUtil` using `const phoneUtil = phone.PhoneNumberUtil.getInstance();` before attempting to use its methods.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , node_phonenumber_1.PhoneNumberUtil) is not a function

Attempting to use ES module `import` syntax or destructuring when the package is CommonJS-only.

fix

Change `import { PhoneNumberUtil } from 'node-phonenumber';` to `const phone = require('node-phonenumber'); const phoneUtil = phone.PhoneNumberUtil.getInstance();`

TypeError: phoneUtil.parse is not a function

Attempting to call methods on the `PhoneNumberUtil` class directly instead of its instance.

fix

Ensure `phoneUtil` is initialized via `const phoneUtil = phone.PhoneNumberUtil.getInstance();` before calling methods like `parse`.

Error: Invalid phone number for country code 'XX'

The phone number data used by this library is severely outdated (last updated in 2016), leading to incorrect validation or formatting for new number ranges or country codes.

fix

Update to an actively maintained `libphonenumber` port like `libphonenumber-js` or `google-libphonenumber` to ensure up-to-date phone number metadata.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wajatimur/node-phonenumber ↗

packagehttps://www.npmjs.com/package/node-phonenumber ↗

homepagehttp://code.google.com/p/libphonenumber/ ↗