Getting Started

This guide walks you through scaffolding and running your first Miko app from the official templates.

Requirements

• .NET 11.0 SDK or later
• A platform supported by SkiaSharp:
  • Windows — Windows 10 or 11
  • macOS — Current macOS release
  • Linux — glibc-based distros (Ubuntu, Debian, Fedora, etc.). Desktop apps require a working OpenGL driver; libSkiaSharp.so and libHarfBuzzSharp.so are shipped via SkiaSharp.NativeAssets.Linux and HarfBuzzSharp.NativeAssets.Linux.
  • Android — API 26 (Android 8.0) or later, targeting API 36
  • iOS — iOS 15.0 or later

For Android / iOS heads you also need the corresponding .NET workloads (dotnet workload install android ios).

Create an app from the template

The fastest way to start is the Razor app template:

# Install the templates (preview version must be specified explicitly)
dotnet new install Miko.Templates::1.0.0-preview.1

# Scaffold and run a new app
dotnet new miko-razor -o MyApp
cd MyApp
dotnet run

A window opens showing the home page (Pages/Home.razor). Add a page by dropping a new .razor file with a @page directive into Pages/ — routes are discovered automatically.

Choose a layout

The template accepts a --layout option to scaffold a starting UI. Every layout references the Ionic components (Miko.Ionic):

dotnet new miko-razor --layout=blank     -o MyApp   # empty page (default)
dotnet new miko-razor --layout=tabs      -o MyApp   # Ionic bottom tab bar, 3 routed tabs
dotnet new miko-razor --layout=sidemenu  -o MyApp   # Ionic side-menu drawer over a page
dotnet new miko-razor --layout=list      -o MyApp   # Ionic list page
dotnet new miko-razor --layout=full      -o MyApp   # showcase with a demo page per Ionic component

Working with an AI agent

--agent adds an AI-agent setup next to the code: an index at .miko/llms.txt, this documentation under .miko/docs/, and the entry file of the chosen assistant.

dotnet new miko-razor --agent claude -o MyApp   # CLAUDE.md + .claude/  (claude | codex | cursor)

Cross-platform apps

For an app that targets Desktop + Android + iOS from one codebase, use the multiplatform template instead:

# Scaffold a shared app plus Desktop / Android / iOS startup projects
dotnet new miko-multiplatform -o MyApp
cd MyApp

# Run on the desktop
dotnet run --project MyApp.Desktop

This produces a shared Razor UI project plus one thin host project per platform. See Project Structure for the anatomy of a generated app.

Your first page

Pages are Razor components with a @page route directive:

@page "/about"
@namespace MyApp.Pages

<h1>About</h1>
<p>Hello from Miko!</p>

Configure the app

The app is wired up with a fluent builder. The generated template's App.cs looks like this:

using Miko.DevTools;
using Miko.Hosting;

public static class App
{
    public static MikoAppContext CreateContext()
    {
        var builder = MikoAppBuilder.CreateDefault();

        builder.UseTitle("MyApp");
        builder.UseSize(1024, 768);

        builder.AddDevTools();
        builder.AddStyleSheet(GlobalStyles.Create());

        // Routes and the default layout are wired up by Miko.Razor.Compiler.
        builder.UseGeneratedRoutes();
        builder.UseDefaultLayout<MainLayout>();

        builder.EnableHotReload();

        return builder.Build();
    }
}

The desktop entry point (Program.cs) takes that context and runs it:

using Miko.Windowing;

public static class Program
{
    [STAThread]
    public static void Main(string[] args)
    {
        var context = App.CreateContext();

        // Initialize the hot reload handler generated by Miko.Razor.Compiler.
        MikoHotReloadHandler.Initialize(context.GetHotReloadService());

        context.RunDesktop();
    }
}

See Razor Components for the full builder API and the rest of the component model.

Next steps

• Project Structure — how a Miko app is organized.
• Styling — the CSS-like styling model.
• Examples — runnable sample apps in the repository.