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:

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

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 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, 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 for memory, cancellation, and storage behavior.