Osmix

Osmix is a collection of tools for reading, inspecting, and merging OpenStreetMap PBF data in modern JavaScript runtimes and the browser. The first application built with the tools is a worker-driven merge UI. Libraries span low-level PBF parsing, JSON transforms, and efficient typed-array indexes designed for any JavaScript environment.

Getting started

1. Install dependencies with bun install.
2. Run all workspace apps in watch mode via bun run dev.
3. Build production artifacts for packages and apps using bun run build.
4. Execute Vitest suites with bun run test and type coverage with bun run typecheck.
5. Enforce formatting and lint rules using bun run lint, bun run format, or the combined bun run check before sending a PR.

The workspace uses a single root package.json to coordinate shared scripts, dependency versions, and Bun workspace filters (for example, bun run --filter @osmix/merge dev).

Workspace

Apps

• apps/merge – Vite + React app that compares base and patch extracts, renders MapLibre raster and vector overlays, and guides multi-step merge workflows entirely in-browser.
• apps/bench – Experimental benchmark UI that contrasts Osmix operations with DuckDB-wasm queries using shared fixtures.

Packages

• packages/core – Core Osmix engine for ingesting PBF streams, building spatial indexes, and emitting JSON, PBF, or vector and raster tiles.
• packages/change – Change-management helpers that deduplicate entities, generate merge stats, and apply edits on top of @osmix/core.
• packages/json – Easy-to-use streaming converters between PBF bytes and strongly typed JSON entities, plus GeoJSON helpers tuned to OSM conventions.
• packages/pbf – Low-level toolkit that mirrors the official protobuf schema, offering streaming readers/writers, compression helpers, and generated type-safe codecs.
• packages/raster – Canvas-based raster tile renderer and MapLibre protocol built for @osmix/core datasets.
• packages/vt – Encodes Osmix binary overlays directly into Mapbox Vector Tiles with caching helpers.
• packages/shared – Small geometry utilities (haversineDistance, clipPolyline) shared across packages.
• packages/test-utils – Shared Vitest fixtures and helpers used across packages.

Development

• fixtures/ – sample extracts referenced by integration tests and the merge app.

Resources

• OpenStreetMap PBF format
• Bun workspace documentation
• Vite build tooling
• MapLibre GL JS
• Web Compression Streams API