tinyaddress

library1.2.0jsnpmunverified

Tiny (~1.6KB), zero-dependency, universal localized address formatter for postal addresses. Version 1.2.0 uses Google's libaddressinput metadata to correctly sort and format address components for over 200 countries/regions. Features ESM and CJS support, TypeScript types included, and output as array or string. Differentiators: minimal bundle size, no dependencies compared to alternatives like localized-address-format, and coverage of all countries via Google's data. Stable and actively maintained.

productivity

npm install tinyaddress

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TINYADDRESS

tinyaddress

productivityjavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

formatAddress

✓ import { formatAddress } from 'tinyaddress';

✗ const { formatAddress } = require('tinyaddress');

Default export is not available; only named export. For CJS, use require and destructure.

Shows basic usage of formatAddress to format a US address (array output) and a UK address (string output) with the country field.

import { formatAddress } from 'tinyaddress'; const address = formatAddress({ name: 'Mr John Smith', region: 'New York', city: 'Kingston', addressLines: ['132, My Street'], postalCode: '12401', countryCode: 'US', }); console.log(address); // [ 'Mr John Smith', '132, My Street', 'Kingston, New York 12401' ] const addressStr = formatAddress({ name: 'Mrs Jane Doe', city: 'London', addressLines: ['221B Baker Street'], postalCode: 'NW1 6XE', country: 'United Kingdom', countryCode: 'GB', }, { output: 'string' }); console.log(addressStr); /* Mrs Jane Doe 221B Baker Street London NW1 6XE United Kingdom */

Debug

Known issues

gotchacountryCode is required but does not appear in the output; use 'country' field to include the country name as the last line.

fix

Add 'country' property to the address object if you want the country name displayed.

affects: >=1.0

gotchaaddressLines is optional but always appears after name/organization and before city/region/postalCode in the output, regardless of individual country format.

fix

Use addressLines for lines that should appear between recipient and locality; rely on format for country-specific ordering.

affects: >=1.0

gotchaformat option 'latin' may not produce differences for many countries: only a subset (e.g., Japan, China) have distinct latin format metadata.

fix

Check country support; for most countries, 'local' and 'latin' produce identical output.

affects: >=1.0

gotchaOutput as string uses '\n' (newline) exactly; if you need platform-specific line endings (CRLF on Windows), you must post-process.

fix

Call .replace(/\n/g, '\r\n') on the result if targeting Windows files.

affects: >=1.0

Errors

Common errors & fixes

Error: countryCode is required

Missing 'countryCode' property in the address object; it must be a valid ISO 3166-1 alpha-2 code.

fix

Add a countryCode field, e.g., countryCode: 'US'.

TypeError: address is not iterable

Passing undefined or null as address argument to formatAddress.

fix

Ensure the first argument is an object with required properties.

Unsupported country code: XX

Country code not present in Google's metadata (e.g., unknown or invalid code).

fix

Use a valid ISO 3166-1 alpha-2 country code.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

43 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alizeait/tinyaddress ↗

packagetinyaddress ↗

homepagehttps://github.com/alizeait/tinyaddress#readme ↗