Getting started
The quickest route is a generated project. The framework supplies the
platform entry points, the root component, the stylesheet loading and the
host wiring. Your app starts at [AppRoot].
Requirements
- .NET SDK 10 with the usual
dotnetCLI. - Desktop: Windows, Linux or macOS with OpenGL 3.3. The desktop host creates a GLFW window.
- Android: the .NET Android workload and an Android SDK. The generated APK is standalone.
- Browser: a .NET 10 browser build. No extra workload is needed for the Blazor-based WASM host.
Install the CLI
The donkeh tool generates projects and components. Install it
from NuGet, or run it directly from the repository:
dotnet tool install --global Donkeh.CliTool
# or run from a checkout
dotnet run --project Donkeh/CliTool/Source/Donkeh.CliTool.csproj -- --help
To move an existing project and the global tool to a newer release:
donkeh upgrade project --version=1.0.25
# or resolve the latest stable release
donkeh upgrade project
Create a project
Run one of these from any directory. The CLI uses the published NuGet packages, so no framework checkout is required.
# current directory becomes the project root
donkeh new project .
# or create a new directory and project
donkeh new project MyApp
The project defaults to desktop. The generated Program.cs
contains a single attributed root component, so there is no Main
to write and no platform-specific entry-point code.
For a reusable component library, generate a framework-shaped project
instead. It creates a packable library under src/ and a console
test container that renders every public component in a live gallery.
donkeh new project Acme.Components --type framework
cd Acme.Components
donkeh enable-feature hot-reload
donkeh watch
The test container references the library directly.
enable-feature adds the development-only reloader and
watch runs the gallery in Debug. Supported C# edits and CSS
edits update the live preview; unsupported C# edits restart the app. When
the library is ready:
dotnet pack src/Acme.Components.csproj -c Release
--framework <path> to point at a local checkout. The
generated project then uses project references instead of NuGet packages.
Directory structure
A NuGet-based project carries only its own source. The framework's host
wiring arrives with the packages. Projects generated against a local
checkout also include a Directory.Build.targets that imports
that checkout's build targets.
The app root
[AppRoot] marks the component the framework should mount. Its
named properties replace the old IDonkehApp.Settings object.
using Donkeh.Hosting;
using Donkeh.UILab;
using static Donkeh.UILab.HtmlHelper;
[AppRoot(
Width = 1180,
Height = 760,
Title = "My app",
EnableDevTools = true)]
public sealed class App : Component
{
public override Node Render() =>
Div(new() { ClassName = "app" });
}
new WindowSettings { ... }. Use the attribute's named
properties, for example Width = 1180 and
Frameless = true.
The framework discovers the attribute in the entry assembly, creates the
root component, loads every [Stylesheet] declaration, and
starts the matching host. Desktop and browser builds compile a generated
Main; Android uses the framework activity.
Choose hosts
Desktop is enabled by default. Add Android or browser support from the project directory, and the CLI updates the project file for you:
donkeh enable-target android
donkeh enable-target web
Each target only adds what it needs: target frameworks, package
references and platform properties. Checkout-based projects use the
equivalent Donkeh* properties instead.
<!-- Checkout-based projects only. -->
<PropertyGroup>
<DonkehDesktop>true</DonkehDesktop>
<DonkehAndroid>true</DonkehAndroid>
<DonkehWeb>true</DonkehWeb>
</PropertyGroup>
| Property | Target | Output |
|---|---|---|
DonkehDesktop | net10.0 | Desktop |
DonkehAndroid | net10.0-android | APK |
DonkehWeb | net10.0-browser | Static site |
Android permissions can also be declared centrally. The framework emits the matching manifest entries:
<PropertyGroup>
<DonkehAndroidPermissions>Camera;Microphone;Location;Notifications</DonkehAndroidPermissions>
</PropertyGroup>
Build and run
From the project directory:
# desktop, the default host
dotnet run
# build every enabled target
dotnet build
# Android APK
dotnet build -f net10.0-android
# browser static site
dotnet publish -c Release -f net10.0-browser
Browser output is written to the project's builds/wasm
folder. Serve it with any static file server that returns the correct
MIME types for .js, .wasm and
.json.
--screenshot <path>,
renders 120 frames, writes a BMP and closes. The CLI and framework use it
for headless checks.
Where code goes
src/Components. A component is a class deriving from Component.
Shared state
Use typed Context<T> providers for values that many components need.
State and effects
Use hooks inside Render for state, effects, memoisation and context reads.
Device access
Ask for camera, microphone, location and other permissions through Host.Permissions.
Manual project setup
If you are not using the CLI, a normal SDK project only needs a package reference. The package carries the entry point and platform wiring:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Donkeh.Windowing" Version="1.0.22" />
</ItemGroup>
</Project>
In a framework checkout, import the props after the opt-in properties and
import the targets from a Directory.Build.targets instead:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<DonkehDesktop>true</DonkehDesktop>
</PropertyGroup>
<Import Project="..\Donkeh\Build\Donkeh.props" />
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFrameworks>$(DonkehTargetFrameworks)</TargetFrameworks>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
</Project>
<Project>
<Import Project="..\Donkeh\Build\Donkeh.targets" />
</Project>