maptalks-gl: a WebGL map engine for 2D/3D layers, and how to install it

What maptalks-gl is for, and who it is not for

maptalks-gl targets JavaScript developers who need 2D and 3D map content in the same scene rather than in two separate renderers. The README lists the formats it accepts: vector tiles, 3DTiles and GLTF, alongside 3D analysis functions and traffic simulation animations. The unit of composition is the layer. A GroupGLLayer holds other layers, so a vector tile basemap, a GLTF model layer and a polygon layer can sit in one group and share one WebGL context.

The project is a rewrite rather than a version bump. The README states that maptalks is upgrading to maptalks-gl, a WebGL and WebGPU driven engine, and that the old maptalks source now lives under packages/maptalks as a submodule. It also states that maptalks-gl will be officially published in a few months and that the API migration path from legacy maptalks is still marked TBD. If you are maintaining an existing maptalks application, that TBD is the part that concerns you.

This is not a drop-in tile viewer for people who want a map on a page in ten minutes. There is no documented no-build path beyond the CDN bundle, and no statement in the README about which browsers the WebGL and WebGPU paths require.

How the GroupGLLayer composition model works

The architecture visible in the README is a set of packages under a pnpm workspace, each owning one concern. The gl package supplies the WebGL base layer, terrain, post-processing and 3D masks, including GroupGLLayer. layer-3dtiles supplies Geo3DTilesLayer. layer-gltf supplies GLTFLayer and GLTFMarker. layer-video supplies VideoLayer and VideoSurface. Vector tile rendering is split between vt-plugin, which defines the interface, and vt, which implements VectorTileLayer and GeoJSONVectorTileLayer. Analysis and traffic simulation are separate packages.

Data flows through the group rather than to the map directly. In the README example, a VectorTileLayer is constructed with a urlTemplate, wrapped in a GroupGLLayer, and the group is added to the map. The GLTF and polygon layers are then added to the group with groupLayer.addLayer. That indirection is the design: the group owns the GL context and the render loop, and member layers contribute geometry.

The rendering stack underneath is reshader.gl, described in the README as a regl-based implementation of the 3D rendering interface, with renderer, scene, mesh and material classes and predefined materials such as PBR. gltf-loader handles GLTF parsing. If you have used regl before, the mental model transfers; if you have not, the README does not explain how to reach into that layer.

Installing maptalks-gl and rendering a first map

The README gives three package managers for the published package. The npm form is the shortest:

npm i maptalks-gl

The README also lists yarn add maptalks-gl and pnpm i maptalks-gl as equivalents. After installation, the ESM entry point exports the map, the group layer and the layer types you need. The README's own example imports Map, GroupGLLayer, VectorTileLayer, GLTFMarker, GLTFLayer and PolygonLayer from maptalks-gl, constructs a map with center and zoom, builds a vector tile layer from a urlTemplate, and adds the group to the map:

import { Map, GroupGLLayer, VectorTileLayer } from 'maptalks-gl';

const map = new Map('map', {
    center: [0, 0],
    zoom: 2
});
const vtLayer = new VectorTileLayer('vt', {
    urlTemplate: 'http://tile.maptalks.com/test/planet-single/{z}/{x}/{y}.mvt'
});

const groupLayer = new GroupGLLayer('group', [vtLayer]).addTo(map);

What you should see is a map element with the vector tile layer rendered through WebGL. The first argument to Map is the id of a DOM element, which the example assumes exists. The urlTemplate is a test endpoint from the README; substitute your own tile server.

If you need compressed geometry or textures, the README describes optional transcoders that are imported separately from the main package:

import '@maptalks/transcoders.draco';
import '@maptalks/transcoders.crn';
import '@maptalks/transcoders.ktx2';

Without these imports, the README implies draco, crn and ktx2 encoded assets will not decode. There is also a UMD route: a script tag for https://unpkg.com/maptalks-gl/dist/maptalks-gl.js plus a stylesheet at dist/maptalks-gl.css, after which the README states that exported variables are mounted in the maptalks namespace, so you write new maptalks.Map rather than new Map.

Building from source and running the tests

Working on the repository itself is a different job from consuming the package. The README states the minimum node environment is 18.16.1 and that the project uses [email protected], while the root package.json declares packageManager [email protected] and engines.node 22. Those two statements do not agree, and the safest reading is to follow package.json when you build locally. The root scripts are driven by turbo, with build-gl filtering to maptalks-gl and @maptalks/analysis, and build covering maptalks-gl, maptalks-gpu and @maptalks/analysis.

pnpm i
pnpm build

The README describes pnpm run dev in the root folder of the package you are debugging for watch mode. Tests run under karma or electron-mocha depending on the package, and the README says to run npm test under each project. For electron-mocha packages, a single spec is selected with pnpm run tdd -- -g followed by the spec keywords. For karma packages, the README says you must edit the test file to change it to it.only, which is a rougher workflow than a CLI filter.

Where maptalks-gl gets awkward

The README carries its own warning. It says maptalks-gl is in active development now and will be officially published in a few months, and marks the legacy migration path as TBD. The release history does not match that framing: [email protected] is dated 2026-02-11 and [email protected] is dated 2026-03-04, so published artifacts exist. Treat the README as stale rather than as a description of an unreleased project, but do not treat the API as frozen either.

The documentation gaps are concrete. The README does not document rollback or downgrade, does not state browser support for the WebGL or WebGPU paths, and does not describe upgrading from a previous maptalks-gl minor version. It also does not explain how the published maptalks-gl package relates to the individual workspace packages. The README presents gl, layer-3dtiles, layer-gltf and others as packages, and separately notes that maptalks itself moved into packages/maptalks as a submodule, but it never says which of these you can install from npm on their own. If your build imports a layer package directly, confirm it exists on the registry before you commit to it.

The performance claim is the one to be most careful with. The README says maptalks-gl delivers a magnificent performance enhancement by WebGL. There are no numbers, no benchmark method and no hardware or dataset description anywhere in the README. For a project whose pitch rests on rendering throughput, that is a gap you should close with your own tiles before you plan around it.

maptalks-gl against Leaflet and deck.gl

Leaflet is the obvious alternative for a 2D map, and the difference is architectural rather than cosmetic. Leaflet renders through the DOM and canvas with a mature plugin ecosystem, and it has no 3D scene, no GLTF layer and no 3DTiles layer. If your content is raster tiles, GeoJSON and markers, Leaflet does that with far less setup than a GroupGLLayer and a WebGL context.

deck.gl is the closer comparison, because it also renders layers over WebGL and also handles large 3D datasets. The split is in the layer model. deck.gl is a visualization framework that composes layers over a base map, which it typically takes from MapLibre or Mapbox. maptalks-gl supplies the map, the group layer and the layer types in one package, and its README describes vector tile, 3DTiles and GLTF support as features of the engine itself. That is fewer moving parts if you want 3DTiles and GLTF inside the map rather than beside it. It is also a smaller ecosystem, and the README does not describe an equivalent to deck.gl's layer catalog or its interleaved-rendering story with other base maps.

Licence, release cadence and upgrade cost

The root package.json declares "license": "MIT". That is the strongest licence statement available here, and it covers the repository root. The published maptalks-gl package is a separate artifact, and its own licence field is not shown, so check the package metadata before you rely on MIT for the thing you actually ship. Nothing here suggests a copyleft obligation, but this is not legal advice and a licence file in the repository is the place to confirm it.

Upgrades are managed with changesets. The root scripts include changeset, changeset-version, changeset-tag and a release script that runs pnpm build before changeset publish, and the repository has a .changeset directory. That means version bumps and changelog entries are generated from changeset files rather than written by hand, which usually makes the release notes more consistent but also means the notes describe what contributors chose to record.

The cost of tracking releases is the API surface. The README describes a consistent API upgrade from legacy maptalks but marks it TBD, and the published versions sit in the 0.124.x range, which conventionally signals that breaking changes are still expected between minors. Pin your version, read the changeset for each bump, and expect the layer imports to be where breakage shows up first.

Editorial conclusion

Adopt maptalks-gl if you need vector tiles, 3DTiles or GLTF geometry in one JavaScript map and you can live with a README that still marks parts of the migration as TBD. Do not adopt it if you need a documented rollback path, a published browser support matrix, or a stable API contract today. Verify first that your tile endpoints match the urlTemplate form in the README, that the transcoders you need are installed, and that the packages you depend on are actually published, since the README describes some as submodules of this repository rather than npm packages.

Frequently asked questions

Official sources

1. Issues
2. maptalks/maptalks.js on GitHub
3. Project website
4. README
5. Releases