libphonenumber-bundler CLI

Common errors

• lpn-bundler: command not found

  cause The `libphonenumber-bundler` package was installed locally or not added to the system's PATH.
  fix Install the package globally using `npm install -g libphonenumber-bundler` or ensure your shell's PATH includes `$(npm bin)`.

• Error: Version not found: -t X.Y.Z

  cause The specified `libphonenumber` version tag (e.g., 'X.Y.Z') does not exist or cannot be fetched from the upstream Google repository.
  fix Run `lpn-bundler list` to see all available versions and use one from the displayed list. Ensure you have network connectivity to GitHub.

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

  cause The `libphonenumber` object or `PhoneNumberUtil` class was not properly loaded or is not available in the current scope when attempting to call `getInstance()` (e.g., script not included, wrong variable name, or using a module system incorrectly with a global-style bundle).
  fix In a browser, ensure the generated `libphonenumber.js` script is loaded *before* your code attempts to use `libphonenumber.PhoneNumberUtil`. In Node.js, ensure you are correctly requiring the file and accessing the `PhoneNumberUtil` export (e.g., `const { PhoneNumberUtil } = require('./libphonenumber.js');`).

Warnings

• maintenance The `libphonenumber-bundler` package itself (version 0.4.0) has not been updated in over two years, indicating it is no longer actively maintained. While it can fetch recent versions of the upstream `libphonenumber` source, the bundler tool itself may contain unaddressed bugs or security vulnerabilities.
  Fix: Consider alternatives like `libphonenumber-js` (a modern rewrite) or `google-libphonenumber` (another pre-compiled bundle) if active maintenance and a smaller footprint are critical. If using this bundler, ensure you regularly re-bundle with the latest `libphonenumber` upstream version.
• gotcha The generated bundle is from Google's Closure-compiled `libphonenumber` JavaScript port. This port can be significantly larger than optimized rewrites (e.g., `libphonenumber-js`) and is tightly coupled to Google Closure's API patterns, which may differ from standard JavaScript module exports.
  Fix: Be aware of the file size implications, especially in browser environments. For smaller bundles or more idiomatic JavaScript APIs, evaluate `libphonenumber-js` as an alternative. Understand that the API exposed by the bundled file will follow Google's Closure patterns (e.g., `libphonenumber.PhoneNumberUtil.getInstance()`) rather than direct class instantiations.
• gotcha Phone number metadata is frequently updated by Google's `libphonenumber` project. To ensure accurate parsing and validation, users must periodically re-run the `lpn-bundler bundle` command to incorporate the latest upstream metadata, as the CLI tool does not automatically update generated files.
  Fix: Integrate the `lpn-bundler bundle` command into a regular build or deployment pipeline to ensure the bundled `libphonenumber.js` file uses the most current metadata available from the upstream project.
• gotcha The `libphonenumber-bundler` CLI generates a standalone JavaScript file without offering explicit options for modern module formats (ESM, UMD, CJS wrappers). The output typically assumes a global scope for browser use or a basic CommonJS export for Node.js.
  Fix: For projects using bundlers like Webpack or Rollup, you might need to manually wrap the generated file or configure your bundler to handle global-exposed libraries correctly. If strict ESM imports are required, consider a library like `libphonenumber-js` which provides native ESM support.

Install

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

Imports

• libphonenumber.PhoneNumberUtil
  wrong:

  import { PhoneNumberUtil } from 'libphonenumber-bundler'

  correct:

  // After including the bundled script (e.g., in browser):
  const phoneUtil = libphonenumber.PhoneNumberUtil.getInstance();

  This package is a CLI. These imports refer to using the *output* file generated by the bundler. The bundled file typically exposes a global `libphonenumber` object in browsers, or a CommonJS module in Node.js environments.
• libphonenumber.PhoneNumberFormat
  wrong:

  import { PhoneNumberFormat } from 'libphonenumber-bundler'

  correct:

  // After including the bundled script (e.g., in browser):
  const PNF = libphonenumber.PhoneNumberFormat;

  The generated bundle from Google's `libphonenumber` typically exposes `PhoneNumberFormat` as a property of the global `libphonenumber` object, or as an export via CommonJS.
• require('path/to/libphonenumber.js').PhoneNumberUtil
  wrong:

  import { PhoneNumberUtil } from 'libphonenumber-bundler'

  correct:

  // In Node.js, assuming the bundled file is 'libphonenumber.js' in the current directory:
  const { PhoneNumberUtil } = require('./libphonenumber');
  const phoneUtil = PhoneNumberUtil.getInstance();

  For Node.js, the generated bundle often provides CommonJS exports. The path to the generated file is crucial.

Quickstart

Demonstrates global installation, listing available `libphonenumber` versions, bundling a specific version, and basic browser usage of the generated file.

npm install -g libphonenumber-bundler

# List available libphonenumber versions to bundle
lpn-bundler list

# Bundle a specific version of libphonenumber (e.g., 8.12.57) to a file
lpn-bundler bundle -t 8.12.57 -o libphonenumber.js

# Example usage of the generated file (libphonenumber.js) in a browser:
// <script src="libphonenumber.js"></script>
// <script>
//   const phoneUtil = libphonenumber.PhoneNumberUtil.getInstance();
//   const number = phoneUtil.parse('+12024561414', 'US');
//   console.log(phoneUtil.isValidNumber(number));
//   console.log(phoneUtil.format(number, libphonenumber.PhoneNumberFormat.INTERNATIONAL));
// </script>