Registry / serialization / libphonenumber-js

libphonenumber-js

library1.12.41jsnpmunverified

libphonenumber-js is a JavaScript and TypeScript library designed for parsing, formatting, and validating international phone numbers. It serves as a significantly smaller and simpler rewrite of Google's original `libphonenumber` library. Currently at version 1.12.41, this package prioritizes a reduced bundle size (approximately 145 kB vs. 550 kB for the Google port) by focusing solely on personal phone numbers. It deliberately omits support for less common categories such as emergency numbers, short codes, numbers prefixed with `*`, Australian `13`-smart numbers, and alphabetic phone numbers like `1-800-GOT-MILK`. The library ships with comprehensive TypeScript definitions and uniquely offers functionality to search for phone numbers within text, a feature absent in Google's official JavaScript port. While a specific release cadence isn't detailed, the version history suggests active and ongoing development.

serialization communication

npm install libphonenumber-js

package ↗homepage ↗

INSTALL

IMPORT

SIG · LIBPHONENUMBER-JS

libphonenumber-js

serializationjavascriptv1.12.41

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.

parsePhoneNumber

✓ import { parsePhoneNumber } from 'libphonenumber-js';

✗ const parsePhoneNumber = require('libphonenumber-js');

For parsing a phone number string into a PhoneNumber object. ESM is the primary import style. For CommonJS, use `require('libphonenumber-js').parsePhoneNumber`.

formatPhoneNumber

✓ import { formatPhoneNumber } from 'libphonenumber-js';

✗ import formatPhoneNumber from 'libphonenumber-js/formatPhoneNumber';

Use named import for `formatPhoneNumber`. There's also `formatPhoneNumberIntl` for international formatting with a leading `+`.

isValidPhoneNumber

✓ import { isValidPhoneNumber } from 'libphonenumber-js';

✗ import { validatePhoneNumber } from 'libphonenumber-js';

Checks if a phone number string is valid for a given country. This is a common utility function.

getCountryCallingCode

✓ import { getCountryCallingCode } from 'libphonenumber-js';

✗ import { getCallingCode } from 'libphonenumber-js';

Retrieves the international calling code for a specified country code (e.g., 'US' -> '1').

Demonstrates parsing, formatting, and validating phone numbers, including checking country-specific validity and retrieving calling codes.

import { parsePhoneNumber, formatPhoneNumber, isValidPhoneNumber, getCountryCallingCode } from 'libphonenumber-js'; const phoneNumberString = '+12133734253'; const countryCode = 'US'; // Parse a phone number const phoneNumber = parsePhoneNumber(phoneNumberString); if (phoneNumber) { console.log(`Original number: ${phoneNumberString}`); console.log(`Country: ${phoneNumber.country}`); console.log(`National number: ${phoneNumber.nationalNumber}`); // Format the number in various ways console.log(`Formatted E.164: ${phoneNumber.format('E.164')}`); console.log(`Formatted International: ${phoneNumber.format('INTERNATIONAL')}`); console.log(`Formatted National: ${phoneNumber.format('NATIONAL')}`); // Check validity const valid = isValidPhoneNumber(phoneNumberString, countryCode); console.log(`Is valid for ${countryCode}? ${valid}`); // Get country calling code const callingCode = getCountryCallingCode(countryCode); console.log(`Calling code for ${countryCode}: +${callingCode}`); } else { console.log(`Could not parse phone number: ${phoneNumberString}`); } // Example of an invalid number const invalidNumber = '555-123-INVALID'; const isValid = isValidPhoneNumber(invalidNumber, countryCode); console.log(`Is '${invalidNumber}' valid for ${countryCode}? ${isValid}`);

Debug

Known issues

gotchalibphonenumber-js deliberately omits support for several 'special' phone number categories, including emergency numbers (e.g., 911), short codes, numbers starting with `*`, Australian `13`-smart numbers, and alphabetic numbers (e.g., 1-800-GOT-MILK). It focuses exclusively on personal phone numbers to achieve a smaller bundle size. If your application requires handling these specific types, this library might not be suitable, and you may need Google's full `libphonenumber` port.

fix

Review your requirements; if special number types are critical, consider using the official (larger) Google `libphonenumber` JavaScript port or a different library that specifically supports them.

affects: >=1.0.0

gotchaThe `parsePhoneNumber` function returns `undefined` if the input string cannot be parsed into a valid `PhoneNumber` object. Always check the return value before attempting to access properties like `country`, `nationalNumber`, or `format()`, otherwise, it may lead to runtime errors.

fix

Wrap calls to `parsePhoneNumber` in a conditional check: `const phoneNumber = parsePhoneNumber(number); if (phoneNumber) { /* use phoneNumber */ }`.

affects: >=1.0.0

gotchaWhen formatting numbers, ensure you provide a valid format string (e.g., 'E.164', 'INTERNATIONAL', 'NATIONAL'). Using an unsupported format string will result in an error or unexpected output. Refer to the documentation for supported formats.

fix

Consult the `libphonenumber-js` documentation or TypeScript types for the exact accepted format strings for `phoneNumber.format()`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'country')

`parsePhoneNumber` returned `undefined` because the input string was not a valid or recognizable phone number.

fix

Always check if the result of `parsePhoneNumber(string)` is not `undefined` before attempting to access its properties. For example: `const num = parsePhoneNumber(str); if (num) { console.log(num.country); }`.

TS2307: Cannot find module 'libphonenumber-js' or its corresponding type declarations.

TypeScript compiler cannot locate the package or its declaration files (`.d.ts`).

fix

Ensure `libphonenumber-js` is installed (`npm install libphonenumber-js`) and that your `tsconfig.json` includes `node_modules/@types` or has `"moduleResolution": "node"` set correctly.

ReferenceError: require is not defined

Attempting to use `require()` in an ES Module context (e.g., a modern Node.js project or browser module) without proper transpilation or configuration.

fix

Use ESM `import` statements instead: `import { parsePhoneNumber } from 'libphonenumber-js';`. If using CommonJS, ensure your file is a `.js` file or configured as such, and `require()` is appropriate for your environment.

Upgrade

Version history

1.12.41latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/libphonenumber-js ↗

homepagehttps://gitlab.com/catamphetamine/libphonenumber-js#readme ↗