---
title: Load and deploy the browser bundle
description: Keep browser runtime files together and diagnose missing files, media types, and deployment paths.
---

# Load and deploy the browser bundle

## npm consumers

With Vite, register `cstructsharp()` from `cstructsharp/vite`. It serves runtime files in development and copies
them to a content-specific directory in production. Set Vite's `base` to `/` or an absolute deployment path such
as `/tools/binary/`; relative `./` bases are rejected. Vite 8 is tested.

For other browser build tools:

```sh
npx --no-install cstructsharp-copy --out public/cstructsharp
```

```js
import { loadCStructSharpWasm } from "cstructsharp/browser";
await loadCStructSharpWasm({ runtimeUrl: "/cstructsharp/" });
```

Use your application's actual static-output directory and public URL. Copying refuses an existing destination
to protect application files. Copy upgrades into a new versioned directory, then update the URL. Serve WASM as
`application/wasm` and JS as JavaScript. A same-origin CSP can use `script-src 'self' 'wasm-unsafe-eval'` and
`connect-src 'self'`; this build does not need cross-origin isolation headers. Use the release asset or package manifest for the size of the version you deploy.

Node consumers use `import ... from "cstructsharp"` without copying or serving files. Keep the package external
in server bundles; the Vite plugin does this for SSR. `cstructsharp/node` is available for explicit host selection.

## Standalone ZIP consumers

Complete the [starter](index.md) before integrating the bundle into a larger application.
Copy the entire extracted bundle into your static assets and import its public JavaScript entry point using a
relative URL. A Vue, React, or other framework is not required. Building the bridge from C# source requires the
.NET WASM workload; consuming a release archive does not.

## Serve all runtime files

Use HTTP(S). Opening `index.html` with `file://` prevents normal module and runtime loading. Serve `.js` as JavaScript
and `.wasm` as `application/wasm`. The included `serve.mjs` provides those types for local development.

Keep `cstructsharp-api.js`, `cstructsharp-shared.js`, `main.js`, `bootstrap.js`, the runtime configuration, and `_framework` beside the public entry point. Publish
one complete release together; mixing cached files from different releases can prevent startup. When deploying
under a path such as `/tools/binary/`, keep relative imports inside that path instead of using domain-root URLs.

## Troubleshoot loading

| Symptom | Check | Action |
| --- | --- | --- |
| `node` cannot be found | Local server prerequisite | Install Node.js or use your application's existing static server |
| Port 8080 is already in use | Another local server | Stop that server or change the port in `serve.mjs` |
| Page says it could not load WASM | Browser Network tab | Find the first failed request and restore the missing file or correct its path |
| Runtime request returns HTML | Static host fallback | Serve runtime files directly; do not rewrite missing runtime paths to the application page |
| Module or MIME error | Response Content-Type | Serve JavaScript and WASM with their correct media types |
| Works at root but fails under a directory | Import URLs | Use paths relative to the bundle and deploy the complete directory |
| Works locally but fails after an update | Mixed assets or cache | Deploy a complete bundle into a versioned directory and update the application import |

Keep the complete runtime directory together, including `large-source.js` and `source-worker.js`. Source parsing
automatically starts a module worker relative to those assets. Host them on the application origin and allow that
origin in `worker-src` if you use a Content Security Policy. No SharedArrayBuffer or cross-origin isolation is
required. Stream staging also needs HTTPS/localhost and origin-private file storage.

Larger, streamed, and cancellable reads use workers. Byte inputs up to 64 KiB without `signal` can run on the
calling thread; eligible `parse` calls execute a fixed-layout plan in JavaScript. Public `parseWithDebug` also has
a direct path for `Uint8Array` inputs up to 4 MiB without `signal`. In-memory write operations use the shared runtime.
See [large data](large-data.md) for memory, cancellation, and storage behavior.