‏MapLibre GL JS؛ نقشهٔ تعاملی با WebGL تو مرورگر

MapLibre GL JS یه کتابخونهٔ TypeScript هست که با WebGL نقشه‌های تعاملی رو مستقیم تو مرورگر رندر می‌کنه. ورودی‌ش وکتور تایل هست و ظاهر نقشه — لایه‌ها، رنگ‌ها و فونت‌ها — با یه سند style توصیف می‌شه که ساختارش رو MapLibre Style Spec تعیین می‌کنه. تو مستندات اومده که این کتابخونه بخشی از اکوسیستم MapLibre هست و همتای موبایلش برای اندروید و iOS اسمش MapLibre Native هست.

نکتهٔ مهم نسخهٔ ۶ اینه که فقط به شکل ES module منتشر می‌شه و فیلد module تو package.json به همون باندل ESM اشاره می‌کنه، پس باندلرها خودشون برش می‌دارن. در عوض باید آدرس worker رو دستی با setWorkerUrl معرفی کنی، و مستندات برای Vite، webpack ۵ به بالا، esbuild، Rollup و حالت بدون باندلر (CDN) دستور جداگانه داده.

تو Vite باید از کوئری ?worker&url استفاده کنی، نه ?url ساده:

import {Map, setWorkerUrl} from 'maplibre-gl';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';

setWorkerUrl(workerUrl);

دلیلش اینه که فایل worker داخل dist خودش maplibre-gl-shared.mjs رو import می‌کنه؛ ?url ساده تو بیلد پروداکشن فایل رو عیناً و بدون اون وابستگی بیرون می‌ده، worker سر همون اولین import شکست می‌خوره و هیچ وکتور تایلی لود نمی‌شه. ?worker&url فایل رو از خط لولهٔ worker خود Vite رد می‌کنه و یه چانک خودکفا می‌سازه. تو حالت dev هر دوش کار می‌کنه، برای همین این مشکل معمولاً تازه موقع بیلد خودش رو نشون می‌ده.

اگه بیلدت SSR داره (TanStack Start، Astro و مشابهش) و Vite روی سرور نسخهٔ CommonJS رو resolve می‌کنه، باید ssr: {noExternal: ['maplibre-gl']} رو هم به کانفیگ اضافه کنی. تو esbuild و Rollup به‌جای کوئری، خود فایل worker از node_modules به dist کپی می‌شه و بعد آدرسش با import.meta.url ساخته می‌شه. کسایی هم که دارن از نسخهٔ ۵ آپگرید می‌کنن، راهنمای مهاجرت v5 به v6 رو تو همون مستندات دارن.

نکات کلیدی:

• نقشهٔ برداری تعاملی رو با WebGL تو مرورگر رندر می‌کنه و ظاهرش با MapLibre Style Spec کنترل می‌شه.
• نسخهٔ ۶ فقط ESM هست و نقطهٔ ورودش فایل maplibre-gl.mjs هست.
• آدرس worker باید دستی با setWorkerUrl ست بشه.
• تو Vite حتماً ?worker&url، نه ?url ساده؛ وگرنه تایل‌ها تو پروداکشن لود نمی‌شن.
• برای SSR باید maplibre-gl رو تو ssr.noExternal بذاری.