Fix Node.js compatibility for CJS consumers and WASM initialization by kaleababayneh · Pull Request #8 · LumeraProtocol/sdk-js

kaleababayneh · 2026-03-21T19:56:16Z

Problem

The SDK doesn't work properly in Node.js environments. Two issues block usage:

window is not defined (screenshot 1)
Importing the SDK immediately crashes because rq-library-wasm uses a top-level import that eagerly evaluates browser_fs_mem.js, a browser-only file that assigns to window. This occurs even if the consumer never uses any RaptorQ functionality.
ERR_UNKNOWN_FILE_EXTENSION: ".wasm" (screenshot 2)
Node's ESM loader does not recognize .wasm file extensions, causing WASM initialization to fail.

Fix

Lazy-load the WASM module — Instead of importing rq-library-wasm at the top of the file (which immediately executes browser-only code), the module is now loaded on demand via import() only when RaptorQ is actually invoked. A globalThis.window shim is applied before loading so that the browser FS code does not throw in Node.js.
Correct the CJS build paths — package.json pointed to dist/cjs/index.cjs, but tsc outputs index.js. Updated the paths and added a {"type": "commonjs"} marker in dist/cjs/ so Node resolves the module system correctly.

✅ Built and verified locally in Node.js environments.

roomote-v0 · 2026-03-21T19:56:46Z

Rooviewer See task

Re-reviewed after 13d2d6b. The package-lock.json deletion resolves that issue. One minor .gitignore artifact from the missing trailing newline, and the async breaking change still stands.

getWasmSource() uses typeof window === "undefined" for environment detection, but getRqModule() shims globalThis.window in Node.js -- on a retry after init failure, the Node.js path will incorrectly take the browser code path
package-lock.json (8,200+ lines) should not be committed -- this project uses pnpm (pnpm-lock.yaml already exists)
Re-exported utility functions (getFileSize, syncDirExists, etc.) changed from synchronous to async, which is a breaking change to the public API surface
.gitignore: the coverage/ entry under "# Vitest" was corrupted to coverage/package-lock.json due to the original file missing a trailing newline (no functional impact since coverage/ is already ignored on line 171)

Previous reviews

4c2a7a9: Review #1

06e33f8: Review #2

_{Mention @roomote in a comment to request specific changes to this pull request or fix all unresolved issues.}

roomote-v0 · 2026-03-21T19:58:49Z

src/wasm/raptorq-proxy.ts

+async function getWasmSource(): Promise<any> {
+  if (typeof window === "undefined") {


getWasmSource() checks typeof window === "undefined" to decide between the Node.js and browser code paths. But getRqModule() (line 17) sets globalThis.window = globalThis as a shim for Node.js. If initialize() fails after getRqModule() has already been called and cached (e.g., the WASM init itself throws), initPromise is reset to null, allowing a retry. On that retry, getWasmSource() now sees window as defined and takes the browser path (import("rq-library-wasm/rq_library_bg.wasm?url")), which will fail in Node.js.

Consider using a check that is not affected by the shim, such as typeof process !== "undefined" && process.versions?.node or checking before the shim is applied.

_{Fix it with Roo Code or mention @roomote and request a fix.}

roomote-v0 · 2026-03-21T19:59:07Z

package-lock.json

@@ -0,0 +1,8242 @@
+{


This project uses pnpm as its package manager (there is already a pnpm-lock.yaml in the repo). Committing a package-lock.json (8,200+ lines) introduces a conflicting lockfile that can cause dependency resolution confusion. This file should be removed from the PR and added to .gitignore.

_{Fix it with Roo Code or mention @roomote and request a fix.}

roomote-v0 · 2026-03-21T19:59:33Z

src/wasm/raptorq-proxy.ts

+export async function getFileSize(...args: Parameters<typeof import("rq-library-wasm").getFileSize>) {
+  const rq = await getRqModule();
+  return rq.getFileSize(...args);
+}


These re-exported utility functions (getFileSize, syncDirExists, etc.) were previously synchronous re-exports from rq-library-wasm. Wrapping them in async functions changes their return type from T to Promise<T>. Any downstream consumer that was calling, for example, getFileSize(path) synchronously (without await) will now silently receive a Promise object instead of a number. This is a breaking change to the public API surface. If these functions are not currently consumed externally, this is fine, but it should be called out in release notes or the version should be bumped accordingly.

_{Fix it with Roo Code or mention @roomote and request a fix.}

…window for Node.js, remove package-lock.json

roomote-v0 · 2026-03-22T08:23:35Z

.gitignore

+coverage/package-lock.json
+package-lock.json


The original file ended with coverage/ and no trailing newline. When package-lock.json was appended, it got concatenated onto that line, turning coverage/ into coverage/package-lock.json. No functional impact since coverage/ is already ignored on line 171, but this wasn't the intended result.

Suggested change

coverage/package-lock.json

package-lock.json

coverage/

package-lock.json

_{Fix it with Roo Code or mention @roomote and request a fix.}

mateeullahmalik

Thanks for the PR — the intent is good and I appreciate the effort to improve Node compatibility + CJS consumption.

I went through the changes and validated locally. Before we can merge, there are a few blocking issues to address:

CJS runtime break: import.meta.url is still emitted into CJS output from src/wasm/raptorq-proxy.ts, which causes SyntaxError: Cannot use 'import.meta' outside a module when requiring the CJS build.
Public API behavior drift: re-exported FS helpers now become async wrappers (e.g. getFileSize, dirExists, syncDirExists). This changes consumer-facing behavior/signatures and is a breaking change unless explicitly versioned + documented.
Current branch test status: tests/wasm/raptorq-proxy.spec.ts is failing in this branch and should be green before merge.

Please fix the above and I’ll re-review quickly. Happy to approve once these are addressed 🙌

mateeullahmalik · 2026-03-25T12:59:24Z

src/wasm/raptorq-proxy.ts

+    } else {
+      const { createRequire } = await import("node:module");
+      // @ts-ignore - import.meta.url is only available in ESM
+      const req = createRequire(import.meta.url);


import.meta.url here is problematic for the CJS build. In the emitted dist/cjs output this causes a hard parse/runtime failure (Cannot use 'import.meta' outside a module) for require() consumers. We should avoid emitting import.meta into CJS-targeted code paths.

mateeullahmalik · 2026-03-25T12:59:25Z

src/wasm/raptorq-proxy.ts

+  const rq = await getRqModule();
+  return rq.readFileChunk(...args);
+}
+export async function getFileSize(...args: Parameters<typeof import("rq-library-wasm").getFileSize>) {


This changes getFileSize from a direct export to an async wrapper returning a Promise. That is a behavior/signature change for public API consumers. Please preserve the original sync/async contract (or treat as explicit breaking change with versioning/docs).

mateeullahmalik · 2026-03-25T12:59:25Z

src/wasm/raptorq-proxy.ts

+  const rq = await getRqModule();
+  return rq.dirExists(...args);
+}
+export async function syncDirExists(...args: Parameters<typeof import("rq-library-wasm").syncDirExists>) {


Similar concern for syncDirExists/dirExists wrappers: converting these to async wrappers changes external behavior. Can we keep export semantics aligned with previous API surface to avoid regressions for existing callers?

…nc FS exports, fix tests. Added a node example

kaleababayneh · 2026-03-26T08:42:53Z

The existing example used DirectSecp256k1HdWallet which doesn't support signArbitrary since cosmjs hasn't implemented it yet (cosmjs#844). Cascade requires ADR-036 arbitrary signing, so the example now creates a combined signer that wraps both DirectSecp256k1HdWallet (for signDirect) and Secp256k1HdWallet (for signAmino/signArbitrary).

Worth considering creating a LumeraSigner.fromMnemonic() helper that handles all three signing methods out of the box.

Fix Node.js CJS entry point and lazy-load WASM for Node compatibility

06e33f8

roomote-v0 bot reviewed Mar 21, 2026

View reviewed changes

kaleababayneh added 2 commits March 21, 2026 23:08

Address review feedback: Use process.versions.node instead of typeof …

4c2a7a9

…window for Node.js, remove package-lock.json

remove package.json

13d2d6b

roomote-v0 bot reviewed Mar 22, 2026

View reviewed changes

mateeullahmalik requested changes Mar 25, 2026

View reviewed changes

kaleababayneh added 2 commits March 26, 2026 11:03

Address review feedback: remove import.meta.url from CJS, preserve sy…

1a8cde3

…nc FS exports, fix tests. Added a node example

Update upload example: use existing styling and add step logging

f8a7f83

kaleababayneh requested a review from mateeullahmalik March 26, 2026 08:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix Node.js compatibility for CJS consumers and WASM initialization#8

Fix Node.js compatibility for CJS consumers and WASM initialization#8
kaleababayneh wants to merge 5 commits intoLumeraProtocol:masterfrom
kaleababayneh:master

kaleababayneh commented Mar 21, 2026 •

edited

Loading

Uh oh!

roomote-v0 bot commented Mar 21, 2026 •

edited

Loading

Uh oh!

roomote-v0 bot Mar 21, 2026

Uh oh!

roomote-v0 bot Mar 21, 2026

Uh oh!

roomote-v0 bot Mar 21, 2026

Uh oh!

roomote-v0 bot Mar 22, 2026

Uh oh!

mateeullahmalik left a comment

Uh oh!

mateeullahmalik Mar 25, 2026

Uh oh!

mateeullahmalik Mar 25, 2026

Uh oh!

mateeullahmalik Mar 25, 2026

Uh oh!

kaleababayneh commented Mar 26, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		async function getWasmSource(): Promise<any> {
		if (typeof window === "undefined") {

Conversation

kaleababayneh commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Fix

Uh oh!

roomote-v0 bot commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

roomote-v0 bot Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

roomote-v0 bot Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

roomote-v0 bot Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

roomote-v0 bot Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

mateeullahmalik left a comment

Choose a reason for hiding this comment

Uh oh!

mateeullahmalik Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

mateeullahmalik Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

mateeullahmalik Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

kaleababayneh commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kaleababayneh commented Mar 21, 2026 •

edited

Loading

roomote-v0 bot commented Mar 21, 2026 •

edited

Loading

kaleababayneh commented Mar 26, 2026 •

edited

Loading