Using the Nimiq Web Client Across JavaScript Runtimes
Learn how to integrate the Nimiq Albatross light client in any JavaScript environment – from browsers to servers to edge runtimes.
Overview
The Nimiq Albatross light client is distributed as @nimiq/core on npm and comes with three optimized WebAssembly builds, each tailored for different JavaScript environments:
| Build Target | Import Path | Best For | Key Features |
|---|---|---|---|
bundler | @nimiq/core | Webpack, Vite, Rollup, esbuild | Automatic WebAssembly loading via bundler |
web | @nimiq/core/web | Vanilla browsers, Cloudflare Workers, Deno | Manual initialization with init() |
nodejs | @nimiq/core | Node.js ≥ 16, Bun | Synchronous loading, no initialization needed |
Why multiple builds? Each JavaScript runtime handles WebAssembly differently. These builds ensure optimal loading and performance for your specific environment.
The package includes the WebAssembly binary and TypeScript declarations – no additional build steps required.
Browser Environments
Vanilla JavaScript (ES Modules)
For direct browser usage without a bundler, use the /web export:
<script type="module">
import init, * as WebNimiq from '@nimiq/core/web';
// Initialize the WebAssembly module
await init();
// Create and start the client
const config = new WebNimiq.ClientConfiguration().logLevel('info');
const client = await WebNimiq.Client.create(config.build());
await client.waitForConsensusEstablished();
console.log('Nimiq client is ready!');
</script>NOTE
The await init() call is mandatory with the web build.
Hosting the WebAssembly File
When serving your application from a CDN, ensure the nimiq_core_bg.wasm file is accessible:
// Automatic: loads from same directory as the JS file
await init()
// Manual: specify exact URL
await init('/cdn/path/to/nimiq_core_bg.wasm')Modern browsers cache WebAssembly binaries, so this only adds one network request on first load.
Bundler Integration
Modern Bundlers (Vite, Rollup, esbuild)
These bundlers handle WebAssembly automatically:
import * as Nimiq from '@nimiq/core'
const config = new Nimiq.ClientConfiguration().build()
const client = await Nimiq.Client.create(config)Server Environments
Node.js (v24+)
Node.js uses the synchronous build – no initialization needed:
import * as Nimiq from '@nimiq/core'
const config = new Nimiq.ClientConfiguration().build()
const client = await Nimiq.Client.create(config)Why no `init()`?
The Node.js build reads the WebAssembly file directly from disk synchronously.
Another runtime?
Need help with a different environment?
We're here to help you integrate Nimiq with any JavaScript runtime or deployment platform.