A more complete Nginx configuration example required

[aannenko]

Description

Current nginx.conf examples in the article would not let a person reach even a minimally-functional state of their Blazor WASM app.

A basic Blazor WebAssembly application won’t load correctly when hosted on Nginx unless you include into your nginx.conf a types { ... } block similar to the example below.

It would also be useful to provide guidance on configuring caching for common Blazor WASM assets, as well as enabling compression and standard HTTP headers.

Here is my full configuration for a simple Blazor WASM app:

events { }
http {
    server_tokens off;

    limit_req_zone $binary_remote_addr zone=one:10m rate=60r/s;

    map $uri $cache_control {
        default                             "max-age=3600";
        /index.html                         "no-cache";
        /service-worker.js                  "no-cache";
        ~^/_framework/                      "public, max-age=31536000, immutable";
        ~\.woff2$                           "public, max-age=31536000, immutable";
    }

    types {
        text/html                           html htm;
        text/css                            css;
        application/javascript              js mjs;
        application/json                    json;
        application/manifest+json           webmanifest;
        application/wasm                    wasm;
        text/plain                          txt;
        text/xml                            xml;
        application/octet-stream            bin dll exe pdb blat dat webcil;

        # Images
        image/png                           png;
        image/jpeg                          jpg jpeg;
        image/gif                           gif;
        image/webp                          webp;
        image/avif                          avif;
        image/svg+xml                       svg;
        image/x-icon                        ico;

        # Fonts
        font/woff                           woff;
        font/woff2                          woff2;

        # Fallback (optional – nginx `default_type` can cover this)
        application/octet-stream            *;
    }

    server {
        listen 80;

        charset utf-8;
        charset_types text/html text/plain text/css application/javascript application/json application/manifest+json text/xml image/svg+xml;

        location / {
            root /usr/share/nginx/html;
            try_files $uri $uri/ /index.html =404;
            limit_req zone=one burst=60 nodelay;
            gzip_static on;
            add_header Cache-Control $cache_control always;
            add_header X-Content-Type-Options "nosniff" always;
        }
    }
}

---

Because this is an article about deploying Blazor WASM to Nginx, please also consider adding a sample Dockerfile (see below) - it follows Nginx Docker guidance combined with the recommended ASP.NET Dockerfile samples.
The above configuration works well with Blazor WASM wrapped into an Nginx image, as per their guidance.
Here is a Dockerfile example:

# Use SDK image
FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-noble AS build
WORKDIR /source

# Copy everything and publish the app
COPY MyProject/. MyProject/
RUN apt update \
    && apt install -y python3 \
    && dotnet workload install wasm-tools
RUN dotnet publish MyProject -o /app

# Use runtime image
FROM nginx:alpine
COPY --from=build /app/wwwroot/ /usr/share/nginx/html/
COPY MyProject/nginx.conf /etc/nginx/nginx.conf

Page URL

https://learn.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/webassembly/nginx?view=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/blazor/host-and-deploy/webassembly/nginx.md

Document ID

31142790-bc02-2771-3929-9c593a8433f3

Platform Id

e13f5f31-d03a-c912-55b2-7b31680ddae1

Article author

@guardrex

Metadata

• ID: 31142790-bc02-2771-3929-9c593a8433f3
• PlatformId: e13f5f31-d03a-c912-55b2-7b31680ddae1
• Service: aspnet-core
• Sub-service: blazor

Related Issues

[github-actions]

🥳 Happy Holidays! 🍽️

Stand-by! A green dinosaur 🦖 will be along shortly to assist.

[guardrex]

Thanks @aannenko! Yes, I agree that this article requires major improvements.

Pinging @javiercn to take a look at your suggestions.

If he likes the direction of your suggestions, would you be willing to rewrite the article (i.e., send in a PR)? If so and with management's approval, we should be able to offer you a public byline ("By Andrii Annenko") with your name linked to your organization, website, or social media account.

[aannenko]

Certainly! Thank you :)