Deploy and Host Blazor WebAssembly Starter on Railway

A production-ready Blazor WebAssembly template that runs entirely in the browser. Build interactive web applications with C# and .NET 9 without JavaScript. Perfect for SPAs, PWAs, and offline-capable apps with ultra-low hosting costs since everything executes client-side.

About Hosting Blazor WebAssembly Starter

Blazor WebAssembly compiles your C# code to WebAssembly and runs entirely in the browser with no server dependency after initial download. Railway handles the Docker build process that compiles your .NET 9 application to WASM, then serves the static files via nginx on Alpine Linux. The multi-stage build optimizes image size and compilation speed. nginx is configured with proper MIME types for WebAssembly files, gzip compression for faster loading, and SPA routing to handle client-side navigation. Public networking is pre-configured with automatic SSL certificates. After deployment, your app downloads once to the browser and runs completely client-side with native-like performance.

Common Use Cases

• Progressive Web Apps (PWA) - Installable apps that work offline, can be added to home screen on mobile and desktop, and provide native-like experience
• Client-side tools and calculators - Mortgage calculators, unit converters, financial planners, code formatters running entirely in browser with zero server costs
• Interactive documentation and showcases - API documentation, component libraries, design systems, and pattern showcases with live interactive demos
• Data visualization dashboards - Charts, graphs, analytics, and business intelligence running client-side without backend infrastructure
• Browser-based games and simulations - C# game logic and physics simulations running in browser with WebAssembly near-native performance
• Marketing and portfolio websites - Static content sites enhanced with interactive C# components, forms, and animations without server dependency

Dependencies for Blazor WebAssembly Starter Hosting

• .NET 9 SDK - Provided via mcr.microsoft.com/dotnet/sdk:9.0 Docker image for compiling C# to WebAssembly
• nginx Alpine - Ultra-lightweight web server (nginx:alpine ~40MB) for serving static WASM files efficiently
• WebAssembly Runtime - Built into all modern browsers (Chrome 57+, Firefox 52+, Safari 11+, Edge 79+)
• Docker Multi-Stage Build - Compiles WASM in SDK container, serves from minimal nginx container

Deployment Dependencies

• Blazor WASM Documentation - Official Microsoft WebAssembly hosting guide and architecture
• WebAssembly Specification - Understanding WASM technology, browser support, and performance characteristics
• .NET 9 Release Notes - Latest .NET WASM features, optimizations, and runtime improvements
• nginx Documentation - Web server configuration, performance tuning, and security best practices
• Railway Docker Builds - Understanding Railway's Docker build process and optimization

Implementation Details

Multi-Stage Docker Build: Efficient two-stage process separates compilation from serving:

# Stage 1: Build - Compile C# to WebAssembly
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY BlazorWasmStarter/*.csproj BlazorWasmStarter/
RUN dotnet restore "BlazorWasmStarter/BlazorWasmStarter.csproj"
COPY BlazorWasmStarter/ BlazorWasmStarter/
WORKDIR /src/BlazorWasmStarter
RUN dotnet publish "BlazorWasmStarter.csproj" -c Release -o /app/publish

# Stage 2: Serve - nginx serves static WASM files
FROM nginx:alpine
WORKDIR /usr/share/nginx/html
COPY --from=build /app/publish/wwwroot .
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 8080

nginx SPA Configuration: Optimized for single-page applications with proper WASM support:

events { }

http {
    include /etc/nginx/mime.types;
    
    server {
        listen 8080;
        server_name _;
        root /usr/share/nginx/html;
        index index.html;
        
        # SPA routing - all routes serve index.html
        location / {
            try_files $uri $uri/ /index.html =404;
        }
        
        # Enable gzip compression for faster loading
        gzip on;
        gzip_types application/wasm application/javascript text/css;
    }
}

WebAssembly Download Process: First-time visitors download the .NET runtime and your app assemblies:

• dotnet.wasm - .NET WebAssembly runtime (~2 MB compressed)
• blazor.boot.json - Manifest listing all required assemblies
• Application DLLs - Your compiled C# code as .NET assemblies
• All files are cached by browser for subsequent visits

Client-Side Execution Benefits:

• No server round-trips for UI updates or interactions
• Offline capability after initial load completes
• Near-native performance via WebAssembly JIT compilation
• Direct browser API access (DOM, localStorage, geolocation)
• Reduced server costs - only pay for initial file serving

Adding API Backend: WASM apps typically call REST APIs for data persistence. You can:

1. Deploy a separate ASP.NET Core Web API service on Railway
2. Configure CORS to allow requests from your WASM origin
3. Call the API using HttpClient from your WASM components
4. Store authentication tokens in browser local storage

Performance Optimizations:

• AOT (Ahead-of-Time) compilation for faster startup and execution
• Lazy loading assemblies to load features on-demand
• Response compression (gzip/brotli) for faster downloads
• Browser caching reduces repeat visitor load times
• Tree trimming removes unused code from final build

Progressive Web App Support: Convert to PWA by using the PWA template variant:

dotnet new blazorwasm --pwa -n BlazorWasmStarter

This adds service worker for offline support, web manifest for installation, and icon assets for home screen.

Why Deploy Blazor WebAssembly Starter on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Blazor WebAssembly Starter on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Additional WASM-Specific Benefits:

• Ultra-Low Cost - Static file hosting typically costs $1-3/month, far less than server-side apps
• Lightning Fast Deployment - From git push to live in under 90 seconds with zero configuration
• Global Performance - Railway's CDN ensures fast loading worldwide with edge caching
• Zero Server Maintenance - nginx serves static files, no application runtime to manage or update
• Effortless Scaling - nginx handles thousands of concurrent users on minimal CPU and memory
• Automatic HTTPS - SSL certificates provisioned and auto-renewed for secure connections