awesome-phonenumber

7.8.0 verified Fri May 01 auth: no javascript

A pre-compiled version of Google's libphonenumber that provides phone number parsing, validation, and formatting with a simplified API. Currently at version 7.8.0, tracking libphonenumber 9.0.24. Releases follow upstream libphonenumber updates roughly monthly. Key differentiators: minimal footprint (bundled, no closure compiler dependency), zero runtime dependencies, ships both ESM and CJS, TypeScript types included, and unique findNumbers() feature not present in libphonenumber. Faster load and parse times compared to google-libphonenumber and libphonenumber-js. Supports Node >=18.

Common errors

error TypeError: parsePhoneNumber is not a function ↓

cause Default import used instead of named import

fix

Use import { parsePhoneNumber } from 'awesome-phonenumber'

error Error: Invalid region code ↓

cause Passed string as second argument in v7+ instead of object

fix

Use { regionCode: 'SE' } instead of 'SE'

error Type error: Property 'number' does not exist on type 'PhoneNumber' ↓

cause Attempted to access .number without checking .valid first

fix

Check pn.valid before accessing pn.number

error Cannot find module 'awesome-phonenumber' ↓

cause Package not installed or wrong import path

fix

Run npm install awesome-phonenumber and import correctly

Warnings

breaking v7.0.0 changed parsePhoneNumber second argument from string to object ↓

fix Use { regionCode: 'SE' } instead of 'SE' as second argument.

breaking v6.0.0 dropped Node 16 support ↓

fix Upgrade to Node >=18.

breaking v5.0.0 dropped Node 12 support ↓

fix Upgrade to Node >=14 (v6 requires >=18).

deprecated v4.0.0 removed constructor-based API (new PhoneNumber()) ↓

fix Use parsePhoneNumber() function instead.

gotcha parsePhoneNumber returns an object with nullable fields; always check .valid before accessing .number ↓

fix if (pn.valid) { console.log(pn.number.e164); }

gotcha Node >=18 required; no mention of browser support but library works in webpack/bundlers ↓

fix Ensure Node >=18 for server-side, or bundle with webpack/etc for browser.

Install

npm install awesome-phonenumber

yarn add awesome-phonenumber

pnpm add awesome-phonenumber

Imports

parsePhoneNumber

wrong

import parsePhoneNumber from 'awesome-phonenumber'

correct

import { parsePhoneNumber } from 'awesome-phonenumber'

Named export in both ESM and CJS; do not use default import.

getNumberFrom

wrong

const getNumberFrom = require('awesome-phonenumber').getNumberFrom

correct

import { getNumberFrom } from 'awesome-phonenumber'

ESM-style import works; require() also works but note that the entire module is pre-compiled.

findNumbers

wrong

import { findNumbers as find } from 'awesome-phonenumber'

correct

import { findNumbers } from 'awesome-phonenumber'

Available since v7.0.0; also a named export.

PhoneNumber
```
import type { PhoneNumber } from 'awesome-phonenumber'
```
TypeScript users should use type import for interface.

Quickstart

Demonstrates parsing phone numbers with region code, E164 format, and extracting numbers from text using findNumbers().

import { parsePhoneNumber, findNumbers } from 'awesome-phonenumber';

// Parse a phone number with region code
const pn = parsePhoneNumber('0707123456', { regionCode: 'SE' });
console.log(pn.valid); // true
console.log(pn.number?.e164); // +46707123456
console.log(pn.number?.international); // +46 70 712 34 56
console.log(pn.number?.national); // 070-712 34 56

// Parse an E164 number
const pn2 = parsePhoneNumber('+46707123456');
console.log(pn2.valid); // true

// Find phone numbers in text
const text = 'Call me at +1 555-123-4567 or +46 70 712 34 56';
const found = findNumbers(text);
console.log(found.length); // 2
found.forEach(f => {
  console.log(f.phoneNumber.number?.e164);
});