Handling Binary Assets

Some libraries, like the Matrix JS SDK, require loading external binary dependencies like `.wasm` files. Coralite provides a seamless way to handle these files during both development and production builds.

The `assets` Configuration #

In your `coralite.config.js` file, you can specify an `assets` array. This array tells Coralite to copy specific files from an NPM package into your project's build output.

Each object in the `assets` array must define a dest (the destination path relative to your output directory). To determine the source file, you must provide either:

• pkg (the NPM package name) and path (the relative path to the asset within the package).
• OR src (an absolute local path to the source file or directory, which completely bypasses package resolution).

Example: Matrix JS SDK #

Here is an example of configuring your project to include the WebAssembly files required by the Matrix SDK.

export default defineConfig({
  output: './dist',
  components: './src/components',
  pages: './src/pages',
  public: './public',
  assets: [
    {
      pkg: 'matrix-js-sdk',
      path: 'lib/matrix.wasm',
      dest: 'wasm/matrix.wasm'
    }
  ]
})
    

When you run the development server (`pnpm run dev`) or build your project (`pnpm run build`), Coralite will automatically extract `matrix.wasm` from your `node_modules` and place it in your configured output folder under `wasm/matrix.wasm`.

You can then point your library configuration to fetch the file from `/wasm/matrix.wasm`.

Bypassing Package Resolution #

If a package does not explicitly export its package.json, the plugin will attempt an upward directory traversal. However, if you need to bypass package resolution entirely, you can provide an absolute path via the src property.

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const wasmPath = require.resolve('@matrix-org/matrix-sdk-crypto-wasm/pkg/matrix_sdk_crypto_wasm_bg.wasm');

export default defineConfig({
  assets: [{ src: wasmPath, dest: 'matrix_sdk_crypto_wasm_bg.wasm' }]
});
    

MIME Type Support #

To ensure `.wasm` files execute correctly for streaming compilation, the Coralite development server automatically configures the appropriate `application/wasm` MIME type headers for any files ending in `.wasm`.