blazor
- Repo stars 423
- Author repo dotnet-skills
- Domain
- Design
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @managedcode · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Blazor
## Trigger On
- building interactive web UIs with C# instead of JavaScript
- choosing between Server, WebAssembly, or Auto render modes
- designing component hierarchies and state management
- handling prerendering and hydration
- integrating with JavaScript when necessary
## Documentation
- [Blazor Overview](https://learn.microsoft.com/en-us/aspnet/core/blazor/?view=aspnetcore-10.0)
- [Render Modes](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-10.0)
- [Performance Best Practices](https://learn.microsoft.com/en-us/aspnet/core/blazor/performance?view=aspnetcore-10.0)
- [State Management](https://learn.microsoft.com/en-us/aspnet/core/blazor/state-management?view=aspnetcore-10.0)
- [JS Interop](https://learn.microsoft.com/en-us/aspnet/core/blazor/javascript-interoperability/?view=aspnetcore-10.0)
### References
- [patterns.md](references/patterns.md) - Detailed component patterns, state management strategies, and JS interop techniques
- [anti-patterns.md](references/anti-patterns.md) - Common Blazor mistakes and how to avoid them
## Render Modes (.NET 8+)
| Mode | Where It Runs | Best For |
|------|---------------|----------|
| `Static` | Server (no interactivity) | SEO pages, marketing content |
| `InteractiveServer` | Server via SignalR | Real-time apps, thin clients |
| `InteractiveWebAssembly` | Browser via WASM | Offline-capable, client-heavy |
| `InteractiveAuto` | Server first, then WASM | Best of both worlds |
### Applying Render Modes
```razor
@* Per-component *@
@rendermode InteractiveServer
@* Or in App.razor for global *@
<Routes @rendermode="InteractiveAuto" />
```
### InteractiveAuto Architecture
```
First Request:
Browser → Server (Interactive Server) → Fast response
Subsequent Requests:
Browser → WASM (downloaded in background) → No server needed
```
## Workflow
1. **Choose render mode based on requirements:**
- Need SEO? Start with Static or prerendering
- Need real-time? Use InteractiveServer
- Need offline? Use InteractiveWebAssembly
- Want both? Use InteractiveAuto
2. **Design components for reusability:**
- Small, focused components
- Parameters for customization
- Events for communication
3. **Handle state correctly:**
- Component state lives in component
- Shared state via services (DI)
- Persist state across prerender with `[PersistentState]`
4. **Validate in both environments** (for Auto mode)
## Component Patterns
### Basic Component
```razor
@* Counter.razor *@
<button @onclick="IncrementCount">
Clicked @count times
</button>
@code {
private int count = 0;
[Parameter]
public int InitialCount { get; set; } = 0;
protected override void OnInitialized()
{
count = InitialCount;
}
private void IncrementCount() => count++;
}
```
### Parameter and Event Callbacks
```razor
@* Parent.razor *@
<ChildComponent Value="@value" ValueChanged="@OnValueChanged" />
@* ChildComponent.razor *@
@code {
[Parameter] public string Value { get; set; } = "";
[Parameter] public EventCallback<string> ValueChanged { get; set; }
private async Task UpdateValue(string newValue)
{
await ValueChanged.InvokeAsync(newValue);
}
}
```
### State Persistence (.NET 8+)
```razor
@* Prevents double-fetch during prerender + hydration *@
@code {
[PersistentState]
public List<Product> Products { get; set; } = [];
protected override async Task OnInitializedAsync()
{
// Only fetches once, persisted across prerender
Products ??= await Http.GetFromJsonAsync<List<Product>>("api/products");
}
}
```
## Data Access Pattern for Auto Mode
```csharp
// Shared interface
public interface IProductService
{
Task<List<Product>> GetProductsAsync();
}
// Server implementation (direct DB access)
public class ServerProductService : IProductService
{
private readonly AppDbContext _db;
public async Task<List<Product>> GetProductsAsync()
=> await _db.Products.ToListAsync();
}
// Client implementation (HTTP call)
public class ClientProductService : IProductService
{
private readonly HttpClient _http;
public async Task<List<Product>> GetProductsAsync()
=> await _http.GetFromJsonAsync<List<Product>>("api/products");
}
// Registration
// Server: builder.Services.AddScoped<IProductService, ServerProductService>();
// Client: builder.Services.AddScoped<IProductService, ClientProductService>();
```
## Anti-Patterns to Avoid
| Anti-Pattern | Why It's Bad | Better Approach |
|--------------|--------------|-----------------|
| Large components | Hard to maintain, slow renders | Split into smaller components |
| Direct DB access in WASM | No DB in browser | Use HTTP API |
| Ignoring `ShouldRender` | Unnecessary re-renders | Override when needed |
| Sync JS interop in Server | Blocks SignalR circuit | Use `IJSRuntime` async |
| No error boundaries | One error crashes app | Use `<ErrorBoundary>` |
| Forgetting prerender state | Double API calls | Use `[PersistentState]` |
## Performance Best Practices
1. **Virtualize large lists:**
```razor
<Virtualize Items="@products" Context="product">
<ProductCard Product="@product" />
</Virtualize>
```
2. **Use `@key` for list diffing:**
```razor
@foreach (var item in items)
{
<ItemComponent @key="item.Id" Item="@item" />
}
```
3. **Debounce rapid events:**
```csharp
private Timer? _debounceTimer;
private void OnInput(ChangeEventArgs e)
{
_debounceTimer?.Dispose();
_debounceTimer = new Timer(_ => InvokeAsync(DoSearch), null, 300, Timeout.Infinite);
}
```
4. **Lazy load assemblies (WASM):**
```csharp
var assemblies = await LazyAssemblyLoader
.LoadAssembliesAsync(["MyHeavyFeature.wasm"]);
```
## JS Interop
### Calling JavaScript from C#
```csharp
@inject IJSRuntime JS
await JS.InvokeVoidAsync("alert", "Hello from Blazor!");
var result = await JS.InvokeAsync<string>("prompt", "Enter name:");
```
### Calling C# from JavaScript
```csharp
[JSInvokable]
public static string GetMessage() => "Hello from C#!";
```
```javascript
DotNet.invokeMethodAsync('MyAssembly', 'GetMessage')
.then(result => console.log(result));
```
## Deliver
- interactive Blazor components with appropriate render mode
- efficient state management and data flow
- proper handling of prerendering scenarios
- performant list rendering with virtualization
## Validate
- components render correctly in chosen mode
- state persists correctly across prerender/hydration
- no unnecessary re-renders (check with browser tools)
- JS interop works in both Server and WASM
- error boundaries catch component failures
- Auto mode works in both environments
Sections and files
Listed in source order.
sections -> Trigger On → Documentation → References → Render Modes (.NET 8+) → Applying Render Modes → InteractiveAuto Architecture
terms -> Choose render mode based on requirements · Design components for reusability · Handle state correctly · Validate in both environments · Virtualize large lists · Use @key for list diffing · Debounce rapid events · Lazy load assemblies (WASM)
files/cmd -> Static · InteractiveServer · InteractiveWebAssembly · InteractiveAuto · [PersistentState] · ShouldRender · IJSRuntime · <ErrorBoundary>
body sha256 -> 5607d277cf09
Trigger On
building interactive web UIs with C# instead of JavaScript choosing between Server, WebAssembly, or Auto render modes designing component hierarchies and state management handling prerendering and hydration integrating with JavaScript when necessary
Documentation
Blazor Overview Render Modes Performance Best Practices State Management JS Interop
References
patterns.md - Detailed component patterns, state management strategies, and JS interop techniques anti-patterns.md - Common Blazor mistakes and how to avoid them
Render Modes (.NET 8+)
Mode · Where It Runs · Best For
Static· Server (no interactivity) · SEO pages, marketing contentInteractiveServer· Server via SignalR · Real-time apps, thin clientsInteractiveWebAssembly· Browser via WASM · Offline-capable, client-heavyInteractiveAuto· Server first, then WASM · Best of both worldsWorkflow
Choose render mode based on requirements: Need SEO? Start with Static or prerendering Need real-time? Use InteractiveServer Need offline? Use InteractiveWebAssembly Want both? Use InteractiveAuto