js2il 0.9.6

js2il – JavaScript to .NET IL (consumer guide)

js2il is a .NET global tool that parses JavaScript (ES) and emits ECMA‑335 IL you can run on .NET.

Install

• Prerequisite: .NET 10 SDK or later installed.
• Install the tool globally:

dotnet tool install --global js2il

Update later:

dotnet tool update --global js2il

Uninstall:

dotnet tool uninstall --global js2il

Which package should I use?

• js2il
  • The global CLI tool for ad-hoc/manual JavaScript compilation from a terminal.
• Js2IL.SDK
  • The MSBuild/NuGet integration for host projects that should compile JavaScript during dotnet build.
• Js2IL.Core
  • The reusable compiler library for custom tooling, build tasks, or other programmatic .NET integration.
• Js2IL.Runtime
  • The runtime support library used by generated assemblies and .NET hosting scenarios.

Official releases publish Js2IL.Runtime, js2il, Js2IL.Core, and Js2IL.SDK together at the same version. When you mix these packages in one workflow, keep the versions aligned.

Usage

js2il <InputFile> [<OutputPath>] [options]

Options

• -i, --input The JavaScript file to convert (positional supported)
• -o, --output Output folder for the generated IL/assembly (created if missing; defaults to the input file directory)
• -v, --verbose Print compiler diagnostics to the console
• --diagnostic-file <path> Write compiler diagnostics to a text file
• -a, --analyzeunused Report unused functions/properties/variables --version Show version information and exit

Help: -h, --help, -?

Example:

# Convert tests\simple.js and write output next to the file
js2il .\tests\simple.js

# Convert to a specific directory with verbose output
js2il .\tests\simple.js -o .\out -v

What gets generated?

Given an input like C:\code\sample.js, js2il will emit the following into the output directory (default: alongside the input file):

• sample.dll
  • A .NET assembly (targeting net10.0) containing IL corresponding to your JavaScript.
  • The assembly name is the input file name without extension.
  • Contains a Program.Main entry point that executes your script when run.
• sample.runtimeconfig.json
  • Runtime configuration for the dotnet host (framework: .NET 10).
• JavaScriptRuntime.dll (+ optional JavaScriptRuntime.pdb if available)
  • Required runtime support library that provides JS primitives (e.g., console.log, arrays, objects) used by the emitted IL.
  • This file is copied next to your generated assembly and must be present at runtime.

Run it with:

dotnet .\sample.dll

Notes:

• Console output (e.g., console.log) is implemented via the bundled JavaScriptRuntime.dll.
• This is a prototype and doesn’t yet support all JavaScript features. See the repo docs for supported syntax and feature coverage.
• Errors are written to stderr and known failures return a non-zero exit code.

Limitations

• Target framework: net10.0
• Not all JS features are supported; some constructs may be validated and rejected with explanations.
• Emitted IL and runtime surface are subject to change between previews.

Troubleshooting

• Ensure the .NET 10 SDK/runtime is on PATH: dotnet --info
• Use -v to print diagnostics to the console, or --diagnostic-file <path> to capture diagnostics to a file.
• File an issue with a minimal JS sample if you suspect a bug.

Hosting samples

The js2il tool package no longer carries the hosted C# samples. Those samples now ship with Js2IL.SDK, because they are intended to validate the MSBuild/NuGet integration path that hosting consumers use in real projects.

See:

• the repo samples\ directory
• Js2IL.SDK package page: https://www.nuget.org/packages/Js2IL.SDK
• Js2IL.Core package page: https://www.nuget.org/packages/Js2IL.Core

Links

• Hosting (.NET library mode): https://github.com/tomacox74/js2il/blob/master/docs/hosting/Index.md
• Source, issues, docs: https://github.com/tomacox74/js2il
• License: Apache-2.0