BuildFlow

eQuantic.UI Build Flow

This document describes the eQuantic.UI build flow, demonstrating how the framework maintains zero external dependencies for the consumer.

Visual Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                           DEVELOPMENT (source tree)                         │
└─────────────────────────────────────────────────────────────────────────────┘

  reconciler.ts, component.ts, etc.
         │
         ▼
  ┌──────────────────────────────────┐
  │  npm run build                   │  (only during development)
  │  (eQuantic.UI.Runtime)           │
  └──────────────────────────────────┘
         │
         ▼
  dist/index.js (compiled runtime)
         │
         │
  boot.ts ──────imports────────┘
         │
         ▼
  ┌──────────────────────────────────┐
  │  dotnet build                    │
  │  (eQuantic.UI.Server)            │
  │                                  │
  │  ResolveBunForServer target:     │
  │  ├─ Looks for Bun in:            │
  │  │  Runtime.Osx64/tools/bun/     │
  │  │  Runtime.Win64/tools/bun/     │
  │  │  Runtime.Linux64/tools/bun/   │
  │  ├─ Extracts from .zip if needed │
  │  └─ chmod +x (Unix)              │
  │                                  │
  │  BundleRuntime target:           │
  │  └─ "$(_BunPath)" build boot.ts  │
  └──────────────────────────────────┘
         │
         ▼
  wwwroot/runtime.js (embedded in Server.dll)
         │
         ▼
  ┌──────────────────────────────────┐
  │  dotnet pack                     │
  │  (eQuantic.UI.Server)            │
  └──────────────────────────────────┘
         │
         ▼
  artifacts/packages/eQuantic.UI.Server.0.1.1.nupkg


┌─────────────────────────────────────────────────────────────────────────────┐
│                        CONSUMER (client project)                            │
└─────────────────────────────────────────────────────────────────────────────┘

  MyApp.csproj
  ├─ Sdk="eQuantic.UI.Sdk/0.1.1"
  └─ PackageReference: eQuantic.UI.Server, eQuantic.UI.Runtime

         │
         ▼
  ┌──────────────────────────────────┐
  │  dotnet restore                  │
  │                                  │
  │  NuGet installs packages:        │
  │  ├─ eQuantic.UI.Sdk              │
  │  ├─ eQuantic.UI.Server           │
  │  ├─ eQuantic.UI.Runtime          │
  │  │  └─ (meta-package)            │
  │  └─ eQuantic.UI.Runtime.Osx64    │  ◄── Bun embedded here!
  │     └─ tools/bun/bun-darwin.zip  │
  └──────────────────────────────────┘
         │
         ▼
  ┌──────────────────────────────────┐
  │  dotnet build                    │
  │                                  │
  │  SDK.targets executes:           │
  │                                  │
  │  1. ResolveBunZipPath            │
  │     └─ $(PkgeQuantic_UI_Runtime_ │
  │        Osx64)/tools/bun/*.zip    │
  │                                  │
  │  2. EnsureBunExtracted           │
  │     ├─ Unzip if needed           │
  │     └─ chmod +x (Unix)           │
  │                                  │
  │  3. ResolveBunPath               │
  │     └─ Defines $(BunPath)        │
  │                                  │
  │  4. CompileEQuanticUI            │
  │     └─ dotnet eqc.dll ... --bun  │
  │        "$(BunPath)"              │
  │                                  │
  │  5. CopyEQuanticRuntime          │  ◄── NEW: Runtime.js deployment
  │     └─ Copy runtime.js from SDK  │
  │        to wwwroot/_equantic/     │
  │                                  │
  │  6. BuildCSS (Tailwind)          │
  │     └─ "$(BunPath)" x            │
  │        @tailwindcss/cli ...      │
  └──────────────────────────────────┘
         │
         ▼
  wwwroot/_equantic/
  ├─ runtime.js (copied from SDK)
  └─ *.js (compiled components)
         │
         ▼
  ┌──────────────────────────────────┐
  │  dotnet run                      │
  │                                  │
  │  Server serves:                  │
  │  ├─ runtime.js (from Server.dll) │
  │  └─ *.js (from wwwroot/_equantic)│
  └──────────────────────────────────┘
         │
         ▼
  Browser loads application

Bun Source by Component

Component	Bun Source
Server (package build)	eQuantic.UI.Runtime.{OS}/tools/bun/ (source tree)
SDK (consumer)	$(PkgeQuantic_UI_Runtime_{OS})/tools/bun/ (NuGet cache)
Tailwind	Uses $(BunPath) resolved by SDK

Consumer Requirements

The consumer only needs:

• .NET SDK 8.0
• dotnet restore + dotnet build

No Node.js, npm, or global Bun installation required.

Key Files

File	Responsibility
Sdk/Sdk.targets	Resolves Bun from NuGet cache, compiles components
Server.csproj	Resolves Bun from source tree, bundles runtime.js
Tailwind.targets	Uses $(BunPath) to generate CSS
Runtime.{OS}.csproj	Packages Bun executable for each platform

MSBuild Targets (Execution Order)

In SDK (consumer)

1. ResolveBunZipPath - Finds the Bun .zip in NuGet cache
2. EnsureBunExtracted - Extracts the executable if needed
3. ResolveBunPath - Defines $(BunPath) for later use
4. CompileEQuanticUI - Transpiles C# → TypeScript → JavaScript
5. CopyEQuanticRuntime - Copies runtime.js from SDK package to wwwroot/_equantic/
6. BuildCSS (Tailwind) - Generates CSS with Tailwind CLI

In Server (development)

1. ResolveBunForServer - Finds Bun in source tree
2. BundleRuntime - Compiles boot.ts → runtime.js

Runtime.js Deployment Strategy

The runtime.js file is deployed to consumers via the SDK package using a two-step process:

1. Packaging (Development)

During dotnet pack of eQuantic.UI.Sdk:

<!-- eQuantic.UI.Sdk.csproj -->
<Content Include="..\eQuantic.UI.Runtime\dist\index.js"
         PackagePath="tools\runtime\runtime.js"
         Condition="Exists('..\eQuantic.UI.Runtime\dist\index.js')" />

This embeds the compiled runtime into the SDK NuGet package at tools/runtime/runtime.js.

2. Deployment (Consumer Build)

During dotnet build of consumer projects, the CopyEQuanticRuntime target executes:

<!-- Sdk/Sdk.targets -->
<Target Name="CopyEQuanticRuntime"
        AfterTargets="CompileEQuanticUI"
        Condition="'$(EnableEQuanticUICompilation)' == 'true'">
  <PropertyGroup>
    <_RuntimeSourcePath>$(MSBuildThisFileDirectory)../tools/runtime/runtime.js</_RuntimeSourcePath>
    <_RuntimeDestPath>$(MSBuildProjectDirectory)/$(EQuanticOutputPath)runtime.js</_RuntimeDestPath>
  </PropertyGroup>

  <Error Text="eQuantic.UI: Runtime not found at '$(_RuntimeSourcePath)'..."
         Condition="!Exists('$(_RuntimeSourcePath)')" />

  <Message Text="eQuantic.UI: Copying runtime.js to output..." Importance="High" />

  <Copy SourceFiles="$(_RuntimeSourcePath)"
        DestinationFiles="$(_RuntimeDestPath)" />
</Target>

Key Points:

• Uses $(MSBuildThisFileDirectory) for relative path resolution within the NuGet package
• Executes AfterTargets="CompileEQuanticUI" to ensure components are compiled first
• Provides clear error message if runtime.js is missing
• Works for both local development (artifacts/packages) and distributed NuGet packages

Single Bundle Strategy

The runtime uses Vite's inlineDynamicImports: true configuration to create a single bundle:

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        inlineDynamicImports: true,  // ← Creates single bundle
      },
    },
  },
});

Why Single Bundle?

• Simplified Deployment: Only one file to copy (runtime.js)
• No Chunk Management: Avoids issues with separate logger-.js, error-overlay-.js chunks
• Reliable Distribution: Guaranteed that all runtime features (logger, error overlay) are included
• Small Size: ~49KB minified with all features included

Without this, Vite would create separate chunks for dynamic imports, and the SDK would need to copy multiple files with hash-based names.