I'm a full-stack engineer working in Tokyo. One day, I needed to build a feature at work that handles Japanese postal codes.

"Enter a postal code, and the address fills in automatically. Easy, right?" I thought.

It was not easy.

This is the story of how I couldn't find a good library — so I built and published my own npm package, nihonpost.

📦 npm: https://www.npmjs.com/package/nihonpost

The Problem: Nothing That Made Me Say "This Is It"

I searched npm for a library. What I found was...

• Packages that hadn't been maintained in years
• Packages with no TypeScript support
• Packages with almost no documentation I searched for hours, and not a single one made me think, "this is it!" And a library that worked well with Vue 3? It didn't exist anywhere.

I sat with my coffee and thought for a while. Then I decided.

"If it doesn't exist, build it."

What I Built: nihonpost

I developed it bit by bit, on nights and weekends. I focused on three things:

1. TypeScript-first — type definitions included out of the box
2. Vue 3 composable support — usable directly in the familiar use... style
3. No external API dependency — you host the data yourself; it's split into prefix-based JSON chunks, fetched on demand, and cached ### Installation

npm install nihonpost

Setup: Configuring the Loader

nihonpost is designed so that you host the postal code data yourself. No third-party API means no rate limits and no risk of a service shutting down under you.

You configure the loader once at startup:

import { configureLoader, fetchLoader } from 'nihonpost'

configureLoader(fetchLoader('/nihonpost-data'))
// lookups now GET /nihonpost-data/150.json etc., cached after first hit

The data is split into JSON files by the first three digits of the postal code, and only the chunks you need are fetched. Once fetched, they're cached — so repeat lookups in the same area are instant.

Basic Usage

import { lookup } from 'nihonpost'

const address = await lookup('150-0002')
// => { prefecture: '東京都', city: '渋谷区', town: '渋谷' }

Using It with Vue 3

With the composable, it works out of the box in Vue projects:

<script setup lang="ts">
import { usePostalCode } from 'nihonpost/vue'

const { address, loading, search } = usePostalCode()
</script>

<template>
  <input @input="search($event.target.value)" placeholder="Postal code" />
  <p v-if="loading">Searching...</p>
  <p v-else-if="address">{{ address.prefecture }}{{ address.city }}{{ address.town }}</p>
</template>

That's all it takes to implement the classic "postal code → auto-filled address" form field.

What I Learned Along the Way

Even for a small package, taking it all the way to a public release taught me a lot:

• The habit of writing tests — once you publish, "it should work" isn't good enough
• npm package design — supporting both ESM and CJS, and how to write the exports field properly
• The value of documentation — I was the one who suffered from "I can't find anything," so I made sure the README was thorough ## Closing Thoughts

It might be a small package. But that "I can't find one" frustration from that day — there's now one less of it in the world.

The next time someone runs into the same problem, they won't have to search for hours.

Because nihonpost will be there.

📦 npm: https://www.npmjs.com/package/nihonpost

If you try it and something feels off, issues and PRs are very welcome. And if you leave a star, it becomes fuel for next weekend's development 🔥