Function: installMapLibreWorker()
function installMapLibreWorker(): voidRegisters a self-contained MapLibre worker carried inside this bundle.
MapLibre 6 no longer inlines its worker. It resolves it at runtime with
new URL('./maplibre-gl-worker.mjs', import.meta.url), building the filename by concatenation so no
bundler can see it statically and none emit the file. Once a consumer bundles this SDK,
import.meta.url is the consumer’s own chunk, the worker is requested from a path where nothing
exists — in a single-page app the request falls through to the app shell and the worker dies on a
text/html MIME error — and the map renders nothing at all. Handing MapLibre a blob: URL removes
that resolution from the picture entirely, so this holds regardless of the consumer’s bundler, base
href, or whether the app is served from a subpath.
Must run before anything touches MapLibre’s global worker pool, which is earlier than it looks. The
pool is created by the first Dispatcher and the URL is read then, once, and not again while a map
is alive — so any MapLibre call that builds a Dispatcher ahead of this one wins permanently.
new Map(...) is the obvious one, but prewarm(), importScriptInWorkers() and the now-removed
setRTLTextPlugin() all do it too. Hence the very top of the map constructor, rather than next to
the map.
Never called at module load: that would run new Blob and URL.createObjectURL during import,
which fails under SSR and in jsdom, and would hand MapLibre a worker URL for applications that
import this package without ever creating a map. It does not save memory — the worker string is
resident from the moment this module is imported either way.
A consumer that installed its own worker URL is self-hosting on purpose — a strict
Content-Security-Policy without worker-src blob:, typically — and is left alone.
Under such a policy with no URL set, the failure is silent from the application’s side, and measured
rather than assumed: createObjectURL does not throw, new Worker does not throw synchronously,
and MapLibre fires no error event. The only signal is the browser’s own console message,
“Creating a worker from ‘blob:…’ violates the following Content Security Policy directive”, next
to a map that never loads. That string is repeated here so searching for it lands on this
explanation and on setMapLibreWorkerUrl.
Returns
void
See
setMapLibreWorkerUrl for the supported way to opt out.