@id-region-data/data

High-performance, ultra-lightweight Indonesian region data (Provinces, Regencies, Districts, Villages) optimized for modern web applications.

Why this package?

Most Indonesian region packages are monolithic, forcing users to download a 24MB+ JSON file just to pick a single village. This causes massive frontend bundle bloat and slow page loads.

@id-region-data/data solves this by using Dynamic Chunking:

• 0MB Initial Load: The core library is almost weightless.
• Lazy Loading: Data is fetched on-demand using dynamic imports.
• Tree-Shaking: Only the functions you use are included in your bundle.
• Modern: Fully supports ESM, CommonJS, and TypeScript.
• Up-to-Date: Based on the latest Kepmendagri 2025 data (38 Provinces, 83,345 Villages).

Installation

npm install @id-region-data/data

Usage

All functions are asynchronous and return a Promise. Data is only downloaded when a function is called for a specific parent code.

1. Get All Provinces

import { getProvinces } from '@id-region-data/data';

const provinces = await getProvinces();
// [ { code: '11', name: 'ACEH' }, ... ]

2. Get Regencies by Province

import { getRegenciesByProvince } from '@id-region-data/data';

const regencies = await getRegenciesByProvince('32'); // 32 = Jawa Barat

3. Get Districts by Regency

import { getDistrictsByRegency } from '@id-region-data/data';

const districts = await getDistrictsByRegency('3273'); // 3273 = Kota Bandung

4. Get Villages by District

import { getVillagesByDistrict } from '@id-region-data/data';

const villages = await getVillagesByDistrict('3273100'); // Arcamanik

Data Interfaces

Strict TypeScript interfaces are exported for your convenience:

import type { Province, Regency, District, Village } from '@id-region-data/data';

Performance Deep Dive

This library splits the Indonesian hierarchy into 23,531 small JSON chunks.

| Level | Fetch Trigger | Result | | :--- | :--- | :--- | | Province | getProvinces() | Loads provinces.json (~4KB) | | Regency | getRegenciesByProvince('11') | Loads regencies/11.json (~2KB) | | District | getDistrictsByRegency('1101') | Loads districts/1101.json (~2KB) | | Village | getVillagesByDistrict('110101') | Loads villages/110101.json (~1KB) |

Instead of downloading 24MB, your user's browser only downloads roughly 10KB of data to complete a full "Province → Village" selection flow.

Source Data

Data is parsed and verified from the authoritative cahyadsn/wilayah repository, ensuring compliance with the latest Kepmendagri 2025 regional codes (38 Provinces, 83,345 Villages).

License

MIT © id-region-data