Blazor Development Knowledge Base

Reference Documentation

Read the relevant docs based on your task:

Always Read First

• ${CLAUDE_PLUGIN_ROOT}/docs/01-render-modes.md — The foundation. Understand which mode you're in before writing any code.

Core Topics (read as needed)

• ${CLAUDE_PLUGIN_ROOT}/docs/02-component-lifecycle.md — OnInitialized, OnAfterRender, disposal, prerendering double-execution
• ${CLAUDE_PLUGIN_ROOT}/docs/03-forms-validation.md — EditForm, input components, DataAnnotations, custom validation
• ${CLAUDE_PLUGIN_ROOT}/docs/04-state-management.md — StateHasChanged, cascading values, PersistentComponentState, browser storage
• ${CLAUDE_PLUGIN_ROOT}/docs/05-components.md — Parameters, RenderFragment, generics, DynamicComponent, Virtualize, @key, @ref
• ${CLAUDE_PLUGIN_ROOT}/docs/06-js-interop.md — IJSRuntime, module imports, ElementReference, calling .NET from JS, disposal
• ${CLAUDE_PLUGIN_ROOT}/docs/07-routing-navigation.md — @page, route params, NavigationManager, query strings, NavLink
• ${CLAUDE_PLUGIN_ROOT}/docs/08-styling.md — CSS isolation (.razor.css), ::deep, conditional classes, design tokens, theming
• ${CLAUDE_PLUGIN_ROOT}/docs/09-dependency-injection.md — Service lifetimes, @inject, OwningComponentBase, HttpClient patterns
• ${CLAUDE_PLUGIN_ROOT}/docs/10-event-handling-performance.md — Event handling, debouncing, Virtualize, modals, toasts, file upload
• ${CLAUDE_PLUGIN_ROOT}/docs/11-authentication-authorization.md — AuthorizeView, [Authorize], HttpContext pain points, Identity UI

Design & Aesthetics

• ${CLAUDE_PLUGIN_ROOT}/docs/12-design-aesthetics.md — Typography, color systems, motion/animation, spatial composition, anti-patterns, Blazor-specific design tips

Security & Authentication

• ${CLAUDE_PLUGIN_ROOT}/docs/13-security.md — CSRF/antiforgery, XSS prevention, Content Security Policy, secure token storage, BFF pattern, SignalR circuit security
• ${CLAUDE_PLUGIN_ROOT}/docs/14-external-authentication-providers.md — OAuth/OIDC setup for Google, Microsoft/Entra ID, GitHub, Discord; claims mapping, account linking
• ${CLAUDE_PLUGIN_ROOT}/docs/15-two-factor-authentication.md — TOTP authenticator apps, QR code generation (QRCoder server-side, qrcodejs client-side), recovery codes, setup flow

Logging

• ${CLAUDE_PLUGIN_ROOT}/docs/16-logging.md — ILogger in components, prerender noise avoidance, ErrorBoundary logging, circuit diagnostics, WASM log relay pattern. For Serilog, Elastic APM, and OpenTelemetry details, see the observability-skill plugin.

Critical Rules (Common Mistakes)

1. No @rendermode = Static SSR — Event handlers (@onclick, @oninput) are INERT. Add a render mode. Check App.razor first: <Routes @rendermode="InteractiveServer" /> must be set, or per-page @rendermode directives do nothing.
2. JS interop only in OnAfterRender — Not available during OnInitialized or prerendering.
3. OnInitializedAsync runs TWICE with prerendering — Use [PersistentState] (.NET 10+) or PersistentComponentState.
4. Always dispose: IJSObjectReference, DotNetObjectReference, event subscriptions, CancellationTokenSource.
5. HttpContext is NOT available in interactive render modes — Use AuthenticationStateProvider instead.
6. Identity pages MUST be Static SSR — They need HttpContext for cookies.
7. Singleton services on Blazor Server leak between users — Use AddScoped.
8. StateHasChanged from background threads — Wrap in InvokeAsync(StateHasChanged).
9. FormName is required for SSR forms — Without it, Blazor can't dispatch the POST.
10. Cascading values don't cross render mode boundaries — Use AddCascadingValue in DI instead.