Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dart-lang/sdk/llms.txt

Use this file to discover all available pages before exploring further.

The dart2wasm compiler translates Dart code into WebAssembly (Wasm) modules for modern web browsers. It offers near-native performance and compact binary size, making it ideal for compute-intensive web applications.

​
Overview

dart2wasm compiles Dart to WebAssembly, a portable, low-level binary format designed for efficient execution in web browsers. WebAssembly provides:
  • Near-native performance - Faster than JavaScript for CPU-intensive tasks
  • Compact binaries - Smaller than equivalent JavaScript
  • Predictable performance - No JIT compilation overhead
  • Memory safety - Sandboxed execution environment

​
Browser Support

WebAssembly is supported in all modern browsers:
  • Chrome/Edge 91+
  • Firefox 89+
  • Safari 15+

​
Basic Usage

​
Command Line

Compile a Dart application to WebAssembly: 
dart compile wasm -o output.wasm input.dart
This generates:
  • output.wasm - WebAssembly binary
  • output.mjs - JavaScript loader module

​
Common Options

OptionDescription
-o, --output=<file>Output file path (*.wasm)
-O0, -O1, -O2, -O3, -O4Optimization level
--no-minifyDon’t minify imports/exports
--enable-assertsEnable assert statements
-D<name>=<value>Define environment constant

​
Building and Testing

​
Local Development

For rapid iteration during development: 
# Compile without optimizations (fast compilation)
pkg/dart2wasm/tool/compile_benchmark -O0 -g app.dart app.wasm

# Run with D8 (V8 shell)
pkg/dart2wasm/tool/run_benchmark --d8 app.wasm

# Run with Node.js
node --experimental-wasm-gc output.mjs
The -g flag preserves the name section for debugging and profiling.

​
Using the SDK

With a built Dart SDK: 
# Build the SDK
tools/build.py -mrelease -ax64 create_sdk

# Compile with dart compile wasm
dart compile wasm -o app.wasm app.dart

​
Optimization Levels

No optimizations, fast compilation:
dart compile wasm -O0 -o debug.wasm app.dart
  • Fastest compilation
  • Largest binary size
  • Best for debugging
  • No wasm-opt passes

​
Loading WebAssembly

​
Using the Generated Loader

The compiler generates a JavaScript module loader: 
<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import { instantiate } from './output.mjs';
    
    // Instantiate and run
    const instance = await instantiate();
    // Your Dart main() function runs automatically
  </script>
</head>
<body>
  <div id="output"></div>
</body>
</html>

​
Custom Imports and Exports

Define JavaScript interop: 
// Dart code
import 'dart:js_interop';

@JS()
external void consoleLog(String message);

void main() {
  consoleLog('Hello from Wasm!');
}
See imports_and_exports.md for detailed interop documentation.

​
Wasm Detection

Detect if code is running as WebAssembly: 
const bool isWasm = bool.fromEnvironment('dart.tool.dart2wasm');

void platformSpecificCode() {
  if (isWasm) {
    // WebAssembly-specific code
  } else {
    // JavaScript fallback
  }
}
This constant is tree-shaken, so unused branches are eliminated.

​
Inspecting Wasm Output

​
Disassemble to WAT

Convert binary Wasm to text format: 
# Using wasm2wat from WABT
wasm2wat output.wasm -o output.wat

# Or use the Dart wrapper
dart pkg/dart2wasm/bin/wasm2wat.dart output.wasm > output.wat

​
Analyze Binary Size

# Use wasm-objdump to inspect sections
wasm-objdump -h output.wasm

# Detailed disassembly
wasm-objdump -d output.wasm > disassembly.txt
See inspecting_wasm.md for more tools.

​
Testing

Run dart2wasm test suite: 
# With approval database
dart tools/test.dart -n dart2wasm-linux-d8

# With specific JavaScript engine
dart tools/test.dart -n dart2wasm-linux-optimized-jsshell

# Available engines: d8, jsc, jsshell

​
Benchmarking

​
Performance Testing

# Compile optimized build
pkg/dart2wasm/tool/compile_benchmark -O3 benchmark.dart bench.wasm

# Run with timing
pkg/dart2wasm/tool/run_benchmark --d8 bench.wasm

​
Comparing with JavaScript

# Compile to Wasm
dart compile wasm -O3 -o app.wasm app.dart

# Measure startup and execution
time node --experimental-wasm-gc app.mjs
See benchmarking.md for detailed benchmarking guides.

​
Advanced Configuration

​
Compiler Options

Pass extra options to the compiler: 
pkg/dart2wasm/tool/compile_benchmark \
  --extra-compiler-option=--verbose \
  --extra-compiler-option=--emit-type-checks \
  app.dart app.wasm
View all options: 
dart pkg/dart2wasm/bin/dart2wasm.dart --help

​
Running from Source

Develop the compiler itself: 
# Run without rebuilding
pkg/dart2wasm/tool/compile_benchmark --src app.dart app.wasm

# With assertions for compiler debugging
pkg/dart2wasm/tool/compile_benchmark --src --compiler-asserts app.dart app.wasm

​
Platform-Specific Builds

​
V8 (Chrome/Node.js)

Optimize for V8: 
dart compile wasm -O3 -o app.wasm app.dart
node --experimental-wasm-gc app.mjs
See v8.md for V8-specific details.

​
Flutter Web (HHH)

For Flutter web integration: See flutter_hhh_builds.md for Flutter-specific build instructions.

​
Limitations

  • No dart:io - File system operations not available in browser
  • No dart:mirrors - Reflection not supported
  • No dart:ffi - FFI only works in native environments
  • GC proposal required - Needs browsers with WebAssembly GC support
  • Experimental - API and features may change

​
Performance Characteristics

  • Startup time: Faster than dart2js in most cases
  • Execution speed: Near-native for compute-intensive tasks
  • Binary size: Smaller than equivalent JavaScript
  • Memory usage: Efficient with WebAssembly linear memory