`@bitbybit-dev/occt` version `1.0.0-rc.1` no longer builds for browser

[adamscybot]

I am a newcomer to this (brilliant!) project.

I first started using @bitbybit-dev/occt at version 0.21.1 which I was able to build and run in the browser, but only if I enabled skipLibCheck: true because of some missing types coming from the lib.

When investigating that problem (skipLibCheck: true is a pet peave of mine), I noticed the activity here and tried 1.0.0-rc.1. The good news is the type errors are all gone and I can turn skipLibCheck off again 🎉.

The bad news is that it won't compile for the browser. I am using bun bundler configured for a browser target which is perhaps quite cutting edge and possibly a factor. But after digging around to find the cause, I beleive it's not the issue here and this is a problem for bundlers generally.

Bun build error output:

1 | ODE){const{createRequire}=await import("module");var require=createRequire(import.meta.url)}var arguments_=[];var thisPr
                                                                                                                                                                                                                                                                                                                                                         ^
error: Browser build cannot import() Node.js builtin: "module". To use Node.js builtins, set target to 'node' or 'bun'
    at ./node_modules/.bun/@bitbybit-dev+occt@1.0.0-rc.1/node_modules/@bitbybit-dev/occt/bitbybit-dev-occt/bitbybit-dev-occt.js:1:342

The problem seems to be it is trying to conditionally import() stuff from node, guarded with runtime checks to detect node.

The issue with this is bundlers can't universally make that choice statically on complex conditions like this to know to eliminate the "dead code" and therefore it has to assume the guard could evaluate to true, and therefore will attempt to create a chunk for nodes stdlib module package in order to make it available for potential dynamic import later in the runtime -- which obviously won't work in the browser anwyays hence the build-time explosion.

I can do some hackery in my own bundler config using build time overrides of the strings used inside the if conditions that wrap this import, in order to rewrite them them to a statically known value of simply an inline false, which would prevent the bundler from trying to do this (since that really can be statically resolved and so it would eliminate it from the graph entirely via dead code elimination). But that is indeed a hack and I beleive not one that needs to exist...

The canonical and correct solution to this problem today is to provide separate entry points in package.json under the exports object for node/browser etc as detailed here. Bundlers targetting browsers will opt to load the browser entry point, which can then be selective about what it imports and passes along to some platform-agnostic shared common "entry point" just underneath.

E.g. the node entry point would export a thin createBitbybitDevOcct wrapper which calls import('module') (though tbh you no longer need dynamic import here anymore, you can just statically import module from 'node:module') and pass the result of that or something abstracted on top of that down to the "common" file createBitbybitDevOcct underneath, via function params.

The browser entry point would import and then pass down different things/do what it neesd to do -- without needing any import statements to node only packages, dynamic or otherwise, within it.

If the common shared file needs the types of those things still you can use a type import import { type thingyouneed } from 'whatever' which is stripped by bundlers/ts compilers before anything gets to the linking step.

Sorry if you already knew about this. I realise im using an RC right now 😀.

[matas-bitbybit-dev]

Hi @adamscybot, thanks for reporting this - glad you're enjoying the project!

Why this happens

The 1.0.0-rc series uses a new OpenCASCADE 8.0 build compiled with the latest Emscripten, which removed the flag to build web-only output. As a result, the generated JS glue code always includes Node.js references (like import("module")), and it's up to downstream projects/bundlers to handle or exclude them.

Option 1: Use pre-built web workers (recommended for most users)

If you're consuming OCCT through one of the higher-level packages (@bitbybit-dev/threejs, @bitbybit-dev/babylonjs, @bitbybit-dev/playcanvas), you can use pre-built web workers that are already bundled for the browser and fetch the WASM binary from the bitbybit CDN. This means your project doesn't need to define or configure web workers at all.

Here's a complete example (full source):

const sceneOptions = new Inputs.ThreeJSScene.InitThreeJSDto();
sceneOptions.canvasId = "three-canvas";
sceneOptions.sceneSize = 10;
const { scene, startAnimationLoop } = initThreeJS(sceneOptions);
startAnimationLoop();

const bitbybit = new BitByBitBase();
const options: InitBitByBitOptions = {
    enableOCCT: true,
    enableJSCAD: true,
    enableManifold: true,
};
await initBitByBit(scene, bitbybit, options);

You can also self-host the pre-built workers if you prefer not to use bitbybit CDN. https://learn.bitbybit.dev/learn/hosting-and-cdn

Option 2: Using @bitbybit-dev/occt directly

If you're using the @bitbybit-dev/occt package directly and bundling the worker yourself, you'll need to tell your bundler to ignore/stub the Node.js built-ins. In Webpack, for example, I do this:

resolve: {
    extensions: [".tsx", ".ts", ".js"],
    fallback: {
        fs: false,
        perf_hooks: false,
        os: false,
        path: false,
        worker_threads: false,
        crypto: false,
        stream: false,
        module: false,
    }
}

For Bun, the equivalent would be something like using its --external flags or build config to mark these modules as external/empty. I haven't worked with Bun's bundler directly, so I can't provide the exact syntax, but the principle is the same - tell the bundler these Node.js modules won't be available and shouldn't be resolved.

Regarding conditional exports in package.json

Your suggestion about using the exports field with separate node/browser entry points is a valid and well-established pattern. The challenge here is that the Node.js references come from Emscripten-generated glue code (the .js file that loads the .wasm). I'd need to either post-process the Emscripten output or maintain a patched browser-specific version of it. I'll look into this more carefully as a potential improvement - it would certainly provide a cleaner experience for downstream bundlers.

Thanks for the detailed write-up - I'll investigate this further next week when I'm back. In the meantime, I hope one of the options above unblocks you.

[adamscybot]

Hi @matas-bitbybit-dev. Thank you for the detailed response.

I am currently already using @bitbybit-dev/threejs with no other direct calls from my project to other bitbybit packages.

To create a minimum reproduction I then have tried to take your example and compile that -- and I'm running into the same problem. Basically any import to @bitbybit-dev/threejs triggers the issue.

Though this isn't surprising (and I wasn't trying to actively bundle the wasm anyways), because I guess that's simply because as you said:

As a result, the generated JS glue code always includes Node.js references (like import("module")), and it's up to downstream projects/bundlers to handle or exclude them.

and

the Node.js references come from Emscripten-generated glue code (the .js file that loads the .wasm).

Unfortunately, using esbuilds or buns define features to override globalThis.process to undefined in an attempt to coerce the dead code elimination of the bun minifier does not work.

After some investigation, I found this is because the minifier of bun and also esbuild doesn't perform a more complex multi pass. More complex minifiers do do this though (swc, terser, oxc) -- hence some bundlers which come with certain minifiers may not surface this issue, or at least might just require changes to their define config.

With bun/esbuild, It will only work if you first collapse if(ENVIRONMENT_IS_NODE) to if(false) yourself, directly (must be inlined).

As this is a one off and I didn't want to bring in a whole other minifier just for this, I put this plugin together (should work for esbuild folks too)

export function forceEmscriptenDce(): BunPlugin {
  return {
    name: "force-emscripten-dce",
    setup(build) {
      build.onLoad({ filter: /bitbybit-dev-occt.js$/ }, async (args) => {
        let code = await fs.readFile(args.path, "utf8")
        return {
          contents: code.replaceAll(/if\(ENVIRONMENT_IS_NODE\)/g, "if(false)"),
          loader: "js",
        }
      })
    },
  }
}

Which is obviously a bit gross -- but -- im up an running! The bun minifier is now able to perform the dead code elmination I need to wrangle it into working.

Im guesing this doesnt work? The ENVIRONMENT option is still documented I think. Though maybe you dont control this build anyways? Which would indeed be awkward :(.

emcc ... \
  -O3 \
  -sENVIRONMENT=web \
  -sMODULARIZE=1 \
  -sEXPORT_ES6=1 \
  -o out.browser.js

Edit: I just saw this emscripten-core/emscripten#26134. I think ENVIRONMENT is fixed in 5.0.1 (was broken in 5.0.0).

[matas-bitbybit-dev]

I’m really glad to hear you’ve got it working now - and thank you for the detailed response.

I do control the build process (still RC'ish quality), but I’ll try the ENVIRONMENT=web option when I update Emscripten to 5.0.1. Thanks for pointing this out! I thought they just switched to hybrid mode in v5.

I also need to look into Bun more closely. I’ve been seeing it pop up more and more lately, so hopefully I’ll be able to provide a Bun setup example alongside the Vite setups as well with the plugin you provided.