@trapar-waves/react-three-maplibre 1.1.22 → 1.2.0

package/README.md

@@ -25,6 +25,22 @@
 - **Map Interactivity:** Implements `react-map-gl` for interactive map controls and client-side navigation in geospatial contexts.
 - **AntV Enhancements:** Incorporates `@antv/l7-maps` for additional map layering capabilities and visualization tools.
 
+## GitHub Pages
+
+Pushing a version tag matching `v*` runs [`.github/workflows/pages.yml`](./.github/workflows/pages.yml), which builds with `BASE_PATH=/<repository-name>/`, copies `dist/index.html` to `dist/404.html` for SPA routing, and deploys to GitHub Pages. In the repository **Settings → Pages**, set **Source** to **GitHub Actions** once.
+
+The demo map uses [Carto Basemaps](https://carto.com/basemaps/) public MapLibre GL styles (**no API key** required for local builds or GitHub Pages).
+
+```bash
+BASE_PATH=/react-three-maplibre/ pnpm run build && pnpm preview
+```
+
+PowerShell:
+
+```powershell
+$env:BASE_PATH="/react-three-maplibre/"; pnpm run build; pnpm preview
+```
+
 ## 💻 Tech Stack
 
 - **Framework/Library:** React
@@ -142,7 +158,8 @@ const latLon = {
   latitude: 31.215175,
   longitude: 121.417463,
 };
-const MAPTILER_KEY = import.meta.env.PUBLIC_MAPTILER_KEY;
+const MAP_STYLE_URL
+  = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
 
 function App() {
   const ref = useRef<HTMLDivElement>(null!);
@@ -187,7 +204,7 @@ function App() {
           zoom: 11,
           pitch: 64.88,
         }}
-        mapStyle={`https://api.maptiler.com/maps/streets/style.json?key=${MAPTILER_KEY}`}
+        mapStyle={MAP_STYLE_URL}
         onLoad={initL7}
       >
         <Stats className="stats" parent={ref} />
@@ -211,20 +228,15 @@ export default App;
 ```
 
 This example demonstrates:
+
 - Creating a MapLibre GL map with `react-map-gl`
 - Integrating AntV L7 for geospatial data visualization
 - Using React Three Fiber and Drei for 3D rendering
 - Positioning 3D objects relative to the map using `react-three-map`
 
-### Environment Variables
-
-To use map services like MapTiler, you'll need to set up environment variables. Create a `.env` file in your project root:
-
-```
-PUBLIC_MAPTILER_KEY=your_maptiler_api_key_here
-```
+### Map basemap
 
-Make sure to add `.env` to your `.gitignore` to keep your keys secure.
+The template ships with a key-free Carto GL style (`MAP_STYLE_URL` in `src/App.tsx`). To switch providers (e.g. MapTiler), point `mapStyle` at your style JSON and manage API keys via `.env` / CI secrets yourself.
 
 ## 🤝 Contributing
 

package/environments/.env

@@ -1 +1,2 @@
-PUBLIC_MAPTILER_KEY="set your key"
+# 默认底图为 Carto Basemaps（MapLibre GL），无需在此填写地图 API Key。
+# 若接入 MapTiler 等需鉴权的服务，请自行在代码中配置 mapStyle 并在此添加对应变量。

package/eslint.config.js

@@ -13,4 +13,10 @@ export default antfu({
   formatters: {
     markdown: "prettier",
   },
+}, {
+  name: "trapar/pnpm-workspace-yaml-trust-policy",
+  files: ["pnpm-workspace.yaml"],
+  rules: {
+    "pnpm/yaml-enforce-settings": "off",
+  },
 });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@trapar-waves/react-three-maplibre",
   "type": "module",
-  "version": "1.1.22",
-  "packageManager": "pnpm@10.28.2",
+  "version": "1.2.0",
+  "packageManager": "pnpm@10.33.2",
   "description": "A React library integrating Three.js and MapLibre for 3D map visualization",
   "author": {
     "email": "admin@rikka.cc",
@@ -33,42 +33,47 @@
   "scripts": {
     "dev": "rsbuild dev --open",
     "build": "rsbuild build",
+    "build:rsdoctor": "cross-env RSDOCTOR=true rsbuild build",
     "preview": "rsbuild preview",
     "lint": "eslint . --cache --max-warnings=0 --no-warn-ignored",
     "postinstall": "husky"
   },
   "dependencies": {
-    "@antv/l7": "^2.23.2",
-    "@antv/l7-maps": "^2.23.2",
+    "@antv/l7": "^2.25.4",
+    "@antv/l7-maps": "^2.25.4",
     "@react-three/drei": "^10.7.7",
-    "@react-three/fiber": "^9.5.0",
-    "maplibre-gl": "^5.17.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "react-map-gl": "^8.1.0",
+    "@react-three/fiber": "^9.6.0",
+    "maplibre-gl": "^5.24.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-map-gl": "^8.1.1",
     "react-three-map": "^1.0.0",
-    "three": "^0.182.0",
+    "three": "^0.184.0",
     "three-stdlib": "^2.36.1"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^7.2.0",
-    "@eslint-react/eslint-plugin": "^2.9.4",
-    "@iconify/json": "^2.2.435",
-    "@iconify/tailwind4": "^1.2.1",
-    "@rsbuild/core": "^1.7.3",
-    "@rsbuild/plugin-react": "^1.4.5",
-    "@tailwindcss/postcss": "^4.1.18",
-    "@types/react": "^19.2.10",
+    "@antfu/eslint-config": "^8.2.0",
+    "@eslint-react/eslint-plugin": "^3.0.0",
+    "@iconify/json": "^2.2.467",
+    "@iconify/tailwind4": "^1.2.3",
+    "@rsbuild/core": "^2.0.1",
+    "@rsbuild/plugin-less": "^1.6.2",
+    "@rsbuild/plugin-react": "^2.0.0",
+    "@rsdoctor/rspack-plugin": "^1.5.9",
+    "@tailwindcss/postcss": "^4.2.4",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@types/three": "^0.182.0",
-    "eslint": "^9.39.2",
-    "eslint-plugin-format": "^1.3.1",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.5.0",
+    "@types/three": "^0.184.0",
+    "cross-env": "^10.1.0",
+    "eslint": "^10.2.1",
+    "eslint-plugin-format": "^2.0.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
     "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
-    "mapbox-gl": "^3.18.1",
-    "tailwindcss": "^4.1.18",
-    "typescript": "^5.9.3"
+    "lint-staged": "^16.4.0",
+    "mapbox-gl": "^3.22.0",
+    "tailwindcss": "^4.2.4",
+    "typescript": "^6.0.3",
+    "unplugin-turbo-console": "^2.3.1"
   }
 }

package/pnpm-workspace.yaml

@@ -1,3 +1,7 @@
+shellEmulator: true
+
+trustPolicy: off
+
 onlyBuiltDependencies:
   - "@tailwindcss/oxide"
   - core-js

package/readme/README-CN.md

@@ -142,7 +142,8 @@ const latLon = {
   latitude: 31.215175,
   longitude: 121.417463,
 };
-const MAPTILER_KEY = import.meta.env.PUBLIC_MAPTILER_KEY;
+const MAP_STYLE_URL
+  = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
 
 function App() {
   const ref = useRef<HTMLDivElement>(null!);
@@ -187,7 +188,7 @@ function App() {
           zoom: 11,
           pitch: 64.88,
         }}
-        mapStyle={`https://api.maptiler.com/maps/streets/style.json?key=${MAPTILER_KEY}`}
+        mapStyle={MAP_STYLE_URL}
         onLoad={initL7}
       >
         <Stats className="stats" parent={ref} />
@@ -211,20 +212,15 @@ export default App;
 ```
 
 这个示例演示了：
+
 - 使用 `react-map-gl` 创建 MapLibre GL 地图
 - 集成 AntV L7 进行地理空间数据可视化
 - 使用 React Three Fiber 和 Drei 进行 3D 渲染
 - 使用 `react-three-map` 将 3D 对象相对于地图进行定位
 
-### 环境变量
-
-要使用 MapTiler 等地图服务，您需要设置环境变量。在项目根目录创建一个 `.env` 文件：
-
-```
-PUBLIC_MAPTILER_KEY=your_maptiler_api_key_here
-```
+### 地图底图
 
-确保将 `.env` 添加到 `.gitignore` 中以保证密钥安全。
+模板默认使用无需 API Key 的 Carto GL 样式（见 `src/App.tsx` 中的 `MAP_STYLE_URL`）。若改用 MapTiler 等需鉴权的服务，请自行设置 `mapStyle` 并通过 `.env` / CI 密钥管理凭据。
 
 ## 🤝 贡献指南
 

package/readme/README-JP.md

@@ -142,7 +142,8 @@ const latLon = {
   latitude: 31.215175,
   longitude: 121.417463,
 };
-const MAPTILER_KEY = import.meta.env.PUBLIC_MAPTILER_KEY;
+const MAP_STYLE_URL
+  = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
 
 function App() {
   const ref = useRef<HTMLDivElement>(null!);
@@ -187,7 +188,7 @@ function App() {
           zoom: 11,
           pitch: 64.88,
         }}
-        mapStyle={`https://api.maptiler.com/maps/streets/style.json?key=${MAPTILER_KEY}`}
+        mapStyle={MAP_STYLE_URL}
         onLoad={initL7}
       >
         <Stats className="stats" parent={ref} />
@@ -211,20 +212,15 @@ export default App;
 ```
 
 この例では以下を示しています：
+
 - `react-map-gl` を使用して MapLibre GL マップを作成する
 - 地理空間データの可視化のために AntV L7 を統合する
 - 3D レンダリングのために React Three Fiber と Drei を使用する
 - `react-three-map` を使用して 3D オブジェクトをマップに対して配置する
 
-### 環境変数
-
-MapTiler などのマップサービスを使用するには、環境変数を設定する必要があります。プロジェクトのルートに `.env` ファイルを作成します：
-
-```
-PUBLIC_MAPTILER_KEY=your_maptiler_api_key_here
-```
+### 地図のベースマップ
 
-キーを安全に保つために、`.env` を `.gitignore` に追加してください。
+テンプレートは API キー不要の Carto GL スタイル（`src/App.tsx` の `MAP_STYLE_URL`）を既定とします。MapTiler など別プロバイダへ切り替える場合は `mapStyle` を変更し、`.env` / CI で鍵を管理してください。
 
 ## 🤝 コントリビューション
 

package/readme/README-RU.md

@@ -142,7 +142,8 @@ const latLon = {
   latitude: 31.215175,
   longitude: 121.417463,
 };
-const MAPTILER_KEY = import.meta.env.PUBLIC_MAPTILER_KEY;
+const MAP_STYLE_URL
+  = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
 
 function App() {
   const ref = useRef<HTMLDivElement>(null!);
@@ -187,7 +188,7 @@ function App() {
           zoom: 11,
           pitch: 64.88,
         }}
-        mapStyle={`https://api.maptiler.com/maps/streets/style.json?key=${MAPTILER_KEY}`}
+        mapStyle={MAP_STYLE_URL}
         onLoad={initL7}
       >
         <Stats className="stats" parent={ref} />
@@ -211,20 +212,15 @@ export default App;
 ```
 
 Этот пример демонстрирует:
+
 - Создание карты MapLibre GL с помощью `react-map-gl`
 - Интеграция AntV L7 для визуализации геопространственных данных
 - Использование React Three Fiber и Drei для 3D-рендеринга
 - Позиционирование 3D-объектов относительно карты с помощью `react-three-map`
 
-### Переменные окружения
-
-Для использования сервисов карт, таких как MapTiler, вам нужно настроить переменные окружения. Создайте файл `.env` в корне вашего проекта:
-
-```
-PUBLIC_MAPTILER_KEY=your_maptiler_api_key_here
-```
+### Подложка карты
 
-Обязательно добавьте `.env` в ваш `.gitignore`, чтобы ваши ключи оставались в безопасности.
+В шаблоне по умолчанию используется стиль Carto GL без API-ключа (`MAP_STYLE_URL` в `src/App.tsx`). Для другого провайдера (например, MapTiler) задайте `mapStyle` и храните ключи в `.env` / CI.
 
 ## 🤝 Участие в разработке
 

package/rsbuild.config.ts

@@ -1,11 +1,39 @@
+import process from "node:process";
 import { defineConfig, loadEnv } from "@rsbuild/core";
+import { pluginLess } from "@rsbuild/plugin-less";
 import { pluginReact } from "@rsbuild/plugin-react";
+import { RsdoctorRspackPlugin } from "@rsdoctor/rspack-plugin";
 import tailwind from "@tailwindcss/postcss";
+import TurboConsole from "unplugin-turbo-console/rspack";
 
 const { publicVars } = loadEnv({ cwd: "./environments" });
 
+function normalizeBasePath(): string {
+  const raw = process.env.BASE_PATH?.trim();
+  if (!raw || raw === "/") {
+    return "/";
+  }
+  const prefixed = raw.startsWith("/") ? raw : `/${raw}`;
+  return prefixed.endsWith("/") ? prefixed : `${prefixed}/`;
+}
+
+const basePath = normalizeBasePath();
+const useSubpath = basePath !== "/";
+
+const enableRsdoctor = Boolean(process.env.RSDOCTOR);
+const enableTurboConsole = process.env.NODE_ENV === "development";
+
 export default defineConfig({
-  plugins: [pluginReact()],
+  ...(useSubpath
+    ? {
+        server: { base: basePath },
+        output: { assetPrefix: basePath },
+      }
+    : {}),
+  performance: {
+    ...(enableRsdoctor ? { buildCache: false } : {}),
+  },
+  plugins: [pluginReact(), pluginLess()],
   source: {
     define: publicVars,
   },
@@ -15,5 +43,24 @@ export default defineConfig({
         plugins: [tailwind],
       },
     },
+    rspack: [
+      (config) => {
+        if (enableTurboConsole) {
+          config.plugins.push(TurboConsole());
+        }
+        if (enableRsdoctor) {
+          config.plugins.push(
+            new RsdoctorRspackPlugin({
+              output: {
+                mode: "brief",
+                options: {
+                  type: ["json"],
+                },
+              },
+            }),
+          );
+        }
+      },
+    ],
   },
 });

package/src/App.tsx

@@ -23,7 +23,53 @@ const latLon = {
   latitude: 31.215175,
   longitude: 121.417463,
 };
-const MAPTILER_KEY = import.meta.env.PUBLIC_MAPTILER_KEY;
+
+/** Carto 托管的 MapLibre GL 矢量底图，无需 API Key（使用请遵守 https://carto.com/basemaps/ 条款）。 */
+const MAP_STYLE_URL = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+
+function publicAssetUrl(filename: string): string {
+  const base = (import.meta.env.BASE_URL ?? "/").replace(/\/$/, "");
+  const path = filename.startsWith("/") ? filename : `/${filename}`;
+  return `${base || ""}${path}`.replaceAll("//", "/");
+}
+
+const HOMEPAGE = "https://github.com/Trapar-waves/react-three-maplibre";
+const LOGOS_SET_URL = "https://icon-sets.iconify.design/logos/";
+
+interface TechPill {
+  id: string;
+  label: string;
+  iconClass: string;
+}
+
+const techStack: TechPill[] = [
+  { id: "react", label: "React 19", iconClass: "icon-[logos--react]" },
+  { id: "ts", label: "TypeScript", iconClass: "icon-[logos--typescript-icon]" },
+  { id: "tailwind", label: "Tailwind 4", iconClass: "icon-[logos--tailwindcss-icon]" },
+  { id: "rsbuild", label: "Rsbuild", iconClass: "icon-[material-icon-theme--rstack]" },
+  { id: "maplibre", label: "MapLibre · react-map-gl", iconClass: "icon-[simple-icons--maplibre]" },
+  { id: "l7", label: "AntV L7", iconClass: "icon-[logos--markdown]" },
+  { id: "r3f", label: "R3F · drei · three-stdlib", iconClass: "icon-[logos--threejs]" },
+  { id: "rtmap", label: "react-three-map", iconClass: "icon-[logos--markdown]" },
+  { id: "eslint", label: "ESLint", iconClass: "icon-[logos--eslint]" },
+  { id: "pnpm", label: "pnpm", iconClass: "icon-[logos--pnpm]" },
+  { id: "github", label: "GitHub Actions", iconClass: "icon-[logos--github-icon]" },
+];
+
+const readmeFeatures: string[] = [
+  "MapLibre 与 AntV L7 组合，自定义地图与点层渲染。",
+  "@react-three/fiber、drei 将 Three.js 以声明式接入 React。",
+  "react-three-map 与 MapLibre 视口同步；Canvas 使用 overlay 模式使 Three 叠在 L7 点层之上。",
+  "Tailwind CSS 快速布局与面板样式。",
+  "TypeScript 覆盖地图与场景相关类型。",
+  "Rsbuild 开发与生产构建。",
+  "react-map-gl 提供交互与导航体验。",
+  "three-stdlib 与 drei 复用常用几何与调试组件。",
+  "GitHub Pages 支持 BASE_PATH 与 404.html SPA 部署。",
+  "默认 Carto Basemaps GL 样式，本地与 CI 均无需地图 API Key。",
+];
+
+const readmeTechNote = "演示使用 @react-three/drei 的 Stats；生产可按需移除。若需其他底图，可在 App.tsx 中替换 MAP_STYLE_URL 并自行处理鉴权。";
 
 function App() {
   const ref = useRef<HTMLDivElement>(null!);
@@ -37,8 +83,8 @@ function App() {
         }),
       });
       scene.on("loaded", () => {
-        fetch("/BElVQFEFvpAKzddxFZxJ.txt")
-          .then(res => res.text())
+        fetch(publicAssetUrl("BElVQFEFvpAKzddxFZxJ.txt"))
+          .then(res => (res.ok ? res.text() : Promise.reject(new Error(String(res.status)))))
           .then((data) => {
             const pointLayer = new PointLayer({
               blend: "additive",
@@ -54,12 +100,80 @@ function App() {
               .color("#080298");
 
             scene.addLayer(pointLayer);
-          });
+          })
+          .catch(() => {});
       });
     }
   }
   return (
     <div className="h-screen w-screen relative overflow-hidden" ref={ref}>
+      <aside
+        className="pointer-events-none absolute left-4 top-4 z-10 max-w-sm motion-safe:transition motion-safe:duration-200"
+        aria-label="模板说明"
+      >
+        <div
+          className="pointer-events-auto max-h-[min(70vh,560px)] overflow-y-auto overscroll-contain rounded-xl border border-white/15 bg-slate-950/80 p-4 text-sm text-slate-100 shadow-xl backdrop-blur-md"
+        >
+          <p className="font-semibold text-white">react-three-maplibre</p>
+          <p className="mt-2 leading-relaxed text-slate-300">
+            MapLibre 与 react-three-map 同屏；L7 点层叠加 CSV，Three 方体经
+            {" "}
+            <code className="rounded bg-slate-800 px-1">overlay</code>
+            {" "}
+            画布叠在 L7 之上。底图为 Carto 公开 GL 样式，无需地图服务 API Key。技术图标见
+            {" "}
+            <a
+              href={LOGOS_SET_URL}
+              className="font-medium text-sky-300 underline decoration-sky-700 underline-offset-2 hover:text-sky-200"
+              target="_blank"
+              rel="noreferrer"
+            >
+              Iconify logos
+            </a>
+            。
+          </p>
+          <p className="mt-3 text-xs font-medium uppercase tracking-wide text-slate-500">
+            技术栈
+          </p>
+          <div className="mt-2 flex flex-wrap gap-2">
+            {techStack.map(item => (
+              <span
+                key={item.id}
+                className="inline-flex items-center gap-1.5 rounded-lg border border-white/10 bg-slate-900/80 px-2 py-1 text-xs text-slate-200"
+              >
+                <span className={`${item.iconClass} text-base text-sky-300`} aria-hidden />
+                {item.label}
+              </span>
+            ))}
+          </div>
+          <p className="mt-4 text-xs font-medium uppercase tracking-wide text-slate-500">
+            README 摘要
+          </p>
+          <ul className="mt-2 list-disc space-y-1 pl-4 text-slate-400">
+            {readmeFeatures.map(line => (
+              <li key={line}>{line}</li>
+            ))}
+          </ul>
+          <p className="mt-3 text-xs italic leading-relaxed text-slate-500">
+            {readmeTechNote}
+          </p>
+          <p className="mt-3 text-xs leading-relaxed text-slate-500">
+            品牌图标来自
+            {" "}
+            <a href={LOGOS_SET_URL} className="text-sky-400 underline hover:text-sky-300" target="_blank" rel="noreferrer">SVG Logos</a>
+            {" "}
+            （CC0）。
+          </p>
+          <a
+            href={HOMEPAGE}
+            className="mt-3 inline-flex min-h-11 w-full items-center justify-center rounded-lg bg-sky-500 px-4 py-2 text-sm font-semibold text-slate-950 hover:bg-sky-400 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white"
+            target="_blank"
+            rel="noreferrer"
+          >
+            查看仓库
+          </a>
+        </div>
+      </aside>
       <Map
         id="map"
         ref={mapRef}
@@ -68,12 +182,16 @@ function App() {
           zoom: 11,
           pitch: 64.88,
         }}
-        mapStyle={`https://api.maptiler.com/maps/streets/style.json?key=${MAPTILER_KEY}`}
+        mapStyle={MAP_STYLE_URL}
         onLoad={initL7}
       >
         <Stats className="stats" parent={ref} />
 
-        <Canvas {...latLon}>
+        <Canvas
+          overlay
+          id="trapar-r3f-overlay"
+          {...latLon}
+        >
           <hemisphereLight
             args={["#ffffff", "#60666C"]}
             position={[1, 4.5, 3]}

package/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2020",
     "jsx": "react-jsx",
-    "lib": ["DOM", "ES2020"],
+    "lib": ["DOM", "ESNext"],
     "useDefineForClassFields": true,
 
     /* modules */