LegacyBlazorJs 9.0.17

LegacyBlazorJs

Rebuilds the official ASP.NET Core blazor.web.js for multiple JavaScript language targets and publishes the results as a Razor Class Library NuGet package.

Motivation

Background

The official ASP.NET Core Blazor browser support targets "evergreen" browsers only.

However, there are cases where supporting older browsers is necessary, especially for enterprise use. Unfortunately, .NET 9 and later target ES2022, and there have been reports of it not working on somewhat older browsers.

This project aims to make Blazor available on older browsers by rebuilding the Blazor JavaScript runtime, blazor.web.js, to support multiple versions from ES5 to ES2022.

Automation

The build, verification, and release processes are automated and scheduled to run regularly. This allows us to:

• Instant access to upstream updates and breaking changes.
• Released versions should pass testing and therefore function correctly.
• Updates continue even if I lose interest. (Sustainability!)

How to use

Use from NuGet packages

Install the NuGet package LegacyBlazorJs in your Blazor application.

For example, if you are using .NET 10, the version you should install is 10.*.

dotnet add package LegacyBlazorJs

Then, replace the official script in your Blazor Web App's Components/App.razor with the required profile:

- <script src="@Assets["_framework/blazor.web.js"]"></script>
+ <script src="@Assets["_content/LegacyBlazorJs/blazor.web.es2015.js"]"></script>

The es2015 part can be changed according to the browser target. Please refer to the Included files section for details.

Use from GitHub Release

You can also download and use the compiled JavaScript files from GitHub Releases, which are uploaded there.

The procedure is as follows:

1. Download the latest js files from Release/LegacyBlazorJs.x.y.z.zip.
2. Unzip the files and copy the necessary JavaScript files to wwwroot.
3. Load those JavaScript files as scripts in App.razor.

Included files

Overview

The following files are included under _content/LegacyBlazorJs/:

• blazor.web.{version}.js
• blazor.server.{version}.js
• blazor.webassembly.{version}.js
• blazor.webview.{version}.js

The versions listed below are available.

The profile definitions are in config/targets.json.

Compatibility results

1. IE9 and earlier are difficult to run due to a significant lack of APIs.
2. The SignalR connection can be established, but subsequent UI updates are broken.
3. Confirmed to work. Since regular testing is not performed, it may stop working at some point.

Development Guide

How it works

To be specific, the process is as follows:

1. First, resolve the upstream dotnet/aspnetcore targets.
   • By default, the build targets the configured net9, net10, and net11-preview lines.
   • The defaults are controlled in config/majors.json and can be overridden with environment variable BUILD_CHANNELS.
2. Clone the upstream.
3. Build the upstream JavaScript packages with npm workspaces.
4. Build the dependencies in advance. As of .NET 10, the following are included in the dependencies.
   • JSInterop
   • SignalR
   • dotnet.js is built in the runtime, but since it is loaded by dynamic import, it does not need to be built in advance.
5. It is compiled by @rollup/plugin-typescript.
   • At this time, by inserting a transformation plugin via Babel, it is converted for older browsers such as ES2015.
6. The generated JS files (blazor.(type).(version).js) are packaged together into LegacyBlazorJs.
7. Smoke tests are performed (using an old Chromium), and then the package is released.
   • It is released with the same version as the upstream.

Since many modern APIs are missing in older browsers, syntax transformation by Babel alone is not sufficient.
Therefore, the following Polyfills and Patches are applied.

Pre-Patches

Before building, apply the following patches first. These patches basically replace the upstream code itself with simple fixes.

• batch-blazor-regex.mjs
  • Blazor uses a regular expression to retrieve comments (``) included in HTML and connect them, but the regular expression uses Name Capture Group.
  • Name Capture Group is only supported in ES2018 and later, so it is modified to retrieve it by index specification.
• patch-signalr-abort-controller.mjs
  • AbortController is not supported in older browsers, so if it is not available, it is modified not to use it.
• patch-signalr-logging.mjs
  • If SIGNALR_LOGGING is set (for example, SIGNALR_LOGGING=Debug), it replaces the default logLevel: LogLevel.Warning in src/Platform/Circuits/CircuitStartOptions.ts.
  • Valid values are Trace, Debug, Information, Warning, Error, and Critical.

Rollup Build

Overview of the build process is as follows. see rollup-plugins for details.

• Convert CommonJS modules to ES modules.
• Insert Polyfill for whatwg-fetch and webcomponents.
• Use Babel to transform syntax for older browsers.
• Insert Polyfill of core-js.
• Convert import() to Function("u", "return import(u)")(u); because import() syntax will cause an error in older browsers.
  • Even if you run in this state, it will cause an error, but since this part is not executed except for WASM (dotnet.js), it is not a problem.
• Other transformations are also performed for older browsers.

These settings are inserted before terser is applied in upstream rollup settings.

How to Test Functionality

Although there are many limitations, methods for testing functionality remain available for IE and Chrome as of 2026.

For IE

Open Edge, go to "Settings" → "Existing Browser" → "Internet Explorer Mode Pages," add http://localhost:(port), and then open the application.

To open the developer tools, run %systemroot%\system32\f12\IEChooser.exe.

For Chrome

Download chrome-win32.zip from https://commondatastorage.googleapis.com/chromium-browser-snapshots/index.html?prefix=Win/(Id)/, extract it, and run it to run the older version.
The ID uses the correspondence table in chromium-snapshot.json.

Note that older Linux versions may lack shared libraries, potentially preventing the application from starting. Therefore, using the Windows version is a more straightforward approach.

License

This repository itself is licensed under the MIT License.

The generated js files included in the build artifacts are licensed under the MIT License of dotnet/aspnetcore.