Skip to main content

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.

PackageContains
@mapcore/wasm-32, @mapcore/wasm-64The full engine — rendering, layers, overlays
@mapcore/wasm-calculations-32, @mapcore/wasm-calculations-64Calculations 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:

PackageContains
@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:

SuffixBuild
(none)Release
-dDebug
-dsaDebug + AddressSanitizer
-dsuDebug + 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>
warning

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.

MapCore engine · 32-bit32

Rendering, layers, overlays - the full API

npm i @mapcore/wasm-32@12.5.0
MapCore engine · 64-bit64

Rendering, layers, overlays - the full API

npm i @mapcore/wasm-64@12.5.0
Calculations only · 32-bit32

Spatial queries and geodesy with no renderer, and considerably smaller

npm i @mapcore/wasm-calculations-32@12.5.0
Calculations only · 64-bit64

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:

await McStartMapCore();
// MapCore is now a global namespace: MapCore.IMcMapDevice, MapCore.IMcMapViewport, ...
const version = 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:

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​

Verified against MapCore 12.5.0

Written from packaging/npm/wasm_pkg.py