Scarlet.Bun.MSBuild 1.0.0-preview.2

Scarlet.Bun.MSBuild

An MSBuild task package that integrates Bun - a fast all-in-one JavaScript runtime - into your .NET build process. This package allows you to run Bun commands as part of your .NET project build, enabling JavaScript/TypeScript bundling, minification, and other Bun-powered operations.

Table of Contents

• Features
• Installation
• Runtime Options
  • Option 1: Runtime Download
  • Option 2: Platform-Specific Runtime Packages
  • Option 3: Conditional Package References
• Usage
  • Basic Example
  • Using Runtime Download
  • Task Parameters
  • Output Parameters
• Example: JavaScript/SCSS Build Script
• Development
• Requirements
• License
• Credits
• Contributing

Features

• ✅ Cross-platform support (Windows, Linux, macOS - x64 and ARM64)
• ✅ Multiple runtime options: embedded packages or on-demand download
• ✅ Easy MSBuild integration
• ✅ Supports modern .NET / .NET Core (no .NET Framework support)
• ✅ Execute any Bun command during build

Installation

Install the main MSBuild task package:

dotnet add package Scarlet.Bun.MSBuild

Or via Package Manager:

Install-Package Scarlet.Bun.MSBuild

Note: The base package does not include any Bun runtime. You must choose a runtime option (see Runtime Options below).

Runtime Options

After installing Scarlet.Bun.MSBuild, you need to provide the Bun runtime. There are three approaches to choose from based on your needs:

Option 1: Runtime Download

Download the Bun runtime automatically during build by setting the BunRuntimeDownload property:

<PropertyGroup>
  <BunRuntimeDownload>true</BunRuntimeDownload>
  <BunVersionDownload>1.3.6</BunVersionDownload> 
  <BunRuntimeDirectory>$(MSBuildProjectDirectory)/runtimes</BunRuntimeDirectory>
</PropertyGroup>

Advantages:

• Simplest configuration - just set a few properties
• No additional package dependencies to manage
• Each developer/CI agent only downloads the runtime package they need
• Runtime downloaded only once and cached locally for subsequent builds
• Can easily switch Bun versions by changing BunVersionDownload property

See Using Runtime Download for detailed configuration.

Option 2: Platform-Specific Runtime Packages

Install only the runtime package(s) you need for your target platform(s):

# For Windows x64
dotnet add package Scarlet.Bun.Runtime.windows-x64-baseline

# For Linux x64
dotnet add package Scarlet.Bun.Runtime.linux-x64-baseline

# For Linux ARM64
dotnet add package Scarlet.Bun.Runtime.linux-aarch64

# For macOS x64
dotnet add package Scarlet.Bun.Runtime.darwin-x64-baseline

# For macOS ARM64 (Apple Silicon)
dotnet add package Scarlet.Bun.Runtime.darwin-aarch64

Note: Runtime packages are versioned independently from Scarlet.Bun.MSBuild. Their package version corresponds to the bundled Bun version (e.g., package version 1.3.6 contains Bun 1.3.6).

Advantages:

• Explicit control over which runtimes are included
• No runtime downloads during build (runtimes come from NuGet packages)
• Works offline

Trade-offs:

• Package with needed runtime version might be missing

Available Runtime Packages:

Platform	Runtime	Package Name	Package Version
Windows x64	bun-windows-x64-baseline	Scarlet.Bun.Runtime.windows-x64-baseline
Linux x64	bun-linux-x64-baseline	Scarlet.Bun.Runtime.linux-x64-baseline
Linux ARM64	bun-linux-aarch64	Scarlet.Bun.Runtime.linux-aarch64
macOS x64	bun-darwin-x64-baseline	Scarlet.Bun.Runtime.darwin-x64-baseline
macOS ARM64	bun-darwin-aarch64	Scarlet.Bun.Runtime.darwin-aarch64

Option 3: Conditional Package References

Use MSBuild conditions to reference only the runtime package matching the current build platform:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  
  <ItemGroup>
    <PackageReference Include="Scarlet.Bun.MSBuild" Version="*" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
  </ItemGroup>

  
  <PropertyGroup>
    <IsWindows Condition="'$(OS)' == 'Windows_NT'">true</IsWindows>
    <IsLinux Condition="Exists('/proc')">true</IsLinux>
    <IsMacOS Condition="Exists('/System/Library/CoreServices/SystemVersion.plist')">true</IsMacOS>
  </PropertyGroup>

  
  <PropertyGroup>
    <IsARM64 Condition="'$(PROCESSOR_ARCHITECTURE)' == 'ARM64' OR '$(PROCESSOR_IDENTIFIER)' == 'ARM64'">true</IsARM64>
    <IsX64 Condition="'$(PROCESSOR_ARCHITECTURE)' == 'AMD64' OR '$(PROCESSOR_IDENTIFIER)' == 'AMD64'">true</IsX64>
  </PropertyGroup>

  
  <ItemGroup Condition="'$(IsWindows)' == 'true' AND '$(IsX64)' == 'true'">
    <PackageReference Include="Scarlet.Bun.Runtime.windows-x64-baseline" Version="*" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
  </ItemGroup>

  <ItemGroup Condition="'$(IsLinux)' == 'true' AND '$(IsX64)' == 'true'">
    <PackageReference Include="Scarlet.Bun.Runtime.linux-x64-baseline" Version="*" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
  </ItemGroup>

  <ItemGroup Condition="'$(IsLinux)' == 'true' AND '$(IsARM64)' == 'true'">
    <PackageReference Include="Scarlet.Bun.Runtime.linux-aarch64" Version="*" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
  </ItemGroup>

  <ItemGroup Condition="'$(IsMacOS)' == 'true' AND '$(IsX64)' == 'true'">
    <PackageReference Include="Scarlet.Bun.Runtime.darwin-x64-baseline" Version="*" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
  </ItemGroup>

  <ItemGroup Condition="'$(IsMacOS)' == 'true' AND '$(IsARM64)' == 'true'">
    <PackageReference Include="Scarlet.Bun.Runtime.darwin-aarch64" Version="*" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
  </ItemGroup>

</Project>

NB! You can add them without conditions, but the runtime packages have big size.

Advantages:

• Builds work on any platform without modification
• Each developer/CI agent only downloads the runtime package they need
• No runtime downloads during build (runtimes come from NuGet packages)
• Deterministic builds with version-locked packages
• Works offline

Trade-offs:

• Package with needed runtime version might be missing
• More verbose project file configuration
• Need to maintain platform detection logic

Which option should I choose?

• Use Option 1 (Runtime Download) if you want a multi-platform with the simplest setup and configuration
• Use Option 2 (Single Runtime Package) if you want a single platform and want embedded runtime (without downloads)
• Use Option 3 (Conditional References) if you want a multi-platform and want embedded runtimes (without downloads)

Usage

Basic Example

Add the following to your .csproj file to run a Bun script during build:

<Target Name="BunInstall" BeforeTargets="Build">
  <MSBuild Projects="$(MSBuildProjectFullPath)"
           Targets="Bun"
           Properties="BunCommand=install;BunWorkingDirectory=$(MSBuildProjectDirectory)" />
</Target>


<Target Name="BunBuild" AfterTargets="BunInstall">
  <MSBuild Projects="$(MSBuildProjectFullPath)"
           Targets="Bun"
           Properties="BunCommand=run;BunArguments=build.mjs;BunWorkingDirectory=$(MSBuildProjectDirectory)" />
</Target>

Using Runtime Download

If you prefer to download the Bun runtime dynamically instead of using embedded runtimes, you can enable the BunRuntimeDownload option as a global property:

<PropertyGroup>
  <BunRuntimeDownload>true</BunRuntimeDownload>
  <BunVersionDownload>1.3.6</BunVersionDownload>
  <BunRuntimeDirectory>$(MSBuildProjectDirectory)/runtimes</BunRuntimeDirectory>
</PropertyGroup>


<Target Name="BunInstall" BeforeTargets="Build">
  <MSBuild Projects="$(MSBuildProjectFullPath)"
           Targets="Bun"
           Properties="BunCommand=install;BunWorkingDirectory=$(MSBuildProjectDirectory)" />
</Target>

When using BunRuntimeDownload=true:

• The BunRuntimeDirectory property is required and specifies where to download the runtime
• The BunVersionDownload property is optional (defaults to latest version if not specified)
• Only the runtime for the current platform will be downloaded
• The runtime is cached in the specified directory and reused on subsequent builds

Task Parameters

The BunRunTask supports the following parameters:

Output Parameters

Example: JavaScript/SCSS Build Script

Here's an example build.mjs script that bundles JavaScript and compiles SCSS:

import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { minify } from "terser";
import * as sass from "sass";

const scriptFilename = fileURLToPath(import.meta.url);
const scriptDirectory = path.dirname(scriptFilename);
const jsInputDir = path.join(scriptDirectory, "scripts");
const jsOutputFile = path.join(scriptDirectory, "wwwroot/js/bundle.min.js");
const scssInput = path.join(scriptDirectory, "styles/main.scss");
const scssOutput = path.join(scriptDirectory, "wwwroot/css/site.min.css");

async function buildJS() {
  console.log("Building JS bundle...");
  
  let files = fs
    .readdirSync(jsInputDir)
    .filter((f) => f.endsWith(".js"))
    .sort();

  let code = "";
  for (const file of files) {
    const filePath = path.join(jsInputDir, file);
    console.log("Adding", filePath);
    code += fs.readFileSync(filePath, "utf-8") + "\n";
  }

  const minified = await minify(code);
  
  const outDir = path.dirname(jsOutputFile);
  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
  fs.writeFileSync(jsOutputFile, minified.code, "utf-8");
  console.log("✓ JS bundle created");
}

function buildSCSS() {
  console.log("Building SCSS...");
  
  const result = sass.compile(scssInput, {
    style: "compressed",
    sourceMap: false,
  });

  fs.mkdirSync(path.dirname(scssOutput), { recursive: true });
  fs.writeFileSync(scssOutput, result.css);
  console.log("✓ CSS bundle created");
}

await buildJS();
buildSCSS();

Don't forget to add dependencies in package.json:

{
  "type": "module",
  "dependencies": {
    "terser": "^5.36.0",
    "sass": "^1.83.4"
  }
}

Development

Building the Package

dotnet build

Running Tests

Unit tests:

dotnet test tests/Scarlet.Bun.MSBuild.Tests/Scarlet.Bun.MSBuild.Tests.csproj

Integration tests:

dotnet test tests/Scarlet.Bun.MSBuild.IntegrationTests/Scarlet.Bun.MSBuild.IntegrationTests.csproj

All tests:

dotnet test

Creating a Package

dotnet pack src/Scarlet.Bun.MSBuild/Scarlet.Bun.MSBuild.csproj

Requirements

• .NET / .NET Core (no .NET Framework support)
• Supported on Windows, Linux, and macOS

License

This project is licensed under the MIT License - see the LICENSE file for details.

Bundled Software Licenses

This package distributes Bun binaries, which include:

• Bun: MIT License - Copyright (c) Jarred Sumner and contributors
• JavaScriptCore/WebKit: LGPL-2.1 License - Bun statically links JavaScriptCore and WebKit components

Per the LGPL-2.1 license requirements, the complete source code and build instructions for Bun (including its statically linked JavaScriptCore components) are available at:

• Bun source: https://github.com/oven-sh/bun
• Patched WebKit/JavaScriptCore: https://github.com/oven-sh/webkit

To relink Bun with modifications to JavaScriptCore:

git clone https://github.com/oven-sh/bun
cd bun
git submodule update --init --recursive
make jsc
zig build

For more information, see the Bun License Documentation.

Credits

• Built by ScarletKuro
• Uses Bun - a fast all-in-one JavaScript runtime

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.