Install for the web
MapCore's web build ships as npm packages containing the WebAssembly engine: MapCore.js,
MapCore.wasm and the symbology archives. They are published to the MapCore npm registry, so npm
needs to be told where to find them before anything will install.
The packages
Package names follow one rule:
@mapcore/wasm[-<slug>]-<arch>[-<variant>]
<arch> is 32 or 64. Choose 64-bit only if you need more than 4 GB of addressable heap; the
32-bit build is smaller and loads faster.
| Package | Contains |
|---|---|
@mapcore/wasm-32, @mapcore/wasm-64 | The full engine — rendering, layers, overlays |
@mapcore/wasm-calculations-32, @mapcore/wasm-calculations-64 | Calculations only, no rendering. Considerably smaller when you need spatial queries without a map |
Debugging builds are published one package per profiler, not as a single bundle:
| Package | Contains |
|---|---|
@mapcore/wasm-extras-memoryprofile-<arch> | Memory profiler |
@mapcore/wasm-extras-safeheap-<arch> | Heap-safety instrumentation |
@mapcore/wasm-extras-cpuprofile-<arch> | CPU profiler |
@mapcore/wasm-extras-stackinfo-<arch> | Stack reporting — crash stacks in the console log |
@mapcore/wasm-extras-threadprofile-<arch> | Thread profiler |
An optional variant suffix applies to all of the above:
| Suffix | Build |
|---|---|
| (none) | Release |
-d | Debug |
-dsa | Debug + AddressSanitizer |
-dsu | Debug + UndefinedBehaviorSanitizer |
1. Configure the @mapcore scope
This is a once-per-machine step, and skipping it is the most common cause of a failed install: the
packages are scoped, so npm must be told to resolve @mapcore from the MapCore registry rather
than from the public one.
Add both lines to your user .npmrc — ~/.npmrc, which on Windows is
C:\Users\<you>\.npmrc:
@mapcore:registry=https://mapcore.jfrog.io/artifactory/api/npm/c4i-mapcore-npm-release-local/
//mapcore.jfrog.io/artifactory/api/npm/c4i-mapcore-npm-release-local/:_authToken=<YOUR_TOKEN>
Use the user .npmrc, not one placed next to a tarball. npm only reads a project-level
.npmrc from the directory it considers the project root — found by walking up for a
package.json — so a folder containing just a .tgz is skipped, and the scope line in it is
silently ignored.
Authentication alone is not enough. Without the @mapcore:registry line, npm authenticates
correctly and then still looks for the package on the public registry, failing with
404 … '@mapcore/…' is not in this registry.
Getting your token
In the Artifactory web UI, click your name (top right) → Set Me Up, choose npm and the
c4i-mapcore-npm-release-local repository, then copy the _authToken value shown. With the JFrog
CLI, jf rt curl -XGET "/api/npm/auth" prints the same token.
Verify the scope is configured:
npm config get @mapcore:registry
2. Install the engine
npm install @mapcore/wasm-32
Or take the tarball directly, which is what an air-gapped or vendored install needs:
MapCore 12.5.0. Downloads are credential-gated by Artifactory itself — the first one opens its sign-in page.
Downloads are not available on this network. Ask your administrator where to obtain MapCore releases.
Rendering, layers, overlays - the full API
npm i @mapcore/wasm-32@12.5.0
Rendering, layers, overlays - the full API
npm i @mapcore/wasm-64@12.5.0
Spatial queries and geodesy with no renderer, and considerably smaller
npm i @mapcore/wasm-calculations-32@12.5.0
Spatial queries and geodesy with no renderer, and considerably smaller
npm i @mapcore/wasm-calculations-64@12.5.0
3. Load it
McStartMapCore() loads MapCore.wasm and returns a promise. Await it once, at start-up, before
touching anything else.
What it resolves to is not the API. The promise is Promise<void>; the API arrives as a global
namespace called MapCore, created as a side effect of the load. So this is the pattern:
- TypeScript
- JavaScript
await McStartMapCore();
// MapCore is now a global namespace: MapCore.IMcMapDevice, MapCore.IMcMapViewport, ...
const version = MapCore.IMcMapDevice.GetVersion();
await window.McStartMapCore();
const version = window.MapCore.IMcMapDevice.GetVersion();
Assigning the result — const MapCore = await McStartMapCore() — gives you the Emscripten module
rather than the API namespace, and every subsequent call fails on a name that looks correct.
If you are consuming the .mjs build, McStartMapCore is its default export:
- JS / TS
import McStartMapCore from '@mapcore/wasm-32/MapCore.mjs';
await McStartMapCore();
It also accepts a locateFile(filename, directory) callback, which is how you serve the .wasm
from a path the loader would not guess.
Next steps
- Quickstart — a map on screen.
- Running the web-tester — see the engine working before writing any code.