Always use collocated .razor.js files with export — never global window.* functions or <script> tags.
// ChartPanel.razor.js — placed next to ChartPanel.razor\nexport function initialize(canvas, dotNetRef) { /* ... */ }\nexport function updateData(points) { /* ... */ }\nexport function dispose() { /* ... */ }\nImport paths: same project = \"./Components/ChartPanel.razor.js\", RCL = \"./_content/{AssemblyName}/...\".
All JS interop must happen in OnAfterRenderAsync or event handlers — never in OnInitialized, OnParametersSet, or constructors. JS is not available during server prerendering.
Use a typed interop wrapper (see Section 4) — never call InvokeAsync/InvokeVoidAsync with raw string literals:
private ChartInterop? _chart;\n\nprotected override async Task OnAfterRenderAsync(bool firstRender)\n{\n if (firstRender)\n {\n _chart = new ChartInterop(JS);\n await _chart.InitializeAsync(_canvasRef);\n }\n}\nParameter changes: set a flag in OnParametersSet, apply in OnAfterRenderAsync:
private bool _dataChanged;\n\nprotected override void OnParametersSet() => _dataChanged = true;\n\nprotected override async Task OnAfterRenderAsync(bool firstRender)\n{\n if (firstRender) { /* init */ }\n else if (_dataChanged && _chart is not null)\n {\n _dataChanged = false;\n await _chart.UpdateDataAsync(DataPoints);\n }\n}\nEach JS interop call crosses the .NET-to-JS boundary (and in Blazor Server, the SignalR circuit). Batching applies in both directions — .NET→JS and JS→.NET.
\nIf the C# side makes two or more JS calls in a row, combine them into one JS function:
\n// ❌ Two round-trips — theme and locale are always applied together\nawait _module.InvokeVoidAsync(\"applyTheme\", theme);\nawait _module.InvokeVoidAsync(\"applyLocale\", locale);\n\n// ❌ Result of one call feeds into another — both can stay in JS\nvar token = await _module.InvokeAsync<string>(\"createAccessToken\");\nawait _module.InvokeVoidAsync(\"storeToken\", token);\n// ✅ One call applies both — no data dependency, no reason for two trips\nexport function applyPreferences(theme, locale) {\n document.documentElement.dataset.theme = theme;\n document.documentElement.lang = locale;\n}\n\n// ✅ Chain stays in JS — the token never needs to cross the boundary\nexport function createAndStoreToken() {\n const token = crypto.randomUUID();\n sessionStorage.setItem('access-token', token);\n return token;\n}\nWhen JS needs to send multiple pieces of data back to .NET, send them in a single invokeMethodAsync call rather than making separate callbacks:
// ❌ Two .NET round-trips from JS\nawait dotNetRef.invokeMethodAsync(ON_VOLUME_CHANGED, volume);\nawait dotNetRef.invokeMethodAsync(ON_PLAYBACK_CHANGED, isPlaying);\n\n// ✅ One callback with all data\nawait dotNetRef.invokeMethodAsync(ON_PLAYER_STATE_CHANGED, { volume, isPlaying });\nRule: if two interop calls always happen together from either side, merge them into one function.
\nEncapsulate interop for a feature in a plain class that owns the module lifecycle:
\npublic sealed class ChartInterop : IAsyncDisposable\n{\n internal const string ModulePath = \"./Components/ChartPanel.razor.js\";\n internal const string InitMethod = \"initialize\";\n internal const string UpdateMethod = \"updateData\";\n internal const string DisposeMethod = \"dispose\";\n\n private readonly IJSRuntime _js;\n private IJSObjectReference? _module;\n\n public ChartInterop(IJSRuntime js) => _js = js;\n\n private async ValueTask<IJSObjectReference> GetModuleAsync()\n => _module ??= await _js.InvokeAsync<IJSObjectReference>(\"import\", ModulePath);\n\n public async ValueTask InitializeAsync(ElementReference canvas)\n {\n var module = await GetModuleAsync();\n await module.InvokeVoidAsync(InitMethod, canvas);\n }\n\n public async ValueTask UpdateDataAsync(IReadOnlyList<DataPoint> points)\n {\n var module = await GetModuleAsync();\n await module.InvokeVoidAsync(UpdateMethod, points);\n }\n\n public async ValueTask DisposeAsync()\n {\n try\n {\n if (_module is not null)\n {\n await _module.InvokeVoidAsync(DisposeMethod);\n await _module.DisposeAsync();\n }\n }\n catch (JSDisconnectedException) { }\n }\n}\nThe component creates and uses the wrapper with no magic strings:
\n@inject IJSRuntime JS\n@implements IAsyncDisposable\n\n<canvas @ref=\"_canvasRef\" width=\"600\" height=\"400\"></canvas>\n\n@code {\n private ElementReference _canvasRef;\n private ChartInterop? _chart;\n\n protected override async Task OnAfterRenderAsync(bool firstRender)\n {\n if (firstRender)\n {\n _chart = new ChartInterop(JS);\n await _chart.InitializeAsync(_canvasRef);\n }\n }\n\n async ValueTask IAsyncDisposable.DisposeAsync()\n {\n if (_chart is not null)\n await _chart.DisposeAsync();\n }\n}\nPrefer a concrete class over interface + implementation for interop wrappers. For unit testing, substitute IJSRuntime directly (it is already an interface).
_dotNetRef = DotNetObjectReference.Create(this);\nawait _module.InvokeVoidAsync(\"initialize\", _dotNetRef);\nOn the JS side, wrap the dotNetRef in a class. Use async/await with try/catch (not .catch()) to guard against circuit loss. Define .NET method name constants at the top:
const ON_CLIPBOARD_CHANGED = 'OnClipboardChanged';\n\nclass ClipboardMonitor {\n #dotNetRef;\n #abortController;\n\n constructor(dotNetRef) {\n this.#dotNetRef = dotNetRef;\n this.#abortController = new AbortController();\n }\n\n start() {\n document.addEventListener('copy', async () => {\n try {\n const text = await navigator.clipboard.readText();\n await this.#dotNetRef.invokeMethodAsync(ON_CLIPBOARD_CHANGED, text);\n } catch { /* circuit disconnected or clipboard denied */ }\n }, { signal: this.#abortController.signal });\n }\n\n dispose() {\n this.#abortController.abort();\n }\n}\n\nlet monitor;\nexport function initialize(dotNetRef) {\n monitor = new ClipboardMonitor(dotNetRef);\n monitor.start();\n}\n\nexport function dispose() {\n monitor?.dispose();\n}\nRules:
\n[JSInvokable] methods must be public — private/internal silently fails at runtimeStateHasChanged in InvokeAsync inside [JSInvokable] callbacks:\n[JSInvokable]\npublic async Task OnClipboardChanged(string text)\n{\n await InvokeAsync(() => { _lastClipboard = text; StateHasChanged(); });\n}\ntry/catch around invokeMethodAsync in JS — circuit loss throwsconst for .NET method name strings in JS — prevents typo bugs that silently failDotNetObjectReference in DisposeAsyncAlways implement IAsyncDisposable. Call JS cleanup first, then dispose references. Catch JSDisconnectedException for Blazor Server circuit loss:
public async ValueTask DisposeAsync()\n{\n try\n {\n if (_module is not null)\n {\n await _module.InvokeVoidAsync(\"dispose\");\n await _module.DisposeAsync();\n }\n }\n catch (JSDisconnectedException) { }\n\n _dotNetRef?.Dispose();\n}\nNever use sync IDisposable for JS interop cleanup — InvokeVoidAsync returns ValueTask and must be awaited.
Pass DOM elements via @ref, not string IDs:
<canvas @ref=\"_canvasRef\" width=\"600\" height=\"400\"></canvas>\nawait _chart.InitializeAsync(_canvasRef);\n.razor.js with export — no window.* globalsOnAfterRenderAsync or event handlers — never during prerenderIAsyncDisposable catches JSDisconnectedExceptionDotNetObjectReference disposed in DisposeAsync; JS side has try/catch around invokeMethodAsync[JSInvokable] methods are public and use await InvokeAsync(StateHasChanged)InvokeVoidAsync used when no return value is neededElementReference instead of string IDs| Mistake | \nFix | \n
|---|---|
| Using JS for something achievable with CSS | \nUse CSS custom properties, data- attributes, pseudo-classes | \n
| Many fine-grained interop calls | \nBatch into coarse functions — both .NET→JS and JS→.NET | \n
| Component imports JS module directly | \nEncapsulate in a strongly typed interop class | \n
| Magic strings for method names / module paths | \nDefine internal const fields in the interop class | \n
| Interface + implementation for interop wrapper | \nUse a plain class; mock IJSRuntime for tests instead | \n
JS calls in OnInitializedAsync | \nMove to OnAfterRenderAsync(firstRender) | \n
InvokeAsync<object> for void calls | \nUse InvokeVoidAsync | \n
IDisposable with fire-and-forget JS | \nUse IAsyncDisposable with await | \n
Global window.* JS functions | \nUse collocated .razor.js with export | \n
| String element IDs passed to JS | \nUse ElementReference with @ref | \n
[JSInvokable] on private method | \nMust be public — silently fails otherwise | \n
DotNetObjectReference not disposed | \nDispose in DisposeAsync — causes memory leak | \n
StateHasChanged() without InvokeAsync | \nWrap in await InvokeAsync(() => { StateHasChanged(); }) | \n
JS invokeMethodAsync without error handling | \nWrap in try/catch — circuit loss throws | \n
Bare dotNetRef in JS event handlers | \nWrap in a class with #dotNetRef private field | \n
Magic strings in JS invokeMethodAsync calls | \nUse const at module top — typos silently fail at runtime | \n
JS calls in OnParametersSetAsync | \nTrack changes, apply in OnAfterRenderAsync with guard | \n
| No null check before calling module | \nCheck module is not null before use | \n