Create Blazor Project

Create a Blazor Web App

Before You Start — Gather Requirements

If the user's request doesn't make the following clear, ask before scaffolding:

1. What does the app do? List the main screens/features (e.g., "product catalog with search and shopping cart"). 2. What kind of interactivity is needed? Displaying data and forms? Real-time updates? Offline support? Rich drag-and-drop UI? 3. Deployment environment? Internet-facing? Intranet? Mobile users on slow connections? 4. Authentication needed? Anonymous? Individual accounts? Organizational (Azure AD)?

Pick the Right Interactivity Level

Blazor render modes are a progression scale. Start at the simplest level that satisfies the requirements and only move up when there's a concrete reason.

Static SSR ──→ SSR + Enhanced Nav ──→ Interactive Server ──→ Interactive WebAssembly
 simplest                                                           most complex

Decision Rules

Default recommendation: Start with -int Server (per-page). It covers the vast majority of apps. Upgrade to global or WebAssembly only when a specific requirement demands it.

Auto Mode Constraints

Auto mode means your component code runs on the server first, then in the browser on subsequent visits. This creates real constraints:

• All interactive components must live in the `.Client` project — same as WebAssembly.
• No direct server access from interactive components — no EF DbContext, no file system, no server-only services. All data access must go through HTTP APIs.
• Both `Program.cs` files must register matching services — the server and client DI containers must both provide implementations for any service an interactive component injects.
• Code must not assume its execution environment — no HttpContext access, no browser-only APIs without RendererInfo guards.
• Test in both modes — a component that works on Server during development may break on WebAssembly in production (second visit). Test both paths.

Don'ts

• Don't pick WebAssembly "because it's cool" — it adds a .Client project, forces API-mediated data access, and downloads ~10MB to the browser on first visit.
• Don't pick Auto unless you can articulate why Server alone and WebAssembly alone are both insufficient.
• Don't pick global interactivity for apps where most pages are read-only content — per-page keeps the static pages fast and reduces server memory.

Scaffold the Project

Static SSR Only (display data + simple forms)

dotnet new blazor -o {AppName} -int None

No interactive runtime. Enhanced navigation enabled by default via blazor.web.js.

Interactive Server, Per-Page (recommended default)

dotnet new blazor -o {AppName} -int Server

Pages are static by default. Add @rendermode InteractiveServer to components that need interactivity.

Interactive Server, Global

dotnet new blazor -o {AppName} -int Server -ai

All pages interactive via <Routes @rendermode="InteractiveServer" /> in App.razor.

Interactive WebAssembly, Per-Page

dotnet new blazor -o {AppName} -int WebAssembly

Creates {AppName} (server) and {AppName}.Client (WebAssembly) projects. Interactive components must live in .Client.

Interactive WebAssembly, Global

dotnet new blazor -o {AppName} -int WebAssembly -ai

Interactive Auto, Per-Page

dotnet new blazor -o {AppName} -int Auto

Interactive Auto, Global

dotnet new blazor -o {AppName} -int Auto -ai

With Authentication

Append -au Individual to any command above:

dotnet new blazor -o {AppName} -int Server -au Individual

-au Individual scaffolds ASP.NET Core Identity with SQLite (CLI) or SQL Server (Visual Studio). Identity pages are always static SSR — they do not use interactive render modes.

The blazor template only supports -au Individual. For organizational auth (Microsoft Entra ID, Azure AD B2C), scaffold with -au Individual first, then replace the Identity provider with Microsoft.Identity.Web / OIDC middleware and configure the tenant in appsettings.json.

What the Template Creates

Single project (Static SSR, Server)

{AppName}/
├── Components/
│   ├── App.razor              # Root component — sets <HeadOutlet> and <Routes>
│   ├── Routes.razor           # Wraps <Router> with route discovery
│   ├── Layout/
│   │   ├── MainLayout.razor   # App shell with nav, header, footer
│   │   └── MainLayout.razor.css
│   └── Pages/
│       └── Home.razor         # @page "/" — first page
├── Program.cs                 # Service registration and middleware
├── wwwroot/                   # Static files (CSS, images)
└── {AppName}.csproj

Two projects (WebAssembly, Auto)

{AppName}/                     # Server project — hosts the app
├── Components/                # Server-only components (static SSR pages, layouts)
│   ├── App.razor
│   ├── Routes.razor
│   └── Layout/
├── Program.cs                 # Server Program.cs
└── {AppName}.Client/          # Client project — WebAssembly components
    ├── Pages/                 # Interactive components go HERE
    ├── Program.cs             # Client Program.cs
    └── _Imports.razor

Rule: Components using InteractiveWebAssembly or InteractiveAuto must live in the .Client project. They can reference shared code but cannot reference server-only types (EF DbContext, server-side services).

Program.cs Wiring

The template generates the correct Program.cs for the chosen mode. Verify these registrations match your intent:

Static SSR Only

// Program.cs
builder.Services.AddRazorComponents();

// ...

app.MapRazorComponents<App>();

Server (per-page or global)

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// ...

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

WebAssembly (per-page or global)

// Server Program.cs
builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

// ...

app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof({AppName}.Client._Imports).Assembly);

// Client Program.cs
builder.Services.AddAuthorizationCore();
// Register HttpClient, other client-side services

Create Project AGENTS.md

After scaffolding, create an AGENTS.md file in the project root (next to the .csproj). For two-project setups, put it in the server project root.

Pick the matching template from assets/agents-md/ based on the chosen mode:

Copy the template contents into the project's AGENTS.md and replace every {AppName} with the actual project name. If auth was scaffolded (-au Individual), add an ## Authentication section noting that ASP.NET Core Identity is configured and that Identity pages under Components/Account/ are always static SSR — do not add @rendermode to them.

After scaffolding the project and creating AGENTS.md, continue implementing the features the user requested. Remove default template pages (Counter, Weather) and replace them with the actual application pages.

Auto (per-page or global)

// Server Program.cs
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

// ...

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof({AppName}.Client._Imports).Assembly);

App.razor — Global vs Per-Page

The difference between global and per-page interactivity is entirely in App.razor:

Per-page (default)

<!DOCTYPE html>
<html>
<head>
    <HeadOutlet />
</head>
<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

No @rendermode on <Routes> or <HeadOutlet>. Individual pages opt in.

Global

<!DOCTYPE html>
<html>
<head>
    <HeadOutlet @rendermode="InteractiveServer" />
</head>
<body>
    <Routes @rendermode="InteractiveServer" />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

Replace InteractiveServer with InteractiveWebAssembly or InteractiveAuto as appropriate.

After Scaffolding

1. Verify it builds: dotnet build 2. Run it: dotnet run (in the server project if two-project setup) 3. Add your first page: Create a .razor file in Components/Pages/ (server project) or Pages/ (.Client project for WebAssembly components)

Don'ts

• Don't use dotnet new blazorwasm — that creates a standalone WebAssembly SPA without server-side rendering. Use the blazor template with -int WebAssembly instead.
• Don't manually add AddInteractiveServerComponents() to a project created with -int None and expect it to work — you also need the @rendermode directives and potentially App.razor changes. Re-scaffold if the mode needs to change fundamentally.
• Don't put WebAssembly-targeted components in the server project — they'll work during prerender but fail after handoff.

{AppName}

Rendering configuration

This project uses global Interactive Auto with prerendering. Created with dotnet new blazor -int Auto -ai.

On a user's first visit, components render via Interactive Server (SignalR). On subsequent visits the cached WebAssembly runtime takes over and interactions run entirely in the browser.

Project structure

• {AppName} (server): Hosts the Blazor app, serves static files, API endpoints.
• {AppName}.Client (WebAssembly): All interactive UI components. Run on server first, then browser.

Adding new components

• Interactive components MUST go in the .Client project, not the server project.
• New pages go in {AppName}.Client/Pages/.
• All pages are already interactive (global mode). No need to add @rendermode to individual components.
• Server-only static components (e.g., error pages) belong in the server Components/ folder.

Data access

Interactive components cannot access the database directly. Use this pattern: 1. Define an interface in the .Client project (e.g., IDataService). 2. In the .Client project, implement it using HttpClient to call server APIs. 3. In the server project, implement it using direct data access (EF Core DbContext, etc.). 4. Register the client implementation in the client Program.cs and the server implementation in the server Program.cs. 5. Expose server data through minimal API endpoints (e.g., app.MapGet(...)) that the client implementation calls. 6. If the page requires authorization, apply the same auth policy to both the Blazor page (@attribute [Authorize]) and the minimal API endpoint (.RequireAuthorization()).

Service registration

• Both server and client Program.cs must register matching services for any DI used by interactive components.
• Server-only services (EF Core, Identity) stay in the server Program.cs only.

Environment constraints

• Code must work in both server and browser execution environments.
• Do not use HttpContext or browser-only JS APIs without RendererInfo guards.
• The .NET runtime (~10 MB) is downloaded to the browser on first visit and cached — subsequent visits use WebAssembly.

Don'ts

• Don't put interactive components in the server project — they work during prerender but fail after WebAssembly handoff.
• Don't inject DbContext or server-only services in .Client project components — use HTTP APIs instead.
• Don't assume execution environment — the same component runs on Server first, then WebAssembly later. Test both.
• Don't add @rendermode InteractiveAuto to pages — global interactivity is already configured in App.razor.
• Don't add @rendermode to Identity/Account pages if auth is configured — they must stay static SSR.

{AppName}

Rendering configuration

This project uses per-page Interactive Auto with prerendering. Created with dotnet new blazor -int Auto.

Pages are static SSR by default. Components that add @rendermode InteractiveAuto use Server on first visit, then WebAssembly on subsequent visits once the runtime is cached.

Project structure

• {AppName} (server): Hosts the Blazor app, serves static files, API endpoints. Static SSR pages and layouts live here.
• {AppName}.Client (WebAssembly): Interactive components that run on server first, then browser.

Adding new components

• Interactive components MUST go in the .Client project, not the server project.
• New pages in the server Components/Pages/ are static SSR by default.
• Only add @rendermode InteractiveAuto to components that need client-side interactivity.
• Static pages can use standard HTML forms with [SupplyParameterFromForm] — no interactivity needed.

Data access

Interactive components cannot access the database directly. Use this pattern: 1. Define an interface in the .Client project (e.g., IDataService). 2. In the .Client project, implement it using HttpClient to call server APIs. 3. In the server project, implement it using direct data access (EF Core DbContext, etc.). 4. Register the client implementation in the client Program.cs and the server implementation in the server Program.cs. 5. Expose server data through minimal API endpoints (e.g., app.MapGet(...)) that the client implementation calls. 6. If the page requires authorization, apply the same auth policy to both the Blazor page (@attribute [Authorize]) and the minimal API endpoint (.RequireAuthorization()).

Service registration

• Both server and client Program.cs must register matching services for any DI used by interactive components.
• Server-only services (EF Core, Identity) stay in the server Program.cs only.

Environment constraints

• Code must work in both server and browser execution environments.
• Do not use HttpContext or browser-only JS APIs without RendererInfo guards.
• The .NET runtime (~10 MB) is downloaded to the browser on first visit and cached — subsequent visits use WebAssembly.
• Static SSR pages in the server project have full server access.

Don'ts

• Don't put interactive components in the server project — they work during prerender but fail after WebAssembly handoff.
• Don't inject DbContext or server-only services in .Client project components — use HTTP APIs instead.
• Don't assume execution environment — the same component runs on Server first, then WebAssembly later. Test both.
• Don't set @rendermode on <Routes> in App.razor — that makes it global. Per-page mode means individual components opt in.
• Don't add @rendermode to Identity/Account pages if auth is configured — they must stay static SSR.

{AppName}

Rendering configuration

This project uses global Interactive Server with prerendering. Created with dotnet new blazor -int Server -ai.

All pages are interactive by default via <Routes @rendermode="InteractiveServer" /> in App.razor.

Adding new components

• Create new .razor files in Components/Pages/ for routable pages or Components/ for shared components.
• All pages are already interactive. No need to add @rendermode to individual components.

Data access

• Components can inject services directly — EF Core DbContext, file system, server-only APIs. No HTTP API layer needed.

Environment constraints

• Components run on the server via SignalR.
• HttpContext is NOT available in interactive components — it's only available during the initial static prerender.
• Browser APIs are not directly available — use IJSRuntime interop.
• Every connected user holds a SignalR circuit on the server.

Don'ts

• Don't add @rendermode InteractiveServer to pages — global interactivity is already configured in App.razor.
• Don't add @rendermode to Identity/Account pages if auth is configured — they must stay static SSR.
• Don't inject HttpContext in interactive components — it's not available during SignalR circuit lifetime.
• Don't use browser APIs (localStorage, DOM) directly — use IJSRuntime interop instead.

{AppName}

Rendering configuration

This project uses per-page Interactive Server with prerendering. Created with dotnet new blazor -int Server.

Pages are static SSR by default. Only components that explicitly add @rendermode InteractiveServer become interactive.

Adding new components

• Create new .razor files in Components/Pages/ for routable pages or Components/ for shared components.
• New pages are static SSR by default. Only add @rendermode InteractiveServer to components that need client-side behavior (live search, real-time updates, complex form interactions).
• Static pages can use standard HTML forms with [SupplyParameterFromForm] — no interactivity needed.

Data access

• Components can inject services directly — EF Core DbContext, file system, server-only APIs. No HTTP API layer needed.

Environment constraints

• Interactive components run on the server via SignalR. HttpContext is available in static components but NOT in interactive components during the SignalR circuit lifetime.
• Static pages can access HttpContext via [CascadingParameter].
• Browser APIs are not directly available — use IJSRuntime interop in interactive components.

Don'ts

• Don't add @rendermode InteractiveServer to every page — keep read-only content static for performance and lower server memory.
• Don't add @rendermode to Identity/Account pages if auth is configured — they must stay static SSR.
• Don't inject HttpContext in interactive components — it's not available during SignalR circuit lifetime.
• Don't set @rendermode on <Routes> in App.razor — that makes it global. Per-page mode means individual components opt in.

{AppName}

Rendering configuration

This project uses static server-side rendering with no interactivity. Created with dotnet new blazor -int None.

Enhanced navigation via blazor.web.js is enabled by default, making page transitions feel instant without any interactive runtime.

Adding new components

• Create new .razor files in Components/Pages/ for routable pages or Components/ for shared components.
• Do NOT add @rendermode to any component — this project has no interactive runtime configured.
• Forms use standard HTML POST with [SupplyParameterFromForm] for model binding.
• Query string parameters use [SupplyParameterFromQuery].

Data access

• Components can inject services directly — EF Core DbContext, file system, server-only APIs. No HTTP API layer needed.

Environment constraints

• No SignalR circuits, no WebAssembly. All rendering happens on the server.
• Forms use HTML POST with [SupplyParameterFromForm] and require <AntiforgeryToken />.
• HttpContext is available via [CascadingParameter].
• Browser APIs (JS interop) are not available.

Don'ts

• Don't add @rendermode InteractiveServer or any interactive render mode — the project has no interactive runtime registered.
• Don't add AddInteractiveServerComponents() to Program.cs without also updating App.razor.
• Don't use @onclick or other event handlers — they require an interactive render mode. Use form submissions and links for user actions.
• Don't use IJSRuntime — there is no interactive runtime to execute JavaScript calls.

{AppName}

Rendering configuration

This project uses global Interactive WebAssembly with prerendering. Created with dotnet new blazor -int WebAssembly -ai.

All pages are interactive by default via <Routes @rendermode="InteractiveWebAssembly" /> in App.razor. Components run entirely in the browser after the initial prerender.

Project structure

• {AppName} (server): Hosts the Blazor app, serves static files, API endpoints.
• {AppName}.Client (WebAssembly): All interactive UI components. Runs entirely in the browser.

Adding new components

• All interactive components MUST go in the .Client project, not the server project.
• New pages go in {AppName}.Client/Pages/.
• All pages are already interactive. No need to add @rendermode to individual components.

Data access

Interactive components cannot access the database directly. Use this pattern: 1. Define an interface in the .Client project (e.g., IDataService). 2. In the .Client project, implement it using HttpClient to call server APIs. 3. In the server project, implement it using direct data access (EF Core DbContext, etc.). 4. Register the client implementation in the client Program.cs and the server implementation in the server Program.cs. 5. Expose server data through minimal API endpoints (e.g., app.MapGet(...)) that the client implementation calls. 6. If the page requires authorization, apply the same auth policy to both the Blazor page (@attribute [Authorize]) and the minimal API endpoint (.RequireAuthorization()).

Service registration

• Client-side services go in {AppName}.Client/Program.cs.
• Server-side services go in {AppName}/Program.cs.

Environment constraints

• Components run in the browser via WebAssembly. No HttpContext, no server file system.
• All data access goes through HttpClient calls to server API endpoints.
• The .NET runtime (~10 MB) is downloaded to the browser on first visit and cached.

Don'ts

• Don't put interactive components in the server project — they work during prerender but fail after WebAssembly handoff.
• Don't inject DbContext or server-only services in .Client project components — use HTTP APIs instead.
• Don't add @rendermode InteractiveWebAssembly to pages — global interactivity is already configured in App.razor.
• Don't add @rendermode to Identity/Account pages if auth is configured — they must stay static SSR.

{AppName}

Rendering configuration

This project uses per-page Interactive WebAssembly with prerendering. Created with dotnet new blazor -int WebAssembly.

Pages are static SSR by default. Only components that explicitly add @rendermode InteractiveWebAssembly become interactive and run in the browser.

Project structure

• {AppName} (server): Hosts the Blazor app, serves static files, API endpoints. Static SSR pages and layouts live here.
• {AppName}.Client (WebAssembly): Interactive components that run in the browser.

Adding new components

• Interactive components MUST go in the .Client project, not the server project.
• New pages in the server Components/Pages/ are static SSR by default.
• Only add @rendermode InteractiveWebAssembly to components that need client-side interactivity.
• Static pages can use standard HTML forms with [SupplyParameterFromForm] — no interactivity needed.

Data access

Interactive components cannot access the database directly. Use this pattern: 1. Define an interface in the .Client project (e.g., IDataService). 2. In the .Client project, implement it using HttpClient to call server APIs. 3. In the server project, implement it using direct data access (EF Core DbContext, etc.). 4. Register the client implementation in the client Program.cs and the server implementation in the server Program.cs. 5. Expose server data through minimal API endpoints (e.g., app.MapGet(...)) that the client implementation calls. 6. If the page requires authorization, apply the same auth policy to both the Blazor page (@attribute [Authorize]) and the minimal API endpoint (.RequireAuthorization()).

Service registration

• Client-side services go in {AppName}.Client/Program.cs.
• Server-side services go in {AppName}/Program.cs.

Environment constraints

• Interactive components run in the browser via WebAssembly. No HttpContext, no server file system.
• Static SSR pages in the server project have full server access.
• The .NET runtime (~10 MB) is downloaded to the browser on first visit and cached.

Don'ts

• Don't put interactive components in the server project — they work during prerender but fail after WebAssembly handoff.
• Don't inject DbContext or server-only services in .Client project components — use HTTP APIs instead.
• Don't set @rendermode on <Routes> in App.razor — that makes it global. Per-page mode means individual components opt in.
• Don't add @rendermode to Identity/Account pages if auth is configured — they must stay static SSR.