Installing MeshLib SDK for JavaScript

MeshLib is available for JavaScript as the geometry library compiled to WebAssembly. It runs both in Node.js and in the browser, and is published to npm as two packages that share an identical API: @meshinspector/meshlib (single-threaded) and @meshinspector/meshlib-mt (multi-threaded). To see it running in the browser before you install anything, open demo.meshlib.io — the live demo is built on the multi-threaded package.

Prerequisites

Before installing MeshLib SDK for JavaScript, ensure you have the following:

Runtime

MeshLib runs in Node.js or in a modern browser.

@meshinspector/meshlib (single-threaded) requires Node.js 18 or newer.
@meshinspector/meshlib-mt (multi-threaded) requires Node.js 21 or newer.

Download Node.js.

Code Editor

You can use any JavaScript- or TypeScript-compatible editor, such as Visual Studio Code, WebStorm, or any IDE you prefer.

Download Visual Studio Code

Choosing a Package: Single-Threaded or Multi-Threaded

MeshLib ships in two flavors with an identical API:

@meshinspector/meshlib: the single-threaded build. The simplest choice, and the right one for most applications.
@meshinspector/meshlib-mt: the multi-threaded build. It uses worker threads to parallelize geometry operations for higher throughput, and requires Node.js 21 or newer.

The examples below use @meshinspector/meshlib. To use the multi-threaded build instead, install @meshinspector/meshlib-mt and change the import specifier; in Node.js nothing else changes. In the browser the page must additionally be cross-origin isolated.

Installation

Installation via npm

Install the package from npm and enable ES module support in your project:

npm install @meshinspector/meshlib

npm pkg set type=module

Use from CDN

In the browser you can skip npm entirely and import the module directly:

// latest release
import createMeshLib from 'https://js.meshlib.io/meshlib/meshlib.mjs';
 
// or pin a release
import createMeshLib from 'https://js.meshlib.io/meshlib@v1.2.3.456/meshlib.mjs';

Multi-Threaded Build

The multi-threaded build cannot be imported straight from the CDN, because the browser refuses to run a worker script from another origin, so pass the fetched module to the factory as a Blob and its worker pool starts from a same-origin blob: URL:

const url = 'https://js.meshlib.io/meshlib-mt/meshlib-mt.mjs';
 
const { default: createMeshLib } = await import( url );
const blob = new Blob( [ await ( await fetch( url ) ).text() ], { type: 'text/javascript' } );
 
const ml = await createMeshLib( { mainScriptUrlOrBlob: blob } );

In the browser the multi-threaded build additionally requires the page to be cross-origin isolated.

Bundlers

Vite 8 and webpack 5 resolve meshlib.wasm from the module and emit it as an asset, so a plain import needs no configuration. For other bundlers, such as esbuild or Rollup, import the wasm as an asset URL and hand it to the loader via locateFile:

import createMeshLib from '@meshinspector/meshlib';
import wasmUrl from '@meshinspector/meshlib/meshlib.wasm';
 
const ml = await createMeshLib( { locateFile: () => wasmUrl } );

The bundler must treat .wasm files as static assets, so that the import resolves to the URL of the emitted file; the option is usually called an asset or file loader. For example:

esbuild: pass --loader:.wasm=file
Rollup: add @rollup/plugin-url with include: /\.wasm$/
Parcel: use the url: scheme on the import specifier: ‘import wasmUrl from 'url:@meshinspector/meshlib/meshlib.wasm’;`

Payload Size

MeshLib is a WebAssembly build of the full geometry library, so a browser downloads roughly 11 MB of wasm, about 3 MB gzipped over the wire, before the first geometry call. @meshinspector/meshlib-mt is the same order of magnitude.

Two consequences for a browser application:

The .wasm is a sidecar file fetched as a second request, separate from the .mjs module. Serve it as application/wasm with compression enabled, or the download is several times larger than it needs to be.
npm install unpacks about 21 MB, because the browser and the Node.js wasm ship side by side in one package. Only one of them ever reaches the browser; the rest is bundler input, not payload.

If the geometry is not needed on first paint, load the module lazily instead of at the top level, so the wasm download does not block startup:

// load MeshLib only when the user actually needs geometry
const { default: createMeshLib } = await import('@meshinspector/meshlib');
const ml = await createMeshLib();

Cross-Origin Isolation for the Multi-Threaded Build in the Browser

This section applies to browsers only. In Node.js the multi-threaded build needs no headers, flags, or extra configuration.

The multi-threaded package @meshinspector/meshlib-mt relies on SharedArrayBuffer, which browsers only enable on cross-origin isolated pages. The server that serves the page loading the module must send these headers:

Cross-Origin-Opener-Policy: same-origin

Cross-Origin-Embedder-Policy: require-corp

Without them crossOriginIsolated is false, SharedArrayBuffer is unavailable, and createMeshLib() never resolves.

For a Vite dev server, set the headers in vite.config.js (whatever hosts the production build must send them too; vite-plugin-cross-origin-isolation can stamp them for vite preview):

// vite.config.js
export default {
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
};

Where you cannot set response headers at all — GitHub Pages and similar static hosting — the usual workaround is a coi-serviceworker-style shim: a service worker that re-serves the page with the two headers and reloads it once. MeshLib's own interactive demo is hosted exactly this way.

So on a page that is not cross-origin isolated you have three options: send the headers, install the service-worker shim, or use the single-threaded @meshinspector/meshlib package, which has no such requirement.

Getting Started: Your First Example

The default export is an async factory. Await it once to get the module instance, then call MeshLib functions on it:

Note: The using declaration requires Node.js 24+ or a current browser. On older runtimes, call .delete() on each object instead (see the Memory Management section below).

import createMeshLib from '@meshinspector/meshlib';
 
const ml = await createMeshLib();
 
// Build a cube (side 2) from raw geometry.
const positions = new Float32Array([
  -1, -1, -1,   1, -1, -1,   1, 1, -1,   -1, 1, -1,
  -1, -1,  1,   1, -1,  1,   1, 1,  1,   -1, 1,  1,
]);
const indices = new Uint32Array([
  0, 2, 1,  0, 3, 2,  4, 5, 6,  4, 6, 7,  0, 1, 5,  0, 5, 4,
  3, 6, 2,  3, 7, 6,  0, 4, 7,  0, 7, 3,  1, 2, 6,  1, 6, 5,
]);
 
using coords = ml.VertCoords.fromArray(positions);
using tris = ml.Triangulation.fromArray(indices);
using mesh = ml.Mesh.fromTriangles(coords, tris);
 
console.log('volume =', mesh.volume()); // ~8

Note: This example loads the module at the top level, which downloads the wasm on startup. In the browser, consider the lazy alternative in Payload Size.

TypeScript

The package ships type definitions, so createMeshLib and the whole module API are typed with minimal setup:

import createMeshLib, { type Mesh } from '@meshinspector/meshlib';
 
const ml = await createMeshLib();
const mesh: Mesh = ml.Mesh.fromTriangles(coords, tris)!;
const { valid, distSq } = ml.findProjection(point, mesh);
mesh.delete();

Memory Management

Values returned from the API (meshes, bit sets, settings, result objects, and so on) hold WebAssembly memory that the JavaScript garbage collector does not reclaim, so each one must be freed explicitly.

The preferred way is JavaScript's explicit resource management: declare a handle with using and it is freed automatically when its scope ends, even if an exception is thrown.

using mesh = ml.Mesh.fromTriangles(coords, tris);

// ... use mesh; it is freed at the end of this scope

When the number of handles is dynamic (for example built in a loop), collect them in a DisposableStack, which frees everything it holds, in reverse order, at the end of the scope:

using stack = new DisposableStack();
for (const path of inputPaths) {
  const cloud = stack.use(ml.PointsLoad.fromAnySupportedFormat(path));
  // ... use cloud
}
// every handle passed to stack.use(...) is freed here

using and DisposableStack are part of JavaScript's Explicit Resource Management, available in Node.js 24+ and current browsers. On older runtimes and browsers, call .delete() on each object when you are done instead:

const mesh = ml.Mesh.fromTriangles(coords, tris);
// ... use mesh
mesh.delete();

Try Interactive MeshLib Examples

You can check how MeshLib works in a browser environment with live interactive examples: https://demo.meshlib.io/

Try MeshLib with JavaScript Examples

After installing MeshLib, a great way to start exploring its capabilities is through the code samples. Each of the following example pages includes a JavaScript tab:

Browse the full set on the MeshLib Code Samples page.

Table of Contents