Jroc.SDK 0.12.38

Jroc.SDK

Jroc.SDK is the consumer-facing NuGet package for compiling JavaScript sources during dotnet build.

It imports MSBuild props/targets, invokes Jroc.Core in-process, and exposes the generated module assembly back to the host project as a normal MSBuild output.

Which package should I use?

• Jroc.SDK
  • Use this when your project should compile JavaScript during dotnet build. Consume the newly compiled assembly through its generated typed Import and Run APIs.
• jroc
  • Use this when you want the standalone CLI/global tool for manual compilation.
• Jroc.Core
  • Use this for in-memory compilation when scripts are supplied at runtime.
• Jroc.Runtime
  • Runtime execution support; generated-facade projects receive the implementation transitively from Jroc.SDK.

Official releases publish Jroc.Runtime, jroc, Jroc.Core, and Jroc.SDK together at the same version. Local-feed validation must include Jroc.Runtime because it is a transitive Jroc.SDK dependency.

Install

<ItemGroup>
  <PackageReference Include="Jroc.SDK" Version="VERSION" />
</ItemGroup>

The SDK restores and deploys the compatible runtime automatically.

Basic usage

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Jroc.SDK" Version="VERSION" />

    <JrocCompile Include="JavaScript\HostedMathModule.js" />
  </ItemGroup>
</Project>

Replace VERSION with a released JROC version. Create JavaScript/HostedMathModule.js:

exports.version = "1.0.0";
exports.add = (left, right) => left + right;

Create Program.cs alongside the project file:

using var math = HostedMathModule.Import();
Console.WriteLine(math.Version);
Console.WriteLine(math.Add(1d, 2d));

Run dotnet run in the project directory. It builds the JavaScript module, then prints 1.0.0 and 3. No global compiler installation is required.

By default:

• JrocCompile items are compiled before ResolveAssemblyReferences
• the generated module assembly is added as a normal Reference
• generated files are written under $(IntermediateOutputPath)\jroc\<SourceFileName>\

That means a host project can compile against the generated exports contracts with no extra custom .proj file or CLI invocation.

Compiled assemblies also expose assembly-named static script facades. Given AssemblyName="HelloAssembly" and an entry file named hello.js, C# can run the entry module or the explicit script without calling runtime APIs:

HelloAssembly.Run();
HelloAssembly.Scripts.hello.Run("--mode", "test");

Modules with compiler-detected exports also expose Import():

using var exports = HelloAssembly.Import();
Console.WriteLine(exports.Version);

Side-effect-only modules do not get Import(). Dynamic or computed CommonJS exports get a safe generated fallback contract rather than being hidden.

.NET compatibility

The build task ships under tasks/net10.0 and requires a .NET 10 or .NET 11 MSBuild host. It is a build integration package, not a lib/net10.0 library; NuGet's framework tab does not describe all supported consumer targets.

Generated framework references and runtime configuration use the consuming project's targeting pack, not the runtime executing MSBuild:

The .NET 10 SDK cannot build a net11.0 project. Using SDK 11 does not require retargeting an existing net10.0 host. These are framework requirements, not claims of complete JavaScript or Node.js compatibility; see the ECMAScript support index.

Output deployment

Normal build and publish output receives the runtime implementation through the SDK dependency. CopyToOutputDirectory controls copying the generated JROC artifacts themselves; it is not a substitute for runtime package resolution.

Package/module-id entrypoints work too. For example, if the host project restores the npm package in its own directory:

<JrocCompile Include="@mixmark-io/domino"
              CopyToOutputDirectory="true" />

When Include is a module id and RootModuleId is not set, the SDK preserves that module id as the root module id automatically, matching the CLI --moduleid behavior.

JrocCompile metadata and matching properties

You can set metadata per item or apply defaults with properties:

• OutputDirectory / JrocOutputRoot
  • Where generated files are written.
• ModuleResolutionBaseDirectory / JrocModuleResolutionBaseDirectory
  • Base directory used when Include is a package/module id instead of a file path. Defaults to $(MSBuildProjectDirectory). Set the project property once for the common case, or use per-item metadata only when a specific item needs an override.
• RootModuleId / JrocRootModuleId
  • Optional module id override for the root entry module. For package-style inputs such as @mixmark-io/domino, you usually do not need to set this because the SDK will use the module id automatically.
• ReferenceOutputAssembly / JrocReferenceOutputAssembly
  • Defaults to true. When enabled, the generated module assembly is added to Reference before assembly resolution.
• CopyToOutputDirectory / JrocCopyToOutputDirectory
  • Defaults to false. When enabled, the generated outputs are copied into $(TargetDir) after build.
• EmitPdb / JrocEmitPdb
  • Defaults to true for Debug builds and false otherwise.
• Verbose / JrocVerbose
• AnalyzeUnused / JrocAnalyzeUnused
• DiagnosticFilePath / JrocDiagnosticFilePath

MSBuild outputs

After JrocCompile runs, the package populates:

• @(JrocCompiledAssembly)
  • ItemSpec is the generated .dll
  • Metadata includes SourcePath, OutputDirectory, AssemblyName, RuntimeConfigPath, RuntimeAssemblyPath, PdbPath, and RootModuleId
• @(JrocGeneratedOutput)
  • ItemSpec is every generated file
  • Metadata includes Kind (Assembly, AssemblyPdb, RuntimeConfig, RuntimeAssembly, RuntimePdb)

Bundled hosting samples

This package ships the repo hosting samples under samples/ so the packaged samples exercise the same MSBuild/NuGet flow end users consume.

To validate a sample from the .nupkg:

# Download the package (replace VERSION)
$version = "VERSION"
$url = "https://api.nuget.org/v3-flatcontainer/jroc.sdk/$version/jroc.sdk.$version.nupkg"
Invoke-WebRequest -Uri $url -OutFile "Jroc.SDK.$version.nupkg"

# Extract it (a .nupkg is a zip; Expand-Archive expects a .zip extension)
Copy-Item "Jroc.SDK.$version.nupkg" "Jroc.SDK.$version.zip" -Force
Expand-Archive -Path "Jroc.SDK.$version.zip" -DestinationPath "jroc_sdk_pkg" -Force

# Build + run a sample
dotnet build .\jroc_sdk_pkg\samples\Basic\host
dotnet run --project .\jroc_sdk_pkg\samples\Basic\host

If you are validating a locally packed prerelease feed instead of NuGet.org, pack Jroc.Runtime, Jroc.Core, and Jroc.SDK into the same feed, then override JrocPackageVersion (or the individual JrocSdkPackageVersion / JrocRuntimePackageVersion properties) when building the sample. The legacy JavaScriptRuntimePackageVersion property is still accepted as an alias.

Repo hosting sample pattern

• samples\Basic and samples\Typed
  • The host project references Jroc.SDK directly and declares a JrocCompile item that points at compiler\JavaScript\*.js.
• samples\Domino
  • The host project keeps package.json / package-lock.json next to the .csproj, runs npm ci in place, and compiles @mixmark-io/domino directly using the default module-resolution base.
• samples\Picocolors
  • Same flat layout as Domino but compiles the picocolors package and calls color/style functions from C#.

Links

• SDK docs: https://github.com/tomacox74/js2il/blob/master/docs/sdk/Index.md
• Migrating from JS2IL: https://github.com/tomacox74/js2il/blob/master/docs/sdk/LegacyPackageMigration.md
• Release history: https://github.com/tomacox74/js2il/blob/master/CHANGELOG.md
• Source: https://github.com/tomacox74/js2il
• Issues: https://github.com/tomacox74/js2il/issues
• License: Apache-2.0