Blazorade.StaticPages 1.0.0-rc.1

Blazorade Static Pages

Blazorade Static Pages is a library for generating crawler-visible static HTML from ordinary Blazor WebAssembly applications at build time. It works with standard Blazor routing, layouts, navigation, and components, allowing the generated static output to be enhanced with normal Blazor interactivity at runtime.

The application remains the source of truth. Static pages are declared with a source-analysis attribute and marker components:

Read Adding static page generation to Blazor WebAssembly for an introduction to using the library.

• StaticPageAttribute identifies a static page and controls sitemap inclusion.
• StaticMetadata defines the page metadata used for generated HTML and optional live browser rendering.
• StaticContent exposes a safe static representation from a reusable component.
• InteractiveContent excludes runtime-only content from generated HTML while leaving it available to the running application.

The package also integrates the static-page generator into the consuming application's build and publish process. Generated output can include static HTML pages, canonical metadata, sitemap entries, and static-hosting route configuration.

Static pages are generated by analyzing the consuming application's Razor source at build time. The generator does not execute the application, use HtmlRenderer, or depend on runtime render markers. StaticMetadata.RenderInBrowser controls whether metadata is emitted during live browser rendering; static analysis includes metadata regardless of that setting.

Getting started

Add the Blazorade.StaticPages package to a Blazor WebAssembly application. Declare static content in a routable component:

@page "/products"

@attribute [StaticPage]

<StaticMetadata Title="Products" Description="Explore our products." />

<StaticContent>
    <h1>Products</h1>
    <p>Browse our product catalogue.</p>

    <InteractiveContent>
        <ProductConfigurator />
    </InteractiveContent>
</StaticContent>

The optional Date parameter accepts a value parseable as a DateTimeOffset:

<StaticMetadata Title="Products" Date="2026-05-10T14:30:00+02:00" />

<StaticContent>
  <h1>Products</h1>
</StaticContent>

Values without a time-zone offset are interpreted as UTC. The generated page contains a concise article:published_time value and a date-only <meta name="date"> value. Invalid date values produce a build warning and are omitted from the generated metadata.

For reusable components, place the static representation inside StaticContent. Runtime-only descendants should be placed inside InteractiveContent.

To configure the public site URL used for canonical URLs and sitemap generation, add blazorade.config.json next to the consuming application's project file:

{
  "staticPages": {
    "siteUrl": "https://www.example.com"
  }
}

Configuration-specific overrides are supported using the active MSBuild configuration. For example, blazorade.config.Release.json overrides blazorade.config.json for Release builds, and custom configurations such as Pre-Prod use blazorade.config.Pre-Prod.json. The files are merged recursively, with values from the configuration-specific file taking precedence.

Static page selection and compile-time values

Only routable components marked with @attribute [StaticPage] are included in static page generation. Each static routable component must contain exactly one StaticMetadata component. Other routable components remain normal interactive Blazor pages and are ignored by the generator. It is valid for an application to have no static pages.

The Title and other static page metadata values must be resolvable at build time. String constants and string-initialized variables can be declared in the Razor component's @code block or in its matching .razor.cs code-behind file:

@page "/"

@code {
  private const string Title = "My site";
}

@attribute [StaticPage]

<StaticMetadata Title="@Title" />

<StaticContent>
  <PageTitle>@Title</PageTitle>
  <h1>@Title</h1>
</StaticContent>

The generator does not execute application code. Values that depend on services, lifecycle methods, property getters, authentication state, or other runtime data cannot be used as static metadata or content.

Release notes

v1.0.0-rc.1

• Generated pages now receive a <main> element when neither the HTML template nor static content defines one.

Preview releases

Versions v1.0.0-preview.1 through v1.0.0-preview.13 established the initial static-page generation contract and build integration:

• Added StaticPageAttribute, StaticMetadata, StaticContent, and InteractiveContent for explicitly declaring static page output.
• Added source-only Razor analysis and deterministic compile-time value resolution without executing application code or runtime rendering.
• Added static page discovery and HTML generation for Blazor WebAssembly applications, including metadata, canonical URLs, sitemap generation, and static-hosting route configuration.
• Added support for compile-time constants, variables, qualified references, string concatenation, parenthesized expressions, and supported date values in static content and metadata.
• Added build-configuration-specific configuration files with recursive merging over the default configuration.
• Added optional live metadata rendering through StaticMetadata.RenderInBrowser while keeping generated output independent of browser state.
• Added automatic generator and generator-host rebuilding and NuGet packaging under tools/net10.0.