[BUG] fix maplibre-gl v6 map embeds not rendering

[John McCall (lowlydba)]

Fixes #468.

Branch deploy for #465 (the maplibre-gl 5→6 bump) has a blank map: staging.overturemaps.org/docs/pr/465-no-autogen/guides/buildings shows nothing past the background fill, vs. the working live buildings guide.

Root cause

maplibre-gl v6 ships ESM-only. Per the v5→v6 migration guide, bundler consumers must call setWorkerUrl() explicitly, since import.meta.url no longer resolves the worker chunk from inside a bundle.

The worker file (maplibre-gl-worker.mjs) also statically imports a sibling chunk, maplibre-gl-shared.mjs. Rspack's asset handling for new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url) only emits the referenced file, not that sibling, so maplibre-gl-shared.mjs 404s. It 404s silently too: the dev server's SPA fallback serves index.html for the missing path with a text/html content type instead of a real 404, so there's nothing in the console to point at. The worker's module import then fails with an opaque error, the map never fires load/idle, and nothing past the background layer paints.

Fix

Copy both worker files verbatim into static/maplibre/ via scripts/copy-maplibre-worker.mjs, and point setWorkerUrl() at that static path with useBaseUrl() so it still resolves correctly on PR preview deploys with a non-root baseUrl.

That copy step is chained directly into the start/build npm scripts rather than a prestart/prebuild hook. Our CI uses lowlydba/sustainable-npm with ignore-scripts defaulting to true as of v3.0.0, which skips npm's automatic pre/post lifecycle hooks while still running whatever's explicitly invoked by npm run. That's why the staging preview for this PR was still broken even though the fix worked in every local test, prebuild never ran, so static/maplibre/ stayed empty.

Testing

Reproduced the blank map locally against #465's dependency bump (confirmed via WebGL readPixels: canvas painted only the background color, map.isStyleLoaded() never went true) before the fix, then confirmed loaded()/isStyleLoaded() both flip to true and buildings/roads render after it, in both docusaurus start and a docusaurus build + docusaurus serve.

Also set ignore-scripts=true locally to match CI, ran npm run build, and confirmed build/maplibre/*.mjs still got populated and the served build rendered correctly, reproducing and fixing the actual staging failure mode.

npm run lint and npm run build both pass.

[github-actions]

🗺️ OMF Docs previews are live!

🆕 Auto-gen schema site (beta)	https://staging.overturemaps.org/docs/pr/467/index.html
🗂️ Auto-gen schema ref	main@7cd540d
🌍 Repo schema site	https://staging.overturemaps.org/docs/pr/467-no-autogen/index.html
🕐 Updated	Aug 05, 2026 16:49 UTC
📝 Commit	de3aa1a

Auto-gen schema site is now available. This is an early preview of a future workflow where we will automatically generate and publish reference docs for the Overture Maps Format schema.

The auto-gen schema site may contain incomplete or inaccurate information as we are still refining the generation process, so please compare against the repo schema site and refer to the official Overture documentation for authoritative information.

Note

♻️ This preview updates automatically with each push to this PR.

[github-actions]

Super-linter summary

Language	Validation result
JAVASCRIPT_ES	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Fail ❌
SQLFLUFF	Pass ✅

Super-linter detected linting errors

For more information, see the GitHub Actions workflow run

Powered by Super-linter

NATURAL_LANGUAGE

/github/workspace/docs/schema/reference/base/land_use.md
  53:74  ✓ error  Incorrect term: “Key/value”, use “Key-value” instead  terminology

/github/workspace/docs/schema/reference/base/infrastructure.md
  48:74  ✓ error  Incorrect term: “Key/value”, use “Key-value” instead  terminology

/github/workspace/docs/schema/reference/base/land.md
  58:74  ✓ error  Incorrect term: “Key/value”, use “Key-value” instead  terminology

/github/workspace/docs/schema/reference/base/types/source_tags.md
  3:1  ✓ error  Incorrect term: “Key/value”, use “Key-value” instead  terminology

/github/workspace/docs/schema/reference/base/water.md
  69:74  ✓ error  Incorrect term: “Key/value”, use “Key-value” instead  terminology

/github/workspace/docs/schema/reference/places/place.md
  40:89  ✓ error  Incorrect term: “websites”, use “sites” instead  terminology

/github/workspace/docs/schema/reference/system/snake_case_string.md
  3:28  ✓ error  Incorrect term: “snake case”, use “snake_case” instead  terminology
  9:38  ✓ error  Incorrect term: “snake case”, use “snake_case” instead  terminology

/github/workspace/docs/schema/reference/system/ref/id.md
  1:3  ✓ error  Incorrect term: “Id”, use “ID” instead  terminology

✖ 9 problems (9 errors, 0 warnings, 0 infos)
✓ 9 fixable problems.
Try to run: $ textlint --fix [file]

[John McCall (lowlydba)]

Confirming that the map visualization for buildings is working properly now:

[John McCall (lowlydba)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Pull request overview

This PR fixes MapLibre GL v6 embeds rendering blank by explicitly setting a statically served worker URL and ensuring both required worker chunks are available at runtime in Docusaurus builds (including CI environments that skip npm lifecycle hooks).

Changes:

• Update map components to use ESM imports, compute a baseUrl-aware worker URL, and call maplibregl.setWorkerUrl().
• Add a script to copy maplibre-gl-worker.mjs and maplibre-gl-shared.mjs into static/maplibre/ for reliable serving.
• Chain the copy step into npm start/npm run build, bump maplibre-gl to ^6.0.0, and ignore the generated static directory in ESLint/git.

Reviewed changes

Copilot reviewed 5 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/components/map.js	Switch to ESM MapLibre imports and set an explicit worker URL via useBaseUrl() before map creation.
src/components/buildings-map.js	Same worker URL + ESM import changes for the global buildings map embed.
scripts/copy-maplibre-worker.mjs	New script to copy both worker-related .mjs files into static/maplibre/.
package.json	Add copy-maplibre-worker script; chain it into start and build; bump maplibre-gl to v6.
package-lock.json	Lockfile updates for the MapLibre v6 dependency tree.
eslint.config.mjs	Ignore generated static/maplibre/ directory for linting.
.gitignore	Ignore generated static/maplibre/ directory in git.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot resolve the merge conflicts in this pull request

Merge conflicts resolved in 07da9b9. Also chained copy-maplibre-worker into the deploy script for consistency with start/build.