Laravel Nusa Laravel Package

Product Decisions This Supports

• Market-entry sequencing for Indonesia. If Indonesia is on the roadmap, this package settles a deceptively expensive prerequisite: a canonical four-level administrative hierarchy (province → regency → district → village) with postal codes and coordinates. That data alone typically burns 2–6 engineering weeks of sourcing, cleaning, and reconciling against BPS/upstream sources — time that does not differentiate the product.
• Build-vs-buy on address infrastructure. The decision is rarely "use this package" vs. "build it"; it is "use this package" vs. "buy a commercial address/geocoding API" vs. "assemble a custom dataset." This package is the cheap, self-hosted, no-vendor-lock-in option. It anchors the low end of the cost curve and gives you a baseline to price commercial alternatives against.
• Feature scope for anything address-shaped. Checkout and shipping address forms with cascading region selectors, serviceability/coverage checks, territory assignment for sales and ops, KYC and customer-onboarding forms, logistics zone and rate-card mapping, franchise or distribution-network planning, and dashboards broken down by region. All of these become days of work rather than quarters, because the reference data and Eloquent relationships already exist.
• Data-residency and offline posture. Because the dataset ships as a pre-compiled SQLite file and static CSV/JSON/GeoJSON exports, it supports decisions where a live third-party API call is unacceptable — on-prem deployments, air-gapped environments, high-latency or cost-sensitive read paths, and batch jobs that would otherwise incur per-lookup fees.
• Roadmap: multi-country abstraction. Adopting this locks in an Indonesia-shaped data model. If SEA expansion is plausible, the decision it should trigger now is to wrap region lookups behind an internal interface rather than binding product code to Creasi\Nusa\Models\Province. Cheap today, very expensive to retrofit.
• Build-vs-buy on the read layer too. The package ships API routes, migrations for address tables, config, and translations. That is a meaningful chunk of "address service" you do not have to specify, build, or maintain — but it is also opinionated (string primary keys, no timestamps on admin models), so confirm it does not conflict with your existing address schema before committing.

When to Consider This Package

Adopt when:

• Indonesia is a live or near-term market and you need region hierarchies, postal codes, or coordinates in a Laravel application.
• Your stack is already Laravel 9–13 on PHP 8.2+. The integration cost is close to zero — composer require, publish config, done.
• Read-heavy, low-write access pattern. It is a pre-compiled SQLite database consumed through Eloquent; it is excellent for lookups and reference joins, and it is not a transactional store. Use it as a reference dataset alongside your primary database, not as the system of record for customer addresses.
• You want a fast, credible prototype or internal tool, or you need to seed realistic dev/test fixtures for an Indonesian product.
• You are comfortable pinning a version and owning the upgrade path yourself.

Look elsewhere — or budget for mitigation — when:

• Data provenance is a compliance requirement. The dataset is imported from upstream community sources (cahyadsn's wilayah and postal-code datasets). The MIT license covers the package code; it does not automatically settle the licensing, accuracy, or freshness of the underlying administrative data. If addresses feed regulatory reporting, KYC, or billing disputes, get legal and data-quality sign-off on the upstream source, and be prepared to reconcile against official BPS/ Kemendagri references.
• You need guarantees. 101 stars and zero dependent packages is a real signal: this is a single-maintainer project with a thin adoption base. There is no vendor SLA, no security-response commitment, no commercial support. For a revenue-critical path, that means forking it or accepting maintenance risk explicitly.
• You need sub-district geospatial work. Coordinates are present, but SQLite without spatial extensions is not a routing, isochrone, or spatial-join engine. Distance matrices, delivery-route optimization, and polygon containment belong in PostGIS or a dedicated geo service.
• You need official boundary polygons at scale rather than point coordinates — the static GeoJSON output may not meet cartographic or compliance-grade boundary requirements.
• You operate outside Indonesia, or need a country-agnostic address model from day one. The schema and semantics are Indonesia-specific by design.
• You require write-heavy or high-concurrency access to the reference data itself. SQLite under concurrent writes is the wrong substrate; treat this as read-only reference and cache accordingly.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: Indonesia's administrative data — 4 levels of regions, postal codes, coordinates — is normally a multi-week sourcing and cleanup exercise that produces no customer-visible value. Laravel Nusa gives us that dataset pre-compiled, with Laravel models, migrations, API routes, and multilingual docs, under an MIT license, at zero cost. It removes a prerequisite from our Indonesia roadmap and lets the team spend that time on the features customers actually pay for. The trade-off is honest and bounded: it is a young, single-maintainer open-source project with a small user base, so we treat it as a pinned dependency we can fork, not a strategic platform bet. The code license is permissive; we will do a short diligence pass on the upstream data source before it touches anything regulatory.

For engineering — what you are actually signing up for:

• composer require, publish config/migrations/lang, and you have Province, Regency, District, Village models with proper belongsTo/hasMany relations, string code primary keys, and a nusa SQLite connection.
• Treat the admin data as read-only reference. Do not model customer addresses as writes into these tables; keep your own address table and foreign-key to code.
• Wrap it. Put lookups behind an internal RegionRepository interface so a future multi-country model, a commercial provider, or a swap-out is a one-file change.
• Pin the version and vendor the SQLite artifact in your deploy pipeline. CI must not depend on an upstream import at build time — the package's own workflow requires a Docker step and upstream pull, which is fine for their repo and wrong for ours.
• Cache aggressively. Region lists change rarely; ship them to the client once per release rather than querying per request.
• Watch the seams: SQLite concurrency, no timestamps on admin models, and coordinate availability that varies by level. Verify coverage for the specific levels you need — do not assume village-level coordinates are uniformly populated.
• Have an exit. Fork the repo into our org, keep the data-refresh script, and document how to regenerate the SQLite file from upstream. That converts a maintainer-risk concern into a routine maintenance task.

Ask: approve as a pinned dependency for non-regulatory address features in the Indonesia scope, with a 1–2 day diligence task on upstream data licensing and a stated intent to fork-and-own if maintenance lapses.