jpzip の
設計ノート
Cloudflare Pages の使いこなし、MCP server の作り方、Claude Code を使った 8 言語 SDK 展開まで — jpzip プロジェクトの設計判断と数字を書き残します。
-
ken_all / jpostcode gem から jpzip-ruby へ移行する
KEN_ALL.csv をローカル展開する Ruby gem(ken_all=DB へ import、jpostcode=git submodule 同梱)から、CDN フェッチの jpzip-ruby へ移す手順。フィールド対応表、月次更新運用の撤去、移行できない 1 点まで解説します。
-
Cloudflare Workers で jpzip-js を動かす — キャッシュ層をどう選ぶか
jpzip-js を Cloudflare Workers の Edge で動かし、郵便番号 → 住所のルックアップを配信する設計。Cache API・Workers KV・Durable Objects のどれをキャッシュ層に選ぶべきかを、コストと実測 p50/p99 で判断します。
-
zipcoda から jpzip-js へ移行する: 外部 API 依存を切る
zipcoda.net の郵便番号 API を実行時に叩く構成から、jpzip-js の静的 CDN 配信へ移行する手順。レスポンスのフィールドマッピング、JSONP/CSP の整理、レート制限対策の撤去、実測レイテンシまでを Before/After のコードで具体的に解説します。
-
Next.js App Router の Server Actions で住所自動入力フォームを作る
Next.js 16 App Router の Server Actions で、郵便番号から都道府県・市区町村を引いて自動入力するフォームの作り方。JS 無効でも動く Progressive Enhancement、Edge Runtime での実行、use cache ディレクティブとの組み合わせまで解説します。
-
Rails + Hotwire + jpzip-ruby で住所自動入力フォームを作る
Turbo Frame と Stimulus の 2 パターンで、郵便番号から都道府県・市区町村を自動入力する Rails フォームを作る手順。jpzip-ruby の L1/L2 キャッシュで Puma プロセスをまたいだ CDN への重複フェッチを潰す構成まで含めて解説します。
-
React Hook Form + Zod + jpzip で住所自動入力フォームを作る
React Hook Form と Zod で郵便番号バリデーションを組み、jpzip-js の lookup と setValue で都道府県・市区町村・町域を埋める手順。二重 lookup の抑制と aria-busy によるアクセシビリティ対応も含む。
-
Yubinbango から jpzip-js へ移行する: JSONP 脱却と型安全化
jQuery を使わない古典的な Yubinbango から jpzip-js への移行ガイド。JSONP・CSP 制約・TypeScript 型欠如を解消し、microformats h-adr のフォームを薄い互換層で再利用する具体的な手順。
-
Claude Code 1 人開発で 6 時間で 8 言語 SDK を実装した話
jpzip の Go / TypeScript / Python / Rust / Ruby / Dart / PHP / Swift SDK を Claude Code と 6 時間で実装した話。プロトコル先行設計、翻訳タスクとしての多言語移植、言語固有の落とし穴。
-
MCP サーバーを書いて Claude が日本の郵便番号を扱えるようにした
stateless な MCP サーバーで Claude が日本の郵便番号を引けるようにした話。Tool 設計、キャッシュ寿命の分離、漢字/カナ/ローマ字の 3 言語横断検索。
-
KEN_ALL.csv を Cloudflare Pages から 120,677 件配信する設計
日本郵便 KEN_ALL.csv を Cloudflare Pages 上の静的 JSON ファイル群として配信する設計の話。ファイル分割戦略、ETL、Worker/R2/KV を使わない理由まで。
-
Cloudflare Pages の無料枠だけで郵便番号データセット配信サービスを作った話
jpzip という個人プロジェクトの全体像と、なぜそれが「課金軸ゼロ」で成立しているのかを書きます。Cloudflare Pages の無料枠だけで 120,677 件の郵便番号データを配信する設計。