Skip to content

Blazor SEO: prerendering, render modes and the raw HTML

Blazor SEO depends on what the first HTTP response holds: how each render mode, prerendering and standalone WebAssembly change the raw HTML crawlers read.

By Crawlito · 8 min read

In short

  • In a Blazor Web App the default render mode is Static, and Microsoft says prerendering is enabled by default for the Interactive Server, Interactive WebAssembly and Interactive Auto modes.
  • Passing prerender: false to a render mode removes that component's content from the first HTTP response, and doing it on HeadOutlet also removes the server-rendered title and meta tags.
  • OnAfterRender and OnAfterRenderAsync are not called during prerendering, so data loaded there reaches the page only after the app becomes interactive.
  • A standalone Blazor WebAssembly app is a set of static files whose index.html contains only a loading indicator inside div id app until the .NET runtime downloads and starts.
  • Prerendering runs OnInitializedAsync twice; Microsoft's fix is persisting prerendered state, which in .NET 10 and later is the [PersistentState] attribute.
On this page

Blazor can be fully readable by crawlers, but only if the page text is in the first HTTP response. In a Blazor Web App that is the default: static server-side rendering sends finished HTML, and the interactive render modes prerender on the server unless you turn it off. The two setups that hand crawlers little or nothing are a standalone Blazor WebAssembly app, which ships a loading indicator, and components whose content only appears after they become interactive.

This post maps each Blazor hosting model and render mode to what the raw HTML contains, using Microsoft's documentation for .NET 8 to .NET 10, then shows how to check and fix the common gaps. For the general case of SSR against client-side rendering, see SSR vs CSR for SEO and AI search.

What each Blazor render mode puts in the first response

Microsoft's render modes article lists four modes for a Blazor Web App and says the default render mode is Static. It also says: "Prerendering is enabled by default for interactive components." Prerendering means the server renders the component to HTML for the initial response, and Blazor then makes it interactive in the browser.

Mode or modelWhere it rendersWhat a crawler gets in the raw HTML
Static Server (static SSR)ServerThe full component markup. No interactivity.
Interactive Server, prerendered (default)Server, then a SignalR circuitThe prerendered markup, then live updates over the circuit
Interactive WebAssembly, prerendered (default)Server once, then the browserThe prerendered markup, then the .NET runtime takes over in the browser
Interactive Auto, prerendered (default)Server, then the browser on later visitsThe prerendered markup
Any interactive mode with prerender: falseServer circuit or browser onlyNothing from that component until it runs interactively
Standalone Blazor WebAssemblyBrowser onlyA loading indicator inside <div id="app">

Two consequences matter for crawlers. First, if nobody changed the defaults, a Blazor Web App already sends real HTML. Second, everything rides on the word "prerendered": the moment it is switched off, an interactive component behaves like a client-side rendered page, which is the empty HTML problem in Blazor form.

Microsoft's prerender article also says prerendering "can also improve Search Engine Optimization (SEO) by rendering content for the initial HTTP response". That initial response is the only version a crawler that does not run JavaScript ever reads. Vercel and MERJ's December 2024 measurement found that none of the major AI crawlers it tracked rendered JavaScript; do AI crawlers run JavaScript? has the details by crawler.

How prerendering gets disabled, and what that removes

Developers usually turn prerendering off for a practical reason. Microsoft notes that prerendering means components "must render twice", and WebAssembly components must then work on both server and client. Client-only services also fail during prerendering: injecting IWebAssemblyHostEnvironment into a prerendered .Client component throws at runtime because the service is not registered on the server. The quick fix people reach for is this:

razor
@* Per component instance *@
<ProductList @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />

@* Or for the whole app, in Components/App.razor *@
<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />
<Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />

The second form is the one to look for in an audit. Setting it on Routes removes the page body from the first response for every route. Setting it on HeadOutlet removes what PageTitle and HeadContent render, because HeadOutlet is the component that writes them into <head>. A crawler then gets no PageTitle output at all, only any literal markup typed directly into the <head> of App.razor, the same on every URL, and none of your per-page meta descriptions or canonical tags.

At the time of writing, Microsoft also documents that the prerender flag only takes effect on top-level render modes: if a parent component sets a render mode, its children's prerendering settings are ignored. So a single prerender: false high in the tree can silence a whole section.

Fix it without giving up the reason it was disabled:

  1. Keep prerendering on for public pages and solve the double render with persisted state (next section).
  2. For client-only services, Microsoft lists alternatives to disabling prerendering: register the service on the server too, make it optional, or create a service abstraction with a server implementation.
  3. Disable prerendering only on components that have nothing to index, such as a chart editor or an account widget, and set it per instance rather than on Routes.

Content loaded in OnAfterRenderAsync never reaches the raw HTML

The component lifecycle article is explicit: OnAfterRender and OnAfterRenderAsync "aren't called during the prerendering process on the server". They run only after the Blazor script starts in the browser and the component restarts interactively. Prerendering is not attached to a live browser DOM, and JavaScript interop is not possible during it.

That makes this common pattern invisible to non-rendering crawlers, even with prerendering on:

razor
@code {
    private Product? product;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            product = await Api.GetProductAsync(Slug); // runs only interactively
            StateHasChanged();
        }
    }
}

The prerendered HTML contains whatever the markup shows while product is null, usually a spinner or "Loading...". Move the load to OnInitializedAsync, which does run during prerendering, and persist the result so the interactive render does not fetch it again. In .NET 10 and later, Microsoft's prerendered state persistence article shows the [PersistentState] attribute on a public property:

razor
@code {
    [PersistentState]
    public Product? Product { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Product ??= await Api.GetProductAsync(Slug);
    }
}

The same article says the state is serialized with System.Text.Json and persisted in the prerendered HTML, and that for WebAssembly and Auto modes this data is exposed to the browser, so it must not contain private information. In .NET 8 and 9 the equivalent is the PersistentComponentState service with RegisterOnPersisting and TryTakeFromJson. Without persistence, Microsoft notes that OnInitializedAsync is called twice and the UI may flicker as prerendered content is replaced.

Keep OnAfterRenderAsync for work that needs the DOM or JavaScript, such as focusing an input or starting a map library. If you need to branch on the phase inside a component, in .NET 9 and later RendererInfo.IsInteractive is false during prerendering and static SSR.

Content that only arrives over the SignalR circuit

With Interactive Server, the hosting models article says "UI updates, event handling, and JavaScript calls are handled over a SignalR connection using the WebSockets protocol." Anything that appears after the first response travels as a circuit update, not as HTML a crawler downloads. That covers:

  • Data loaded after render, as above.
  • Content shown only after a click, such as tabs or "show more" buttons wired to @onclick. Static HTML for collapsed sections is safer, as covered in lazy-loaded tabs and accordions.
  • Updates pushed from timers or server events.

Google's JavaScript troubleshooting guide says Googlebot does not support connection types such as WebSockets and WebRTC and advises an HTTP fallback to retrieve content. Rather than rely on any crawler following a circuit, put the indexable text in the prerendered markup.

Microsoft also notes that internal navigation with interactive routing does not use prerendering, because the app is already interactive. That is fine for crawlers, which request each URL directly and so get the prerendered response, but it means testing by clicking through the app in a browser tells you nothing about what a crawler gets. Always test with a fresh request per URL.

Streaming rendering and slow prerenders

Prerendering waits for what Microsoft calls quiescence: a component does not render until the whole render tree has finished, so a slow database call in OnInitializedAsync delays the entire response. The documented fix is streaming rendering: the [StreamRendering] attribute in .NET 9 and later, or [StreamRendering(true)] in .NET 8. The rendering article says the page first renders "with placeholder content", then the updated content "is sent to the client on the same response connection and patched into the DOM". It also says hosts that buffer responses get the page without streaming.

So streamed content is in the same response, but it is not in its final position in the markup the server sends first, and Blazor's script does the patching. How each AI crawler's text extraction handles that is not documented. For the facts you most need crawlers to read, such as a product name, price or the main article text, prefer data that is ready without streaming, or check the raw response as shown below.

Standalone Blazor WebAssembly: the loading shell

A standalone app has no server rendering. Microsoft describes it as running "exclusively" on the WebAssembly hosting model, deployable as static files from a CDN. The project template's index.html is what the host serves for every route (shortened here; the real script tag carries a fingerprint placeholder):

html
<body>
    <div id="app">
        <svg class="loading-progress">
            <circle r="40%" cx="50%" cy="50%" />
            <circle r="40%" cx="50%" cy="50%" />
        </svg>
        <div class="loading-progress-text"></div>
    </div>
    ...
    <script src="_framework/blazor.webassembly.js"></script>
</body>

Page titles are added in the browser too: the template registers HeadOutlet with builder.RootComponents.Add<HeadOutlet>("head::after"), which appends to the static head in index.html. A crawler that does not run the .NET runtime sees one title and a progress ring on every URL.

Microsoft's prerendering guidance covers Blazor Web Apps and Blazor Server apps, not standalone WebAssembly. If public pages need to be read by crawlers, the setup Microsoft documents prerendering for is a Blazor Web App: keep the WebAssembly components with the Interactive WebAssembly or Auto mode, which prerender by default, or render marketing and content pages with static SSR. Keep standalone WebAssembly for apps behind a login.

How to check what your Blazor app sends

Fetch each important template the way a crawler does, with no JavaScript, and look for a sentence you know is on the page. How to see your page as an AI crawler, with curl has more variations.

bash
UA="Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.4; +https://openai.com/gptbot"
URL=https://example.com/products/blue-kettle

# 1. Is the main text in the raw HTML? 0 means it is rendered later.
curl -s -A "$UA" "$URL" | grep -c "Holds 1.7 litres"

# 2. Is this page a standalone WebAssembly shell?
curl -s -A "$UA" "$URL" | grep -c "loading-progress"

# 3. Does each URL have its own title?
curl -s -A "$UA" "$URL" | grep -o "<title>[^<]*</title>"

Then read the results:

ResultLikely causeFix
Text missing, title correctData loaded in OnAfterRenderAsync or after a clickLoad in OnInitializedAsync and persist state
Text and per-page title missingprerender: false on Routes and HeadOutletRemove it, or scope it to non-public components
loading-progress foundStandalone Blazor WebAssemblyMove public pages to a Blazor Web App
Text present but only a "Loading..." placeholder in placeStreaming renderingCheck where the streamed text lands, or avoid streaming for key facts

Compare with the rendered DOM in Search Console's URL Inspection tool to see the gap between the two versions; raw vs rendered HTML explains why both matter.

Frequently asked questions

Is Blazor bad for SEO?

No. A Blazor Web App with the default settings sends server-rendered HTML, either through static SSR or prerendering of interactive components. Problems come from disabling prerendering, loading content after render, or using standalone WebAssembly for public pages.

Does Blazor Server work for crawlers?

The prerendered first response does. Anything that appears later travels over the SignalR circuit, and Google says Googlebot does not support WebSockets, so keep indexable text in the prerendered markup.

Can I prerender a standalone Blazor WebAssembly app?

Microsoft's prerendering documentation covers Blazor Web Apps and Blazor Server apps, not standalone WebAssembly. The setup Microsoft documents for this is a Blazor Web App using the Interactive WebAssembly or Auto render mode, which prerenders on the server by default.

Why does my data load twice with prerendering?

OnInitializedAsync runs once during prerendering and again when the component becomes interactive. Persist the prerendered state with [PersistentState] in .NET 10 and later, or PersistentComponentState in .NET 8 and 9.

Will prerendering get my Blazor site cited by AI assistants?

No change can promise that. Prerendering removes a technical barrier so crawlers can read the text; whether an assistant uses or cites a page depends on many factors outside your HTML.

Check what crawlers receive from your Blazor pages

Run the three curl checks on your home page, one product or service page and one article, since render modes are often set per page. To test a single URL without a terminal, the free check shows whether the main text is in the raw HTML, with no account needed.

Filed under Rendering and content. Topics: blazor, ssr, rendering, raw-html, javascript