How Navara Works
Headless Architecture
Section titled “Headless Architecture”Navara is a headless 3D globe map engine. Its GIS core is written in Rust and compiled to WebAssembly, deliberately separated from any specific rendering technology. Currently, Navara provides a Three.js-based rendering backend (@navaramap/three), but the engine is designed so that other rendering engines — and even native platforms — can be supported in the future.
The Rust/WASM GIS engine handles all geospatial computation independently of the renderer, and CPU-intensive tasks are distributed across Web Workers for responsive performance even with large datasets.
Plugin-Based Architecture
Section titled “Plugin-Based Architecture”Navara uses a plugin system to register descriptor types. Before calling init(), you add plugins to a ThreeView instance. Each plugin registers the mesh, light, and effect descriptor types it provides. After initialization, you can add descriptors of those registered types.
DefaultPlugin (from @navaramap/three_default_plugin) registers built-in mesh, light, and effect descriptors. For most applications, adding DefaultPlugin is all you need to get started.
You can also create your own mesh descriptors, effect descriptors, and light descriptors with full access to the rendering engine’s scene graph. This is the same mechanism that powers Navara’s built-in descriptors. For details, see the Custom Descriptor documentation.
In addition to these, Navara provides layers for loading and displaying geographic data such as GeoJSON, MVT, and 3D Tiles. Layers handle the complexity of features and their attributes — parsing, spatial indexing, and attribute-based styling through FeatureEvaluator. Mesh descriptors, on the other hand, deal only with geometry and rendering, which allows them to be optimized purely for draw performance and is suited for rendering large numbers of objects efficiently. This separation lets you choose the right tool for each use case. For more on descriptor types, see Layer Types.
Tiered API
Section titled “Tiered API”Navara organizes its API into tiers with different stability guarantees, so that casual users get a simple, stable interface while plugin developers can access deeper functionality when needed.
Tier 0: ThreeView is the primary entry point for all users. It provides high-level methods for camera positioning, layer management, plugin registration, and lifecycle control. This surface is intentionally kept small and stable — breaking changes require a major version bump. See the ThreeView API reference for details.
Tier 1: Plugin + ViewContext is available to plugin and Descriptor developers. When a plugin is initialized, it receives a ViewContext that provides controlled access to rendering internals such as scenes, pass management, and the renderer reference. This level offers more power at the cost of occasional breaking changes between minor versions. See the Plugin and Custom Descriptor documentation for details.
Tier 2: Advanced is planned for future use cases that require deeper integration, such as injecting an external renderer or replacing the render loop. These APIs will be explicitly marked as unstable.
For most applications, you will only interact with Tier 0 — the ThreeView class.
Library Overview
Section titled “Library Overview”Navara is split into several npm packages. This can seem complex at first, but the separation follows directly from the headless design: the GIS engine is independent of any renderer, the rendering backend is a separate layer, and descriptor implementations are separate from the core so you can choose which ones to include.
In practice, most applications only need two packages: @navaramap/three for the core engine and @navaramap/three_default_plugin for the built-in descriptors.
| Package | Role | When you need it |
|---|---|---|
@navaramap/three | Main package — ThreeView class, source & layer API, camera control | Always |
@navaramap/three_default_plugin | DefaultPlugin — built-in mesh, light, and effect descriptors | Almost always |
@navaramap/three_default_descs | Individual descriptor class implementations | When registering descriptors manually without DefaultPlugin |
@navaramap/three_api | Standalone GIS utilities (coordinate transforms, geodesic calculations) | When you need GIS math without the full map engine |
Navigating the Documentation
Section titled “Navigating the Documentation”This documentation is organized into several sections that correspond to different parts of the system.
The three section covers everything related to @navaramap/three — the ThreeView API, camera controls, layer concepts, and step-by-step tutorials. If you are building an application with Navara, this is where you will spend most of your time.
The three_default_descs section is a reference for all the mesh, effect, and light descriptor types provided by @navaramap/three_default_descs. Each descriptor type has its own page documenting its configuration options and usage examples.
The three_default_plugin section documents the DefaultPlugin API, including the convenience methods it provides for common setups.
The guides section (where you are now) contains this introduction, community resources, and contributor documentation.
Next Steps
Section titled “Next Steps”If you haven’t built your first globe yet, head to Getting Started. To dive deeper into the Three.js renderer, continue with What is navara_three?.