PMTiles vector source fails when mapbox-gl is loaded via npm bundler (Vite/Rollup/Webpack)

[whirano]

mapbox-gl-js version

3.24.0

Browser and version

No response

Expected behavior

Description

PMTiles vector sources work correctly when Mapbox GL JS is loaded via CDN <script> tag, but fail with u is not defined error when the same version is imported as an npm package and bundled with Vite, Rollup, or Webpack.

Steps to reproduce

1. Install mapbox-gl@3.24.0 via npm/yarn.
2. Import and bundle with Vite (or any bundler).
3. Add a PMTiles vector source:

map.addSource('test', {
  type: 'vector',
  url: 'https://docs.mapbox.com/mapbox-gl-js/assets/earthquakes.pmtiles'
});

4. Observe error in console: u is not defined from loadTileProvider in the worker blob.

Actual behavior

Actual behavior

Worker fails to dynamically import the PMTiles provider plugin. The error occurs in both dev and production builds.

Root cause analysis

The TILE_PROVIDER_URLS config uses a relative path (/mapbox-gl-js/plugins/mapbox-gl-pmtiles-provider/v0.0.2/mapbox-gl-pmtiles-provider.js).

• When loaded via CDN, this resolves to https://api.mapbox.com/mapbox-gl-js/plugins/....
• However, when bundled via npm, the Worker blob's origin becomes blob:http://localhost:..., so the dynamic import() resolves to http://localhost/mapbox-gl-js/plugins/... which doesn't exist.

Workaround

• Use CDN <script> tag instead of npm package.
• Or, use MapLibre GL JS with the pmtiles library.

Environment

• mapbox-gl: 3.24.0
• Bundler: Vite 8 (also reproduced with production build, so not Vite-specific)
• Browser: Chrome
• OS: Linux

Link to the demonstration

No response

Steps to trigger the unexpected behavior

No response

Relevant log output

[mourner]

@whirano for the current workaround, please try doing import mapboxgl from 'mapbox-gl/esm' in your Vite setup (or import * as mapboxgl from 'mapbox-gl/esm' if you're on v3.25+). Meanwhile, we'll investigate.

[whirano]

@mourner
Hi,

Thank you for the suggested workaround! I can confirm that switching to the ESM build resolves the issue in my environment.

Since my project uses react-map-gl, updating the import statement directly in my application-level code didn't propagate to react-map-gl's internal imports. To ensure all consumers resolve to the ESM build, I applied the redirect at the bundler level using Vite's resolve.alias:

// vite.config.ts
export default defineConfig({
  resolve: {
    alias: [
      { find: /^mapbox-gl$/, replacement: 'mapbox-gl/esm' }
    ]
  }
})

With this alias in place, all instances—including react-map-gl—correctly resolve to the ESM build, and PMTiles vector sources with url: 'xxx.pmtiles' now load perfectly without the u is not defined Worker error.

I'll keep this workaround active for now. Please let me know if a proper fix is planned for v3.25 or a later release.

Thanks again for the quick response!

[stepankuzmin]

@whirano could you please try overriding the pmtiles provider URL with mapboxgl.addTileProvider before you initialize the map?

mapboxgl.addTileProvider('pmtiles', 'https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-pmtiles-provider/v0.0.2/mapbox-gl-pmtiles-provider.js');

[whirano]

@stepankuzmin
Thanks for the suggestion! I tried overriding the provider URL with mapboxgl.addTileProvider before map initialization, but it didn't resolve the issue on its own.

The root cause turned out to be that the default provider URL (/mapbox-gl-js/plugins/...) is a relative path, which fails to resolve inside the Worker blob because the blob's origin is blob: rather than the actual host origin.

Overriding it with the absolute URL via addTileProvider did fix that specific problem, but only when combined with the existing workaround of aliasing mapbox-gl to mapbox-gl/esm in the Vite config. Without the ESM alias, a separate __vite__injectQuery is not defined error occurs inside the Worker.

So, the working solution for a Vite/npm environment is a combination of both:

1. Alias mapbox-gl to mapbox-gl/esm in vite.config.ts (to avoid Vite transform artifacts in the Worker).
2. Call mapboxgl.addTileProvider('pmtiles', 'https://api.mapbox.com/...') before map initialization (to fix the relative URL resolution in the Worker blob).

With both in place, PMTiles loads correctly. Hope this helps others hitting the same issue!

[stepankuzmin]

I guess we could expose esm entrypoint right in the react-map-gl

import Map from 'react-map-gl/mapbox-esm';

Something like visgl/react-map-gl#2594

[stepankuzmin]

Btw, it seems that react-map-gl has a mapLib prop that you can use to pass the ESM variant of GL JS:

import Map from 'react-map-gl/mapbox';
import mapboxGl from 'mapbox-gl/esm';

<Map mapLib={mapboxGl} {...props} />

@whirano could you please check if that works for you?

[whirano]

@stepankuzmin
Thanks for the suggestion! I tested it and it works — PMTiles vector sources load correctly with this approach.

However, I ran into one caveat: since mapbox-gl/esm is a separate module instance from the mapbox-gl that my helper code imports internally, the Mapbox access token set on one instance is not shared with the other.

Concretely, my token initialization code does:

import mapboxgl from 'mapbox-gl'
mapboxgl.accessToken = token  // sets token on the CJS/default instance

But the uses the ESM instance, which has no token set — resulting in:

Error: An API access token is required to use Mapbox GL.

The fix was to explicitly set the token on the ESM instance as well:

import mapboxGlEsm from 'mapbox-gl/esm'

fetchToken().then((token) => {
  mapboxGlEsm.accessToken = token  // must set on the ESM instance separately
})

So the mapLib approach does work, but requires careful attention to which module instance holds the access token.

For our codebase, the Vite resolve.alias approach (mapbox-gl → mapbox-gl/esm) remains simpler since it unifies all imports to the same instance automatically — no duplicate token management needed.

That said, the mapLib prop is a clean solution for projects that don't use a bundler alias, as long as they're aware of the instance isolation. I hope documenting this specific behavior helps others avoid the same "missing token" pitfall!

[stepankuzmin]

Thanks for taking a look, @whirano!

I think it'd be better to stick with a single ESM bundle instead of having two different bundles. You can set accessToken directly when you create a map instance like:

import * as mapboxgl from 'mapbox-gl/esm';

const accessToken = await fetchToken();

const map = new mapboxgl.Map({
    accessToken,
    container: 'map'
});

Similar in react-map-gl:

function App() {
  return <Map mapboxAccessToken={accessToken} />;
}

[whirano]

@stepankuzmin
You're right — we removed the Vite alias and migrated to mapLib={mapboxGlEsm} + mapboxAccessToken={token} prop. Since all direct Mapbox GL API calls go through the Map instance ref, they naturally share the same ESM instance, so no separate global token management is needed. Works perfectly. Thanks for guiding us to the cleaner solution!