maplibre-native-gl-js-parity
Six places where MapLibre Native (Android, iOS) and MapLibre GL JS differ, release by release — custom URL schemes (`addProtocol`), globe projection, 3D terrain, `interpolate-hcl` and `interpolate-lab
SKILL.mdskills/maplibre-native-gl-js-parity/SKILL.md
GitHubMapLibre Native and GL JS Parity
MapLibre GL JS and MapLibre Native read the same style specification but ship features at different times. A style key Native does not know is ignored, and a paint value it cannot parse drops its layer, both without a crash, so the symptom is a map that quietly differs from the browser. The table below names each gap this skill covers, the release that closed it where one has, and what to do on Native instead. Rows were checked against android-v13.7.1 (2026-10-15) and ios-v7.0.0 (2026-10-28).
When to Use This Skill
These are symptoms as you would observe them, before you know the cause:
- The browser shows a globe, the app stays flat: the style sets
"projection": {"type": "globe"}and nothing changes on Android or iOS however far the map zooms out (no Native release draws a globe). - One layer never draws on Android or iOS, no crash, every other layer fine: a paint value uses an expression the installed release does not implement, such as
interpolate-hclbefore android-v13.7.1 or ios-v7.0.0, so the whole layer is dropped. - Porting
map.setTerrain(...)to Kotlin or Swift: there is nothing to port it to (no Native release has 3D terrain). - A
maplibregl.addProtocolhandler needs an Android or iOS equivalent: there is noaddProtocolon Native; app code answers the request in each platform's HTTP stack instead. - Elevation-banded color on a phone without pre-rendered tiles: a
color-relieflayer, on Native since android-v13.0.0 and ios-v6.24.0. - A
.pmtilesarchive in an iOS or Android app: no tile server, conversion, or package;pmtiles://is built in since android-v11.8.0 and ios-v6.10.0.
Scope. The table's six gaps are the ones where a model answering without this skill gets the API or the release wrong. The renderers differ in other places too. For a feature not in the table, find the release that added it in the Native CHANGELOGs.[5] [6] The js-parity label tracks open gaps,[1] but some open issues there describe shipped features.
The gaps, and what to do on Native
| Feature | MapLibre GL JS | MapLibre Native | Do on Native |
|---|---|---|---|
A custom URL scheme for tiles (vault://…) |
addProtocol, promise-based since 4.0.0[9] |
No addProtocol; #3562 open[2] |
Android: a custom HttpRequest from a ModuleProvider (android-v11.0.0), an OkHttp interceptor on https:// URLs the app marks, or a CustomVectorSource (android-v13.5.0). iOS: a URLProtocol in MLNNetworkConfiguration's sessionConfiguration (every release). |
Globe projection (projection: globe) |
Yes | No release; #3161 open[3] | Stay on Mercator, or show the globe in a web view running GL JS |
3D terrain (map.setTerrain, the style's terrain) |
Yes | No release; #252 open[4] | hillshade or color-relief on the same raster-dem source: shading on a flat map, not relief |
interpolate-hcl, interpolate-lab |
Yes | android-v13.7.1, ios-v7.0.0 (#4668); earlier releases drop the layer[5] [6] | Upgrade, or keep the release and use a plain interpolate ramp with intermediate stops |
color-relief layer |
5.6.0[9] | android-v13.0.0, ios-v6.24.0 (#3965)[5] [6] | Use it from the style; there is no raster-color on either renderer |
| PMTiles | The pmtiles package registers pmtiles:// with addProtocol |
Built in: pmtiles:// since android-v11.8.0, ios-v6.10.0 (#2882)[5] [6] |
pmtiles://https://… in the style, or on iOS MLNVectorTileSource(identifier:configurationURLString:) |
Custom URL schemes: four doors, and none is addProtocol
Native has no API that registers a scheme. It reads asset://, file://, mbtiles:// and pmtiles:// URLs itself and passes every other URL, vault:// included, to the platform's HTTP stack, where app code can answer it.[10]
Android: keep the style's vault:// URLs and answer every request yourself. A ModuleProvider hands MapLibre the HttpRequest it uses for every resource (tiles, the style, sprites, glyphs), since android-v11.0.0.[5] [7] Delegate what is not yours to the stock request:
import org.maplibre.android.MapLibre
import org.maplibre.android.ModuleProvider
import org.maplibre.android.http.HttpRequest
import org.maplibre.android.http.HttpResponder
class VaultHttpRequest(private val stock: HttpRequest) : HttpRequest {
override fun executeRequest(
responder: HttpResponder, nativePtr: Long, resourceUrl: String,
dataRange: String?, etag: String?, modified: String?, offlineUsage: Boolean
) {
if (!resourceUrl.startsWith("vault://")) {
return stock.executeRequest(responder, nativePtr, resourceUrl, dataRange, etag, modified, offlineUsage)
}
val bytes = Vault.decryptTile(resourceUrl) // your code: the MVT bytes for this URL
// code, eTag, lastModified, cacheControl, expires, retryAfter, xRateLimitReset, body
responder.onResponse(200, null, null, null, null, null, null, bytes)
}
override fun cancelRequest() = stock.cancelRequest()
}
val stock = MapLibre.getModuleProvider()
MapLibre.setModuleProvider(object : ModuleProvider by stock {
override fun createHttpRequest(): HttpRequest = VaultHttpRequest(stock.createHttpRequest())
})
Set the provider before the first MapView is created. Report a failure with responder.handleFailure(type, message) rather than an empty body; type is one of the three constants on HttpRequest: CONNECTION_ERROR, TEMPORARY_ERROR, PERMANENT_ERROR.
Or, on Android, add the source from code and hand over tiles by z/x/y. A CustomVectorSource (android-v13.5.0) asks a CustomVectorTileProvider for each tile and takes the raw MVT bytes back as TileData.Mvt.[5] [7] The style JSON does not reference it; the source and its layers are added in code:
val vault = CustomVectorSource(
id = "vault",
provider = object : CustomVectorTileProvider {
override suspend fun fetchTile(z: Int, x: Int, y: Int): TileData =
TileData.Mvt(Vault.decryptTile(z, x, y)) // your code: the MVT bytes
},
scope = lifecycleScope,
maxZoom = 14
)
style.addSource(vault)
style.addLayer(FillLayer("parcels", "vault").withSourceLayer("parcels"))
Or, on Android, change the tile URLs to https:// ones the app marks, and answer those in an OkHttp interceptor. It takes http:// or https://: the stock request drops any URL OkHttp's HttpUrl.parse rejects, vault:// included, before the client sees it, logging [HTTP] Unable to parse resourceUrl and never answering.[7] HttpRequestUtil.setOkHttpClient sets the OkHttp client that request uses, in every release, and an application interceptor on it returns its own Response for the marked requests, here those with a vault query parameter, and passes the rest to the network:
import okhttp3.OkHttpClient
import okhttp3.Protocol
import okhttp3.Response
import okhttp3.ResponseBody.Companion.toResponseBody
import org.maplibre.android.module.http.HttpRequestUtil
HttpRequestUtil.setOkHttpClient(OkHttpClient.Builder().addInterceptor { chain ->
val request = chain.request()
if (request.url.queryParameter("vault") == null) return@addInterceptor chain.proceed(request)
val bytes = Vault.decryptTile(request.url) // your code: the MVT bytes for this URL
Response.Builder().request(request).protocol(Protocol.HTTP_1_1).code(200).message("OK")
.body(bytes.toResponseBody()).build()
}.build())
MapLibre reads that Response like a server's, ETag, Cache-Control and Expires included, and stores the tile in its ambient cache.
iOS: keep the style's vault:// URLs and answer them in a URLProtocol. MapLibre builds its URLSession from MLNNetworkConfiguration.sharedManager.sessionConfiguration, in every release (MGLNetworkConfiguration before ios-v6.0.0).[6] [10] Add a URLProtocol subclass whose canInit(with:) accepts the vault scheme to that configuration's protocolClasses before the first MLNMapView is created. Answer each request with an HTTPURLResponse (status 200) and the tile bytes; MapLibre reports a plain URLResponse as an error that reads Response class is not NSHTTPURLResponse.
- ❌
MapLibre.addProtocol,MapLibreMap.addProtocol,Style.addProtocol, or a request-handler option onMapLibreMapOptions: none exists. - ❌
FileSource.setResourceTransformto serve bytes: it returns a replacement URL, nothing else.
Globe projection: no release draws one
The style's projection key has no effect on Android or iOS; the map stays Mercator, and nothing in MapView or MLNMapView turns a globe on. The work is tracked in #3161;[3] until a release note names it, the choices are a Mercator map or GL JS in a web view.
3D terrain: shade it, do not raise it
Native has no setTerrain, no terrain style block, no TerrainOptions, and no Terrain(...) constructor; the work is tracked in #252.[4] The same raster-dem source still draws two things, both on a flat map:
{ "id": "shade", "type": "hillshade", "source": "dem" }
{
"id": "relief",
"type": "color-relief",
"source": "dem",
"paint": {
"color-relief-color": ["interpolate", ["linear"], ["elevation"], 0, "#2e8b57", 1500, "#8b5a2b", 3000, "#ffffff"]
}
}
color-relief is on Android since android-v13.0.0 and on iOS since ios-v6.24.0; hillshade predates both.[5] [6] A hillshade or color-relief layer sits in the layer order like any other layer, so put it above the fills it should shade. ["elevation"] is the DEM value at the pixel, an expression of its own that takes no argument. On Android the same layer is built in code with the ramp passed as JSON through Expression.raw(), which is the builder route for ["elevation"], interpolate-hcl and interpolate-lab alike:[7]
style.addLayer(
ColorReliefLayer("relief", "dem").withProperties(
PropertyFactory.colorReliefColor(
Expression.raw("""["interpolate", ["linear"], ["elevation"], 0, "#2e8b57", 1500, "#8b5a2b", 3000, "#ffffff"]""")
)
)
)
interpolate-hcl and interpolate-lab: a version boundary
Both expressions work on Native from android-v13.7.1 and ios-v7.0.0 (#4668).[5] [6] On Android they go in style JSON or through Expression.raw(); the typed Expression builders stop at interpolate.
On an earlier release the paint value does not parse and the whole layer is dropped, with no crash. The one trace is a log line that reads [ParseStyle]: value must be a string and nothing more: no layer id, no property name, no expression. The symptom to work back from is one missing layer. The fix for a release you cannot raise is a plain interpolate with intermediate stops along the ramp:
"fill-color": ["interpolate", ["linear"], ["get", "density"], 0, "#f7fbff", 1250, "#c6dbef", 2500, "#6baed6", 3750, "#2171b5", 5000, "#08306b"]
PMTiles: built in, with one iOS trap
Native reads a PMTiles archive directly through its own pmtiles:// scheme, since android-v11.8.0 and ios-v6.10.0 (#2882):[5] [6] no tile server, no MBTiles conversion, no custom source, and no pmtiles package or URLProtocol subclass. Put the scheme in front of the archive's full URL in the style, here a test archive MapLibre hosts:
{ "world": { "type": "vector", "url": "pmtiles://https://demotiles.maplibre.org/pmtiles/vector/world.pmtiles" } }
That style entry works on Android and iOS alike. MapLibre's iOS guide covers local archives and raster sources too.[11] A vector source built in Swift code uses configurationURLString:, the initializer that takes the string as is. URL(string:) mangles pmtiles://https:// on iOS 17, so a source made with configurationURL: never loads (#3151):[8]
let world = MLNVectorTileSource(
identifier: "world",
configurationURLString: "pmtiles://https://demotiles.maplibre.org/pmtiles/vector/world.pmtiles"
)
style.addSource(world)
- ❌
MLNVectorTileSource(identifier: "world", configurationURL: URL(string: "pmtiles://https://…")!): theURLform is the one iOS 17 breaks, though the iOS guide's samples use it.
Since android-v13.7.1 an archive bundled in the APK loads with pmtiles://asset://….[5]
Related Skills
- maplibre-terrain-rendering —
hillshade,color-relief, and 3D terrain on GL JS - maplibre-pmtiles-patterns — the
pmtilespackage andaddProtocolon GL JS; serving and building archives
References
- MapLibre Native
js-paritylabel — Native's tracking issues for gaps between the two renderers - maplibre-native#3562 — custom URL schemes (
addProtocol) on Native - maplibre-native#3161 — globe projection on Native
- maplibre-native#252 — 3D terrain on Native
- MapLibre Native Android CHANGELOG — 11.0.0 custom
ModuleProvider(#2231); 11.8.0 PMTiles (#2882); 13.0.0color-relief(#3965); 13.5.0CustomVectorSource(#4377); 13.7.1interpolate-labandinterpolate-hcl(#4668) andpmtiles://asset://(#4602) - MapLibre Native iOS CHANGELOG — 6.0.0 the
MGLtoMLNprefix change; 6.10.0 PMTiles; 6.24.0color-relief; 7.0.0interpolate-labandinterpolate-hcl - Android API, android-v13.7.1 —
ModuleProvider.java,http/HttpRequest.java,http/HttpResponder.java,module/http/HttpRequestImpl.java,module/http/HttpRequestUtil.java,style/sources/CustomVectorSource.kt,style/sources/CustomVectorTileProvider.kt,style/sources/TileData.kt,style/layers/ColorReliefLayer.java,style/layers/PropertyFactory.java,style/expressions/Expression.java MLNVectorTileSource.h— theconfigurationURLString:initializer and its iOS 17 note- MapLibre GL JS CHANGELOG — 4.0.0 promise-based
addProtocol; 5.6.0color-relief - MapLibre Native resource loading, ios-v7.0.0 —
default/src/mln/storage/main_resource_loader.cpp(the schemes Native reads itself),darwin/src/MLNNetworkConfiguration.h(sessionConfiguration),darwin/core/http_file_source.mm(theURLSessionbuilt from it and theNSHTTPURLResponsecheck) - MapLibre Native for iOS: PMTiles — remote and local archives, vector and raster sources
This skill is a snapshot. Where a primary source contradicts it — the References above, MapLibre's current documentation, or what MapLibre does when you run it — that source wins. Follow it, then report the disagreement, citing the source and your MapLibre version: editing your installed copy helps no one else and is overwritten on the next update.