BlazorSimdCompatibility

Runtime SIMD/exception-handling detection for Blazor WebAssembly. Automatically falls back to a compatibility build on unsupported browsers — no manual configuration needed.

Problem

.NET 8+ Blazor WASM enables SIMD, exception handling, and jiterpreter by default. These features break on:

• Older CPUs (AMD Phenom II, pre-SSE4 Intel)
• Older Android builds
• Some Firefox versions
• Any browser without WebAssembly SIMD support

The app fails before any C# code runs, so in-app error handling cannot rescue it.

Solution

BlazorSimdCompatibility provides:

1. Runtime detection — JavaScript detects SIMD/exception support before Blazor boots
2. Auto-fallback — loads a compat build transparently on unsupported devices
3. Auto-config — NuGet .props adds ReleaseCompat build configuration automatically
4. CLI tool — verify and automate dual-build + merge

Quick Start

1. Install the NuGet package

dotnet add package BlazorSimdCompatibility

2. Update index.html

<!-- Blazor loader with autostart=false -->
<script src="_framework/blazor.webassembly.js" autostart="false"></script>

<!-- wasm-feature-detect (bundled in the package) -->
<script src="_content/BlazorSimdCompatibility/wasm-feature-detect.1.5.1.js"></script>

<!-- SIMD detection + auto-start -->
<script src="_content/BlazorSimdCompatibility/blazor-simd-compat.js"></script>

3. Publish dual build

# Install the CLI tool
dotnet tool install -g BlazorSimdCompatibility.Cli

# Dual publish + merge
blazor-simd-compat publish

# Verify output
blazor-simd-compat verify bin/Publish/wwwroot

4. Deploy

Deploy bin/Publish/wwwroot/. Modern devices get _framework/ (SIMD), older devices get _frameworkCompat/ (compat) — transparently.

How It Works

Browser loads index.html
  ↓
blazor-simd-compat.js runs
  ↓
wasm-feature-detect checks SIMD + exceptions
  ↓
┌─ Supported → Blazor.start() loads _framework/ (SIMD build)
└─ Not supported → loadBootResource remaps to _frameworkCompat/ (compat build)

CLI Commands

# Verify dual-publish output
blazor-simd-compat verify bin/Publish/wwwroot
blazor-simd-compat verify bin/Publish/wwwroot --pwa

# Dual publish + merge
blazor-simd-compat publish
blazor-simd-compat publish --output bin/Release --pwa
blazor-simd-compat publish --project ./MyApp

Debug Flags

Add query string flags to debug in the browser:

Flag	Effect
?verboseStart=1	Log detection results to console
?forceCompatMode=1	Force compat build (for testing)

Example: https://myapp.com/?verboseStart=1&forceCompatMode=1

PWA Support

For Blazor PWA apps, use --pwa flag:

blazor-simd-compat publish --pwa

This copies service-worker-assets-compat.js for SIMD-aware service worker caching. See the original skill documentation for the full PWA service worker implementation.

AI Skill (Claude Code Plugin)

This repo includes a Claude Code skill at .claude/skills/blazor-simd-compatibility/SKILL.md. Install it as a plugin to get AI-guided setup:

# In your Blazor project directory
claude plugin install path/to/BlazorSimdCompatibility

Then ask Claude in natural language:

• "Add SIMD compatibility to my Blazor WASM app"
• "My app shows a blank page on older Android phones"
• "Set up dual publish for my Blazor project"
• "Deploy my Blazor WASM app to Azure with SIMD compat"

The skill covers: package setup, index.html configuration, dual publish, CI/CD (GitHub Actions), deployment (Azure, GitHub Pages, Docker, Nginx), and debugging.

Requirements

• .NET 8.0 SDK or newer
• wasm-tools workload (for ReleaseCompat build): dotnet workload install wasm-tools

License

MIT