ClearScript: embedding V8 JavaScript and other script engines into .NET applications

The create-expose-run pattern: how a .NET host adds scripting

ClearScript's usage model follows three steps: create a script engine, add your .NET objects or types to it, then run scripts that interact with those objects. Any class that already works in .NET can be handed to the engine without attributes or an adapter layer. The bridge does not require the host to annotate which members are scriptable; anything public on the exposed object or type is accessible.

The host remains in charge of what the script can see. Nothing from the host application is visible inside the engine unless the host adds it explicitly. That design gives the host full control over what surface a script can touch, but it does not constitute a sandbox: once an object is added to the engine, the script can call all its public members, including any that in turn access sensitive system resources.

The host can also invoke script functions and access script objects directly, which makes the boundary bidirectional. .NET code can call into script logic, and script logic can call .NET methods, read .NET properties and subscribe to .NET events. This bidirectional flow is what distinguishes ClearScript from a pure evaluation pipeline where the host can only observe script outputs.

V8 runs on Windows, Linux and macOS; JScript and VBScript run only on Windows

The three supported engines differ in platform coverage. V8 covers Windows (x86, x64 and arm64), Linux (x64, arm and arm64) and macOS (x64 and arm64). JScript and VBScript are Windows-only. That split matters early in any evaluation: if the deployment target is Linux or macOS, the engine choice is V8 by default.

JScript is the Microsoft implementation of JavaScript that shipped with Internet Explorer and Windows Script Host. VBScript is the Visual Basic-flavored scripting engine that ran alongside it. Both are available only on Windows because they depend on the Windows Script Host component. Teams that already use JScript or VBScript for existing automation on Windows can embed that logic in a .NET host through ClearScript, but migrating those scripts to a cross-platform deployment means rewriting them in V8-compatible JavaScript first.

For new projects, V8 is the practical choice on all three platforms. It carries the V8 binaries as a native component, which means the NuGet package pulls in platform-specific native assets alongside the managed library.

Installing Microsoft.ClearScript.Complete and what that package includes

The README's Installation section offers a complete package named Microsoft.ClearScript.Complete, described as all-in-one for all supported platforms. It is published on NuGet under that identifier. The README does not show a dotnet or Package Manager Console command for installing it, so use the standard NuGet tooling in your environment and reference Microsoft.ClearScript.Complete as the package ID.

The complete package is the recommended starting point when you want V8 on any supported platform without configuring separate native binaries yourself. The repository also contains ClearScript/ and ClearScriptV8/ directories, NetCore/, NetFramework/ and NetStandard/ subdirectories, and a NuGet/ directory, all of which point to additional packaging configurations. The docs directory holds the project documentation.

The current release is version 7.5.1.1, published on 2026-09-04. Before that, version 7.5.1 shipped on 2026-05-10 and a preview for 7.5.1 arrived on 2025-12-22. The last push to the repository was on 2026-09-04.

.NET collections map to native script iteration; generics cross the bridge with type inference

The type mapping layer is where ClearScript earns its depth. Exposed .NET collections support native iteration syntax in each engine: V8 scripts can use for...of and for await...of, JScript scripts can use Enumerator, and VBScript scripts can use For Each...Next. This is not an approximation of iteration; the README states that collections support native script iteration mechanisms, meaning the script sees an object it can iterate with the syntax it already knows.

Generic methods cross the bridge cleanly, with the kind of type inference a C# developer would recognize and the ability to pass explicit type arguments when inference is insufficient. Scripts can invoke methods with output parameters, optional parameters and parameter arrays. That last item matters for .NET APIs that use params: a script does not have to build an array manually before passing variadic arguments.

Extension methods, conversion operators and explicitly implemented interfaces are also accessible from script code, alongside constructors and nested types when the host exposes a type rather than an instance. The net effect is that ClearScript does not flatten the .NET object model into a simplified subset for script consumption.

V8-specific features: typed arrays, ES modules, task-to-promise and BigInt

Several features are available only with the V8 engine. Fast data transfer to and from JavaScript typed arrays is one: the README marks it as a V8 feature and describes it as fast, which points to a shared memory path rather than element-by-element copying. The exact memory model for this transfer is not documented in the README.

JavaScript modules are supported under V8. CommonJS modules work with both V8 and JScript. Three optional type conversions are V8-specific: .NET BigInteger to JavaScript BigInt (automatic), .NET DateTime to JavaScript Date (optional), and .NET tasks to JavaScript promises (optional). The DateTime and task conversions are off by default and must be enabled explicitly, while the BigInteger conversion is automatic.

Turning task-to-promise conversion on is the enabler for async JavaScript code that awaits .NET operations. Without it, a script that calls a .NET method returning a Task receives a Task object rather than a thenable, and await will not work as expected. The README does not document how to enable these conversions in the API, so the project documentation at clearscript.clearfoundry.net is where to look for that.

.NET 5.0+, .NET Framework 4.6.2+, .NET Core 3.1, .NET Standard 2.1: what each target gets

ClearScript targets four runtime configurations. .NET 5.0 and later is the primary modern target. .NET Framework 4.6.2 and later covers projects that cannot migrate to the unified runtime. .NET Core 3.1 is listed alongside both as a supported target. .NET Standard 2.1 covers library projects that need to be consumable from any of the above.

The repository tree reflects these targets: NetCore/, NetFramework/ and NetStandard/ subdirectories hold configuration-specific files. UWP/ appears as a top-level directory, suggesting Universal Windows Platform support is at least considered, though the README's platform list does not mention it explicitly.

The native V8 binaries are the largest variable in a deployment. A Linux x64 build carries different native assets than a Windows arm64 build. The Microsoft.ClearScript.Complete package is described as all-in-one for all supported platforms, which means it likely ships binaries for each architecture inside a single NuGet package. For size-constrained deployments or cross-compilation scenarios, the repository layout suggests that per-platform packages may exist under the NuGet/ directory, though the README does not document them.

No access control layer inside the engine, and no assembly-level import restriction without explicit configuration

ClearScript's design principle that exposed resources require no modification also means there is no automatic restriction layer. Once a .NET object is in the engine, the script can reach everything the object's public API exposes. This is not unique to ClearScript, but it is worth stating plainly: the host has to be deliberate about what it adds to the engine, because removing something from the engine later is not the same as never having added it.

Optional support for importing types and assemblies from script code is listed as a feature. The word optional is important: if the host enables that import path, a script can load .NET types that the host did not add explicitly. That path is described as optional in the feature list, so it is off unless the host turns it on, but the README does not describe the toggle.

Jint is the usual alternative to consider here. It is a pure .NET JavaScript interpreter with no native V8 binaries, which means it runs anywhere the managed runtime runs, including platforms and architectures that ClearScript does not support. The tradeoff is that Jint does not have V8's JIT performance and runs a different JavaScript engine, so feature parity with V8-era APIs is not guaranteed. For a deployment that needs strict portability over raw execution speed, Jint is the alternative to evaluate.

Editorial conclusion

ClearScript suits a .NET host that needs industrial-strength JavaScript execution with V8 JIT performance, ES module support and direct access to host objects. Skip it if your deployment environment cannot run native platform binaries alongside a managed assembly, or if JScript and VBScript are required on Linux or macOS: those engines only work on Windows. Before adopting, check that your target architecture is one of the supported combinations: x86, x64 and arm64 on Windows; x64, arm and arm64 on Linux; x64 and arm64 on macOS.

Frequently asked questions

Official sources

1. ClearFoundry/ClearScript on GitHub
2. License: MIT
3. Project website
4. README
5. Releases