Auto-build WASM packages on npm install via prepare hook

[secretrobotron]

After cloning the repo and running npm install, the npm run build command fails with this error:

[vite]: Rollup failed to resolve import "spark-rs" from "src/SplatPager.ts".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to build.rollupOptions.external.

(fresh clone on osx with cargo 1.94.1 and npm 11.8.0)

The error message suggests a Vite/Rollup config issue, but the real problem is that the spark-rs and spark-worker-rs WASM packages haven't been built yet. Their pkg/ directories are gitignored (correctly), but nothing in the standard setup flow builds them automatically. You have to know to run npm run build:wasm first, which is only mentioned in the README's build instructions in passing.

Fix

This PR sets the prepare script in package.json to npm run build:wasm. The prepare hook runs automatically after npm install, so the WASM packages are built before anything else needs them. This means npm install && npm run build just works out of the box for new contributors.

The WASM build is only triggered by npm install — not on every npm run build — so there's no performance cost during normal development iteration.

Verification

• Delete rust/spark-rs/pkg and rust/spark-worker-rs/pkg
• Run npm install — verify WASM packages are built automatically
• Run npm run build — verify it completes successfully

[dmarcos]

Thanks!

[mrxz]

While the change itself is okay, it's worth noting that this prepare script used to be there before. It was removed deliberately in commit 2fbde38. We should avoid changing this back and forth repeatedly.

AFAIUI there are two setups Spark is trying to accommodate: building/developing the project itself and using a specific commit of Spark as dependency in a project. The former requires the user to build the wasm projects. In this case having it part of the prepare script is beneficial. The latter is meant to use the pre-built bundles in the dist/ folder, but many package managers execute the prepare script regardless (see #195).

In practice people that wanted to test the latest commits ran into issues because they didn't have a Rust toolchain setup. Arguably this negates the convenience of providing pre-built bundles.

[secretrobotron]

@mrxz that totally makes sense. In that case, we should just revert, and update the README, no?

[asundqui]

@dmarcos @mrxz a build system that updated to the latest version hit an issue with this recently - Since we now require rust/rustup to be installed in order to npm install on some systems, this fails. The fix is of course relatively simple - either add rust/rustup to the build system environment, or have a fork without npm run build:wasm in the prepare script :).

Is there any way you guys can think of that we can improve how we do things to both have pre-builds that are easy to link to, and have developer install+build be simple? I agree with @mrxz that we shouldn't be changing this back and forth, but is the current state the lesser of two evils? What if we improved the README/docs to highlight the need to run build:wasm? What if the Rust packages were pre-built somehow in the repo, is this possible at all?

[secretrobotron]

(omg, I'm so sorry for this. I was just trying to be helpful hahaha.)

@asundqui @dmarcos @mrxz honestly, a simple README update would have probably been enough for me. I just thought, "oh, it looks like they left that part out!" as I read the docs.

[mrxz]

Is there any way you guys can think of that we can improve how we do things to both have pre-builds that are easy to link to, and have developer install+build be simple? I agree with @mrxz that we shouldn't be changing this back and forth, but is the current state the lesser of two evils?

The main reason we have pre-built versions in the repo is for people to easily use/test the latest commits. Most people don't have the Rust toolchain setup when they attempt this. From that point of view I'd consider not using the prepare script the lesser of two evils.

That just leaves us with the challenge of how to improve the developer install+build experience. Updating the README to make this step clearer/explicit is the easiest and might already be enough. On top of that we could look into a mechanism similar to the "no local assets directory" message we show in the vite.config.ts, to notify users if the spark-rs or spark-worker-rs projects aren't built and point them to the build:wasm command and/or installing Rust.