📮
今どきのフロントエンドのための、郵便番号→住所変換 #jposta

2024/11/01に公開
JavaScript
TypeScript
frontend
tech
 概要入力された郵便番号から住所を自動入力するためのライブラリは無数に存在しますが、今どきのフロントエンドアーキテクチャと親和性の高いライブラリは多くありません。また、メジャーなライブラリの中にも郵便番号と住所の紐づけデータをAPIで外部から取得しているものがあり、エンタープライズで利用しにくいという状況があります。
そこで、jpostaの紹介です。

⚡ ES6 / Promiseベース / TypeScript対応

⚡ 依存ライブラリなし

⚡ Self-hosted & ダイナミックインポート (暗黙的なAPIコールなし)
https://www.npmjs.com/package/jposta

https://github.com/nickichi/jposta

 インストール$ npm i jposta
$ yarn add jposta
$ pnpm i jposta

 使い方簡単です。
import { getAddress } from 'jposta';

// 文字列で渡す
const address = await getAddress('1000001');
console.log(address);
// { pref: "東京都", prefNum: 13, city: "千代田区", area: "千代田" }

// ハイフンありも可
const address2 = await getAddress('100-0003');
console.log(address2);
// { pref: "東京都", prefNum: 13, city: "千代田区", area: "皇居外苑" }

 仕組みダイナミックインポートで必要最小限のリソースを必要なタイミングで取得します。
const result1 = await getAddress('1000001');
// z10.jsのようなファイルをホスト先から取得
const result2 = await getAddress('2100002');
// z21.jsのようなファイルをホスト先から取得
const result3 = await getAddress('1000003');
// z10.jsはすでに取得済みなので余分な通信は必要なし
以下のように、検索アクションでデータファイルが取得されます。

データファイルはメインファイルにはバンドルされません。

例えば、viteでのビルドは下記のようになります。
$ npm run build

> vite-react-jposta@0.0.0 build
> tsc && vite build

vite v5.2.13 building for production...
✓ 136 modules transformed.
dist/index.html                         0.46 kB │ gzip:  0.30 kB
dist/assets/react-CHdo91hT.svg          4.13 kB │ gzip:  2.05 kB
dist/assets/index-DiwrgTda.css          1.39 kB │ gzip:  0.72 kB
dist/assets/z11-nic1O4vt-B_L_y_VH.js    2.29 kB │ gzip:  0.95 kB
dist/assets/z96-Br2qdTMP-DG7Gpu3V.js   80.14 kB │ gzip: 27.45 kB
...(many files)
dist/assets/z50-BWUSdQBW-BJcxw7Xg.js   87.66 kB │ gzip: 29.14 kB
dist/assets/z60-34YubQWJ-DwuyaedM.js  101.50 kB │ gzip: 29.97 kB
dist/assets/index-D0vWSNxA.js         152.48 kB │ gzip: 49.62 kB
✓ built in 2.16s
ご覧の通りですが、データファイルは各プロジェクトでホストしなければなりません。
参考1：Vite+React+jpostaサンプル

参考2：Next.js+jpostaサンプル
ダイナミックインポートで利用するのが最も簡単ですが、

場合によってはサーバサイドでデータ参照し、自前のAPIを構築するほうが望ましい場合もあります。
こちらのNode.js+Express+jpostaサンプルのように、サーバサイドで利用してAPI化することもできます。

 データの出どころ？データソースは日本郵便株式会社が提供しているCSVデータです。

ファイルの変更を監視＆自動反映します。

 まとめVite+React+TypeScriptなど、今どきのフロントエンドアーキテクチャとマッチする郵便番号ライブラリをお探しの方は、jpostaをぜひどうぞ。
概要

インストール

使い方

仕組み

データの出どころ？

まとめ

Discussion
