libphonenumber-js

Common errors

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

  cause `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.

  cause 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

  cause 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.

Warnings

• gotcha libphonenumber-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.
• gotcha The `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 */ }`.
• gotcha When 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()`.

Install

• npm install libphonenumber-js npm
• yarn add libphonenumber-js yarn
• pnpm add libphonenumber-js pnpm

Imports

• parsePhoneNumber
  wrong:

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

  correct:

  import { parsePhoneNumber } from '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
  wrong:

  import formatPhoneNumber from 'libphonenumber-js/formatPhoneNumber';

  correct:

  import { formatPhoneNumber } from 'libphonenumber-js';

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

  import { validatePhoneNumber } from 'libphonenumber-js';

  correct:

  import { isValidPhoneNumber } from 'libphonenumber-js';

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

  import { getCallingCode } from 'libphonenumber-js';

  correct:

  import { getCountryCallingCode } from 'libphonenumber-js';

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

Quickstart

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}`);