feat(maplibre)!: require MapLibre GL JS v6

[harlan-zw]

🔗 Linked issue

Supersedes #857.

📚 Description

MapLibre v6 is ESM-only. dist/maplibre-gl.js and dist/maplibre-gl-csp.js are no longer published, so the pinned unpkg script tag 404s and nothing sets window.maplibregl. bundle: true can't work either: the ESM entry imports sibling chunks the bundle downloader never fetches. #857 on its own would have shipped a dead map.

The registry entry now runs in scriptMode: 'npm' and imports maplibre-gl, same shape as PostHog. The stylesheet comes from the package too, which kills the second pinned CDN URL and its integrity constant. stylesheetUrl still injects a custom link.

The worker took a while to track down. v6 builds the worker URL at runtime from import.meta.url rather than a static new URL() literal, so no bundler can rewrite it:

GET /_nuxt/node_modules/.cache/vite/client/deps/maplibre-gl-worker.mjs 404

The map got as far as fetching the style and sprites, then sat there with a hidden canvas because load never fired. MapLibre's install guide says every bundler consumer needs a one-time setWorkerUrl(), and ?worker&url rather than plain ?url, because the worker imports its sibling maplibre-gl-shared.mjs. Production now emits _nuxt/maplibre-gl-worker-<hash>.js.

Component code needed nothing. The v6 breaks we could have hit are all APIs we don't touch: styleimagemissing becoming notify-only, the map.transform removal, GeoJSONSource.setData losing its second argument.

⚠️ Breaking: apps using <ScriptMapLibreMap> need maplibre-gl@^6. It was already a documented install for types.

Loose end: ?worker&url is Vite syntax and I only exercised the Vite builder. Not sure what rspack/webpack do with it. Might want a builder check or at least a docs note.

🤖 AI disclosure: Harlan Agent Kit modified this description. My AI open-source policy.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
scripts-playground	Ready	Preview	Aug 18, 2026 4:42am

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/scripts@866

commit: 2067f91

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 361f436a-94c1-4cf7-8d50-890f07cd30b8

📥 Commits

Reviewing files that changed from the base of the PR and between c8375a7 and 2067f91.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (12)

• docs/content/scripts/maplibre/1.guides/3.performance-csp-and-accessibility.md
• docs/content/scripts/maplibre/index.md
• packages/script/package.json
• packages/script/src/registry-types.json
• packages/script/src/registry.ts
• packages/script/src/runtime/components/MapLibre/ScriptMapLibreMap.vue
• packages/script/src/runtime/maplibre-styles.ts
• packages/script/src/runtime/registry/maplibre.ts
• packages/script/src/runtime/registry/schemas.ts
• packages/script/src/script-meta.ts
• test/unit/maplibre-registry.test.ts
• test/unit/maplibre-styles.test.ts

Included review availability: Your plan includes up to 4 reviews per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

MapLibre integration now uses the MapLibre v6 ESM package instead of CDN scripts. The runtime loads the package, injects its stylesheet when enabled, configures bundled or custom workers through setWorkerUrl(), reuses existing globals, and handles aborted initialization. Registry metadata, schemas, package dependencies, and documentation reflect the new loading model. Unit tests cover package loading, styles, workers, deduplication, and abort handling.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk:⚪ Minimal · up to 2067f

This PR updates MapLibre loading, worker, stylesheet, and dependency handling for v6, with the supplied checks and playground verification passing. No actionable merge-blocking risk remains beyond normal review and checks.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR addresses the ESM migration, removed bundles, worker setup, API compatibility, and validation, but sets the peer range to ^6.0.0 instead of the issue's requested ^6.4.0.	Update the maplibre-gl peer dependency range from ^6.0.0 to the linked issue's requested ^6.4.0, then rerun dependency and compatibility validation.
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The documentation, registry, loader, stylesheet, worker, metadata, and tests all support the MapLibre v6 migration objectives.
Title check	✅ Passed	The title clearly states the primary change: requiring MapLibre GL JS v6.
Description check	✅ Passed	The description directly explains the MapLibre v6 migration, ESM loading changes, worker configuration, compatibility impact, and validation.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/maplibre-gl-v6

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}