OpenGlobus: a WebGL engine for 3D maps, terrain and geospatial data

A rendering library, not a map service

OpenGlobus is described as a TypeScript and JavaScript library designed to display interactive 3D maps and other geospatial data at a scale from planet to bee. That last phrase is the positioning statement, and it tells you what kind of engine this is: the same renderer handles a whole planet and a small object, with the level of detail changing rather than the tool.

The capability list in the README is concrete. It supports various high-resolution terrain providers, imagery layers, renders thousands of 3D objects, and provides geometry measurement tools. Everything is rendered with WebGL, and the project's own framing is that it is open source and completely free.

The stated goal is to make 3D map features fast, good-looking, user-friendly and easy to implement in any related project, which is a fairly broad promise. The practical question is what the library expects to own and what it expects you to own. The answer is visible in the package metadata: it is a rendering engine that takes layers, terrain and objects and draws them, with no hosting, no tile server and no data pipeline inside the box. The topic tags on the repository, ranging from 3dmap and earth through lidar, terrain-rendering and webgl2, match that scope.

So the audience is application developers who need 3D geospatial visualisation inside a web product, not analysts who want a globe to look at and not data teams who want a spatial database.

The npm package is one ES module plus a separate styles entry

The packaging tells you how the library is meant to be consumed. In package.json the package is named @openglobus/og, the main field points at lib/og.es.js and the types field at lib/index.d.ts.

The exports map has two entries. The root entry resolves to the ES module bundle with its types, and a separate ./styles entry resolves to lib/og.css. That split is the detail worth knowing, because it means a bundler-aware application can pull the stylesheet without importing the library, which keeps the CSS out of the JavaScript dependency graph and lets you load it once.

Only the lib/ directory is published, listed in the files array, and publishConfig sets access to public. The build output, described in the README, consists of og.es.js, og.es.js.map, og.css and a ./res/... directory of resources. The res directory matters in practice, because a map library that loads textures, fonts and other assets will need those served alongside the bundle rather than inlined.

The version recorded in package.json is 1.0.0-rc33, which is a release candidate rather than a stable 1.0.0. The library is authored in TypeScript, and the type declarations are generated by the build rather than hand written, so the published types track the published bundle exactly. For an application in TypeScript that is a good arrangement, and it also means the types are only as stable as the candidate version they ship with.

Scaffolding a first application with create-openglobus

The fastest route to a working application is the template package the README points to, create-openglobus, which supports JS, TS, React and more. You invoke it through npx:

npx create-openglobus

The template is the recommended way to create a first application, and it exists precisely because a 3D map library has a fair amount of wiring: a WebGL canvas, a camera, a coordinate system and at least one layer to look at.

For an existing project, the library installs as an ordinary npm dependency:

npm install @openglobus/og

React projects have a separate binding in its own package, and the README points to the openglobus-react repository for the module:

npm i @openglobus/openglobus-react

Two notes for anyone integrating this. First, the stylesheet lives behind the ./styles export, so your bundler import has to ask for that path rather than expecting the CSS to arrive with the main entry. Second, the res/ resources have to be reachable at runtime, which is the kind of detail that a template handles for you and a hand-rolled integration discovers on deployment day.

For a first real look at what the engine can draw, the README points at a sandbox of examples, and the development instructions give a concrete local path once the examples are served, for example http://127.0.0.1:3000/sandbox/osm/osm.html. That path is worth visiting early, because it shows the expected structure of a scene before you write your own.

Vite builds it, JSDoc documents it, tsc emits the types

The toolchain is visible in the scripts section of package.json, and it is conventional rather than exotic.

The production build is vite build --mode production followed by the declaration step. The dev loop uses vite build --watch --mode development, which rebuilds into the lib folder as an ES module while you work. A local static server is provided by ws, and the combined dev_serve script runs the watcher and the server in parallel. The docs build runs jsdoc over ./src/ with jsdoc.conf.js and writes to ./docs/, and the README documents it as npm run docs, producing the API documentation site.

The remaining scripts are the ones you would expect from a serious JavaScript project: eslint over src/ for linting, Prettier for formatting src and css with a separate non-modifying check, vitest for tests with a verbose reporter, and tsc --build tsconfig.json for declarations. There is a jest.config.js in the repository root alongside vitest.config.ts, and a vite-plugin-force-terser.js for the production bundle, plus a babel.config.js.

The practical consequence for an adopter is that the documentation you read is generated from the same source you compile, and the types are generated from the same build. There is no hand-maintained API surface that can drift. The cost is the usual one: a documented build pipeline that has to be understood before you can produce a custom bundle, and a dependency set that includes Babel, Jest, ESLint, Prettier, JSDoc, Vite and Vitest even though only the runtime library reaches your application.

Release candidates landed three times in the last week

The release history is the most important operational fact about this project, and it is a little unusual.

Three release candidates shipped in the space of a week: v1.0.0-rc31 on 2026-10-12, v1.0.0-rc32 on 2026-10-16 and v1.0.0-rc33 on 2026-10-17, with the last push to the repository on 2026-10-19. The version in package.json matches rc33, so the published package and the newest tag are in step.

Candidates moving this fast are a signal of intensity rather than of stability. The API can and does change between candidates, and the 1.0.0 line is not yet a fixed point. If you adopt, pin an exact candidate and read CHANGELOG.md before every bump, because the upgrade cost is the diff between two rc builds rather than a documented migration guide.

The same caution applies to the surrounding resources. The repository holds CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, STYLEGUIDE.md and CHANGELOG.md, and the README lists the community channels: the issue tracker, discussions, a gitter chat, a forum and an OpenCollective page for financial support. The project describes itself as free and open source, and the licence section names Apache-2.0, with LICENSE.md in the repository root.

Apache-2.0 is a permissive licence with an explicit patent grant, which for a library embedded in a commercial product is a straightforward choice. That is a factual note about the terms, not advice on how to apply them, and you should read LICENSE.md for the text that applies to your use.

Where OpenGlobus is the wrong tool

There are cases where this library is the wrong answer, and they are structural rather than fixable.

The first is a flat map. If your requirement is a 2D map with markers, a raster tile stack gives you a result with far less machinery, and there is nothing in the OpenGlobus feature list that a 2D map needs. The library's value is in the third dimension and in the geospatial objects it renders, and a plan view throws that away while keeping the WebGL and asset overhead.

The second is the delivery model. A browser WebGL renderer is a client-side 3D pipeline with its own bundle, its own GPU requirements and its own asset hosting. A mobile browser on an old device, a locked-down corporate environment or a very large set of objects will all hit the edges of what a client-side renderer can do, and the README does not document a server-side rendering or a streaming fallback. If your users need a lightweight 2D view, a separate path is required.

The third is the release status. Adopting a release candidate library means your own upgrade cadence is tied to someone else's candidate cycle, and a breaking change between rc32 and rc33 is a change you will meet without a stable contract to plan against.

The alternative, then, is architectural rather than a competing library: build the visualisation on a raster tile map and add only the 3D elements that genuinely need to be 3D. The difference in approach is that OpenGlobus gives you the whole globe, the terrain and the object layer in one WebGL engine with measurement tools, while a tile-based approach gives you a smaller surface area, lighter assets and a far less demanding runtime, at the cost of giving up the continuous 3D view that is the entire point of this library.

Editorial conclusion

Adopt OpenGlobus if your product needs a 3D globe or terrain view in a web application, if you can live inside the WebGL rendering model, and if you are prepared to track release candidates. Do not adopt it for flat 2D mapping, where a raster tile stack is simpler, and do not build on the assumption that the API is frozen, because the published version is 1.0.0-rc33 and candidates appeared on 2026-10-12, 2026-10-16 and 2026-10-17. Before you commit, read CHANGELOG.md, check the Apache-2.0 terms in LICENSE.md, and confirm that npm run dts produces the TypeScript declarations your project expects from lib/index.d.ts.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. openglobus/openglobus on GitHub
3. Project website
4. README
5. Releases