{"id":15679,"library":"libphonenumber-bundler","title":"libphonenumber-bundler CLI","description":"This package provides a Command Line Interface (CLI) utility designed to compile and bundle Google's official `libphonenumber` JavaScript port into a single, standalone JavaScript file. Unlike modern alternatives like `libphonenumber-js` which are independent rewrites, this tool directly uses the original Closure-compiled JavaScript output from Google's project, aiming for a faithful reproduction of its full functionality, including its potentially larger footprint and reliance on Closure's API patterns. The current stable version, 0.4.0, has not seen updates in over two years, indicating a maintenance status for the bundler tool itself, although it can fetch recent versions of the upstream `libphonenumber` source code. Its key differentiator is simplifying the process of obtaining a self-contained, official `libphonenumber` bundle without requiring a complex build setup, making it suitable for projects that prefer a direct script inclusion or a CommonJS module of the original Google library rather than a streamlined rewrite.","status":"maintenance","version":"0.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/dagjaneiro/libphonenumber-bundler","tags":["javascript","libphonenumber","google","bundler","compiler"],"install":[{"cmd":"npm install libphonenumber-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add libphonenumber-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add libphonenumber-bundler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { PhoneNumberUtil } from 'libphonenumber-bundler'","symbol":"libphonenumber.PhoneNumberUtil","correct":"// After including the bundled script (e.g., in browser):\nconst phoneUtil = libphonenumber.PhoneNumberUtil.getInstance();"},{"note":"The generated bundle from Google's `libphonenumber` typically exposes `PhoneNumberFormat` as a property of the global `libphonenumber` object, or as an export via CommonJS.","wrong":"import { PhoneNumberFormat } from 'libphonenumber-bundler'","symbol":"libphonenumber.PhoneNumberFormat","correct":"// After including the bundled script (e.g., in browser):\nconst PNF = libphonenumber.PhoneNumberFormat;"},{"note":"For Node.js, the generated bundle often provides CommonJS exports. The path to the generated file is crucial.","wrong":"import { PhoneNumberUtil } from 'libphonenumber-bundler'","symbol":"require('path/to/libphonenumber.js').PhoneNumberUtil","correct":"// In Node.js, assuming the bundled file is 'libphonenumber.js' in the current directory:\nconst { PhoneNumberUtil } = require('./libphonenumber');\nconst phoneUtil = PhoneNumberUtil.getInstance();"}],"quickstart":{"code":"npm install -g libphonenumber-bundler\n\n# List available libphonenumber versions to bundle\nlpn-bundler list\n\n# Bundle a specific version of libphonenumber (e.g., 8.12.57) to a file\nlpn-bundler bundle -t 8.12.57 -o libphonenumber.js\n\n# Example usage of the generated file (libphonenumber.js) in a browser:\n// <script src=\"libphonenumber.js\"></script>\n// <script>\n//   const phoneUtil = libphonenumber.PhoneNumberUtil.getInstance();\n//   const number = phoneUtil.parse('+12024561414', 'US');\n//   console.log(phoneUtil.isValidNumber(number));\n//   console.log(phoneUtil.format(number, libphonenumber.PhoneNumberFormat.INTERNATIONAL));\n// </script>","lang":"javascript","description":"Demonstrates global installation, listing available `libphonenumber` versions, bundling a specific version, and basic browser usage of the generated file."},"warnings":[{"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.","message":"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.","severity":"maintenance","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install the package globally using `npm install -g libphonenumber-bundler` or ensure your shell's PATH includes `$(npm bin)`.","cause":"The `libphonenumber-bundler` package was installed locally or not added to the system's PATH.","error":"lpn-bundler: command not found"},{"fix":"Run `lpn-bundler list` to see all available versions and use one from the displayed list. Ensure you have network connectivity to GitHub.","cause":"The specified `libphonenumber` version tag (e.g., 'X.Y.Z') does not exist or cannot be fetched from the upstream Google repository.","error":"Error: Version not found: -t X.Y.Z"},{"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');`).","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).","error":"TypeError: Cannot read properties of undefined (reading 'getInstance')"}],"ecosystem":"npm"}