WebAssembly Documentation

February 6, 2026 ยท View on GitHub

This document serves as a guide for contributors to the WebAssembly implementation in the dotnet/runtime repository. It provides links and references to technical documentation, workflows, and resources relevant to developing and maintaining WebAssembly support within this codebase.

Table of Contents

Getting Started

What is .NET WebAssembly?

.NET WebAssembly allows you to run .NET applications in web browsers and other WebAssembly-compatible environments. The runtime uses the Mono runtime to execute .NET bytecode compiled to WebAssembly.

Supported Environments

  • Browser (browser-wasm): Run .NET applications in web browsers
  • WASI (wasi-wasm): Run .NET applications in WASI-compatible environments

Building for WebAssembly

Core Runtime Building

Libraries Building

WASI Support

  • WASI Support - Experimental WASI support, building, and configuration

Testing and Debugging

Library Testing

Runtime Debugging

Common Debugging Scenarios

For debugging instructions including VS Code and Chrome DevTools setup, see the WebAssembly Debugging Reference.

Running coreclr callhelpers generator

After building the runtime, use the generate-coreclr-helpers script for your platform (.cmd or .sh) in src/tasks/WasmAppBuilder to [re]generate the call helpers in src/coreclr/vm/wasm.

Features and Configuration

Runtime Features

JavaScript Interop

Globalization and ICU

Testing WebAssembly Changes

For testing WebAssembly implementation changes end-to-end, see the testing documentation.

Advanced Topics

Performance and Optimization

  • Profiling: Use browser dev tools profiler integration
  • AOT Compilation: Improve runtime performance with ahead-of-time compilation
  • IL Trimming: Reduce application size by removing unused code

Samples and Examples

Located in src/mono/sample/wasm/:

  • browser-bench: Performance benchmarking sample
  • browser-profile: Profiling sample
  • console: Console application samples

Workloads

  • wasm-tools: Production WebAssembly tools and optimization
  • wasm-experimental: Experimental features and templates

FAQ

How do I debug a library test failure seen on CI?

See the WebAssembly Debugging Reference for detailed instructions on debugging library tests locally.

How do I build for different WebAssembly targets?

See the Building for WebAssembly section above for build instructions for different targets.

How do I test Wasm changes end to end?

Use Wasm.Build.Tests or Wasi.Build.Tests. See the Wasm.Build.Tests README for detailed instructions.

How do I enable multi-threading?

See the Threading Support documentation for detailed multi-threading configuration and limitations.

What JavaScript engines are supported for testing?

See the Testing Libraries on WebAssembly documentation for JavaScript engine installation and usage.

How do I collect native stack traces with symbols?

See the WebAssembly Debugging documentation for symbol configuration.

How do I run tests with different configurations?

  • With AOT: Add /p:RunAOTCompilation=true
  • With trimming: Add /p:EnableAggressiveTrimming=true
  • Different JS engine: Add /p:JSEngine=SpiderMonkey
  • Outer loop tests: Add /p:Outerloop=true

Contributing

Code Style

  • Runtime JavaScript code uses ESLint rules in .eslintrc.js
  • Run npm run lint in src/mono/browser/runtime
  • Install VS Code ESLint plugin for real-time checking

Building Changes

When making changes that affect native code or build configuration, see Building the Repo for detailed instructions.

Then test your changes with Testing the Repo using the relevant test suites.

Documentation Updates

When updating WebAssembly documentation:

  1. Update this index if adding new documents
  2. Ensure cross-references remain valid
  3. Test documentation examples locally
  4. Follow existing documentation patterns and styles

For questions or additional help, see the main workflow documentation or ask in the dotnet/runtime repository discussions.