Web SDK quick start

Install the npm release

The browser SDK is published as @sqsmap/core on npm. This guide targets release 0.2.0, verified on 2026-10-15, and uses its existing MapView.create, addGeoJSON and event interfaces.

Use Node.js 22.12 or newer. This example pins SDK 0.2.0 and Vite 8.3.4. Commit the generated package-lock.json and use npm ci for reproducible installs. Check the declarations bundled with your package before using another version.

mkdir sqsmap-first-map
cd sqsmap-first-map
npm init -y
npm pkg set type=module
npm install --save-exact @sqsmap/core@0.2.0
npm install --save-dev --save-exact vite@8.3.4
npm pkg set scripts.dev="vite" scripts.build="vite build" scripts.preview="vite preview"

Create your first map

Create these four files in the project root. The example displays an inline demonstration polygon without a basemap account or network tiles. GeoJSON positions are WGS84 [longitude, latitude]. The first layer automatically frames its data.

index.html

<!doctype html>
<html lang="en">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>SqsMap</title></head>
<body><div id="map"></div><pre id="status" role="status"></pre><script type="module" src="/main.js"></script></body>
</html>

style.css

The container needs nonzero width and height. Creating a map without giving its container a height leaves it invisible.

html, body, #map { width: 100%; height: 100%; margin: 0; }
#status { position: fixed; left: 12px; bottom: 12px; max-width: calc(100% - 48px); margin: 0; padding: 8px 12px; background: #fff; color: #111; white-space: pre-wrap; pointer-events: none; }

main.js

Await MapView.create before using the map. The catch block handles creation failures, while the error listener reports subsequent data and resource errors. Release 0.2.0 accepts only zh or en for locale.

import { MapView } from '@sqsmap/core';
import './style.css';

const status = document.getElementById('status');
try {
  const view = await MapView.create(document.getElementById('map'), { locale: 'en' });
  view.on('error', ({ message }) => { status.textContent = message; });
  view.addGeoJSON('Example', {
    type: 'Feature', properties: {},
    geometry: { type: 'Polygon', coordinates: [[
      [116.38, 39.90], [116.42, 39.90], [116.42, 39.93],
      [116.38, 39.93], [116.38, 39.90]
    ]] }
  });
  status.textContent = `Backend: ${view.backend}; Worker: ${view.offscreen}`;
  view.on('click', ({ lngLat }) => { status.textContent = JSON.stringify(lngLat); });
  addEventListener('pagehide', () => view.destroy(), { once: true });
  if (import.meta.hot) import.meta.hot.dispose(() => view.destroy());
} catch (error) {
  status.textContent = error instanceof Error ? error.message : String(error);
}

vite.config.js

Exclude the SDK from development prebundling to preserve its relative Worker entry. Workers contain dynamic imports, so emit them as ES modules.

export default {
  optimizeDeps: { exclude: ['@sqsmap/core'] },
  worker: { format: 'es' },
};

Run and deploy

npm run dev

Open the local URL printed in the terminal. Expect a demonstration polygon, drag/zoom interaction and coordinates on click. The lower-left status shows the backend and actual Worker use. The SDK prefers WebGPU and attempts WebGL2 when unavailable. This example passed package declaration checks and a Vite production build; visual rendering and interaction still require acceptance in your target browser.

npm run build
npm run preview

Deploy the complete dist/, including HTML, JS, Worker and .wasm files. Use HTTP for local development and HTTPS in production, not file://. Serve .wasm as application/wasm. Missing assets should return 404 rather than your SPA HTML. For a subpath deployment, set Vite's base to the actual prefix, such as /maps/, then rebuild and upload.

Worker and WASM

• Worker rendering is attempted by default; unsupported browsers or failed default Worker startup can fall back to the main thread. Read view.offscreen for the actual result.
• To isolate main-thread behavior, use MapView.create(container, { worker: false, locale: 'en' }). WASM is still required.
• Vite processes the package's Worker, binding JS and WASM in this example. No manual copying or files from the website's development snapshot are needed.
• Set wasmUrl only when hosting the matching WASM yourself, for example on a CDN. Do not mix package versions. Cross-origin hosts must allow resource access.
• A custom createWorker is an advanced integration. In 0.2.0 it makes Worker startup strict: failure rejects instead of falling back.

Call destroy() when disposing of the page. In Vue/React, create after the container mounts and destroy on component unmount. The example also disposes of old maps during Vite hot updates.

Troubleshooting

Release versus development snapshot

The browser API reference and website distribution guide currently describe development snapshot 0.3.0-dev.8fc51305. Do not apply its addSource, addLayer or flush examples directly to npm 0.2.0. This page uses the release's convenience GeoJSON interface.

For development shared-camera, source and style APIs, obtain all matching resources from the distribution guide. For the npm release, use dist/index.d.ts and its relative declarations in the installed package. npm ls @sqsmap/core shows your installed version; npm view @sqsmap/core version queries the registry's latest version. Rebuild and validate after upgrading.

Keep the package's LICENSE and THIRD_PARTY_NOTICES.txt, including the embedded-font notice, when distributing your application. Map-data and basemap attribution requirements apply separately.