Installation & Packages
This document covers the MewUI NuGet package structure, installation, and backend selection at publish time.
1. Package Structure
Section titled “1. Package Structure”MewUI is organized into metapackages (convenience bundles) and individual packages (fine-grained composition).
Aprillz.MewUI ← All-in-one metapackage (all platforms + all backends)├─ Aprillz.MewUI.Core ← Core (controls, layout, markup, binding)├─ Aprillz.MewUI.Platform.* ← Platform hosts│ ├─ .Platform.Win32│ ├─ .Platform.X11│ └─ .Platform.MacOS└─ Aprillz.MewUI.Backend.* ← Rendering backends ├─ .Backend.Direct2D (Windows) ├─ .Backend.Gdi (Windows) ├─ .Backend.MewVG.Win32 (Windows, NanoVG/OpenGL) ├─ .Backend.MewVG.X11 (Linux, NanoVG/OpenGL) └─ .Backend.MewVG.MacOS (macOS, NanoVG/Metal)Separately managed packages (not included in the metapackages):
Aprillz.MewUI.Svg- SVG parsing/renderingAprillz.MewUI.MewDock- Visual Studio style dockingAprillz.MewUI.MewCharts- cartesian, pie and polar chartsAprillz.MewUI.WebView2.Win32- WebView2 integration (Windows only)Aprillz.MewUI.Skia- SkiaCanvasView, with a GPU interop package per backend (.Skia.Interop.Direct2D,.Skia.Interop.Gdi,.Skia.Interop.MewVG.Win32,.Skia.Interop.MewVG.X11,.Skia.Interop.MewVG.MacOS) and the metapackages.Skia.Windows,.Skia.Linux,.Skia.MacOS,.Skia.AllAprillz.MewUI.Platform.Browser- browser platform host (WebAssembly, net10.0 only)Aprillz.MewUI.Backend.MewVG.Browser- WebGL 2 rendering backend for the browser hostAprillz.MewUI.Templates-dotnet newtemplates for desktop and browser apps (section 2.4)
2. Installation
Section titled “2. Installation”2.1 Quick Start — Metapackages
Section titled “2.1 Quick Start — Metapackages”In most cases, just add a single platform metapackage.
| Target Platform | Package | Includes |
|---|---|---|
| Windows | Aprillz.MewUI.Windows |
Core + Win32 + Direct2D + GDI + MewVG |
| Linux | Aprillz.MewUI.Linux |
Core + X11 + MewVG |
| macOS | Aprillz.MewUI.MacOS |
Core + MacOS + MewVG |
| Cross-platform | Aprillz.MewUI |
All platforms + all backends |
# Windows appdotnet add package Aprillz.MewUI.Windows
# Cross-platform appdotnet add package Aprillz.MewUIInstalling a package is not enough to run: the app registers a platform host and a rendering backend before Application.Run, and a missing registration throws InvalidOperationException at the first control that measures text. On macOS that is:
MacOSPlatform.Register();MewVGMacOSBackend.Register();See Application Lifecycle for the Windows, Linux and browser equivalents and for the builder chain.
2.2 Individual Packages
Section titled “2.2 Individual Packages”Instead of a metapackage, you can reference only the packages you need.
<ItemGroup> <PackageReference Include="Aprillz.MewUI.Core" Version="0.21.1" /> <PackageReference Include="Aprillz.MewUI.Platform.Win32" Version="0.21.1" /> <PackageReference Include="Aprillz.MewUI.Backend.Gdi" Version="0.21.1" /></ItemGroup>2.3 Additional Packages
Section titled “2.3 Additional Packages”Add SVG or WebView2 support separately.
dotnet add package Aprillz.MewUI.Svgdotnet add package Aprillz.MewUI.WebView2.Win322.4 Project Templates
Section titled “2.4 Project Templates”Aprillz.MewUI.Templates creates a project that already references the packages and registers the platform host and backend.
dotnet new install Aprillz.MewUI.Templates
# Desktop app for Windows, Linux and macOS, on Aprillz.MewUI (-f net8.0 for .NET 8)dotnet new mewui -o MyApp
# Browser app on WebAssemblydotnet new mewui-browser -o MyBrowserAppThe created project references the MewUI packages of the same version as the template package.
2.5 Browser Apps
Section titled “2.5 Browser Apps”A browser app references Aprillz.MewUI.Platform.Browser and Aprillz.MewUI.Backend.MewVG.Browser instead of a metapackage; the all-in-one Aprillz.MewUI does not include them. Building one needs the WebAssembly build tools (dotnet workload install wasm-tools), and the app owns its page files. See Browser Bootstrap for the project setup and what the template creates.
3. Backend Selection at Publish
Section titled “3. Backend Selection at Publish”3.1 Overview
Section titled “3.1 Overview”Metapackages include all backends for the target platform.
At publish time, use the MewUIBackend property to keep only one backend.
If not specified, all backends are included in the publish output.
3.2 CLI
Section titled “3.2 CLI”# Direct2D onlydotnet publish -r win-x64 -p:MewUIBackend=Direct2D
# GDI only (lightweight)dotnet publish -r win-x64 -p:MewUIBackend=Gdi
# MewVG onlydotnet publish -r win-x64 -p:MewUIBackend=MewVG3.3 In csproj
Section titled “3.3 In csproj”<PropertyGroup> <MewUIBackend>Direct2D</MewUIBackend></PropertyGroup>3.4 In a Publish Profile
Section titled “3.4 In a Publish Profile”<!-- Properties/PublishProfiles/Win-Direct2D.pubxml --><Project> <PropertyGroup> <RuntimeIdentifier>win-x64</RuntimeIdentifier> <MewUIBackend>Direct2D</MewUIBackend> </PropertyGroup></Project>dotnet publish -p:PublishProfile=Win-Direct2D3.5 MewUIBackend Values
Section titled “3.5 MewUIBackend Values”| Value | Kept | Removed |
|---|---|---|
Direct2D |
Backend.Direct2D | Backend.Gdi, Backend.MewVG.Win32 |
Gdi |
Backend.Gdi | Backend.Direct2D, Backend.MewVG.Win32 |
MewVG |
Backend.MewVG.* | Backend.Direct2D, Backend.Gdi |
| (not set) | All | — |
Linux and macOS include only the MewVG backend, so
MewUIBackendis not needed.
4. Cross-Platform Publish (Aprillz.MewUI)
Section titled “4. Cross-Platform Publish (Aprillz.MewUI)”The all-in-one package (Aprillz.MewUI) includes assemblies for every platform,
but dotnet publish -r <rid> automatically excludes non-target platform assemblies.
| RID | Kept | Auto-removed |
|---|---|---|
win-x64 |
Core, Win32, Direct2D, Gdi, MewVG.Win32 | X11, MacOS, MewVG.X11, MewVG.MacOS |
linux-x64 |
Core, X11, MewVG.X11 | Win32, MacOS, Direct2D, Gdi, MewVG.Win32, MewVG.MacOS |
osx-arm64 |
Core, MacOS, MewVG.MacOS | Win32, X11, Direct2D, Gdi, MewVG.Win32, MewVG.X11 |
RID filtering and MewUIBackend filtering can be combined.
# Windows + Direct2D onlydotnet publish -r win-x64 -p:MewUIBackend=Direct2D5. Rendering Backend Guide
Section titled “5. Rendering Backend Guide”| Backend | Platform | Notes |
|---|---|---|
| Direct2D | Windows | GPU-accelerated, high-quality text rendering. Recommended default for Windows |
| GDI | Windows | CPU-based, ultra-lightweight, minimal dependencies |
| MewVG | Windows, Linux, macOS | Managed port of NanoVG. Uses OpenGL (Win32/X11) or Metal (macOS) |
See Application Lifecycle for backend registration in app code.
6. File-Based Apps (.NET 10+)
Section titled “6. File-Based Apps (.NET 10+)”In .NET 10 file-based apps, reference packages with the #:package directive.
#:sdk Microsoft.NET.Sdk#:property OutputType=Exe#:property TargetFramework=net10.0
#:package Aprillz.MewUI@0.21.1
using Aprillz.MewUI;using Aprillz.MewUI.Controls;
// ...Application.Run(window);7. Version Compatibility
Section titled “7. Version Compatibility”- All MewUI packages (Core, Platform., Backend., metapackages) are published with the same version.
- Referencing a single metapackage automatically aligns all dependency versions.
- When composing individual packages, ensure all packages use the same version.