Browse documentation
Docs Start
Alpha documentation — APIs may change between 0.x releases.

Getting started

Create a Windows, macOS, or Android app with a standard web frontend and a C#/.NET native host.

Prerequisites

  • .NET 10 SDK
  • The .NET MAUI workload
  • Node.js 22 or newer
  • Xcode when targeting macOS; Windows targets must be built on Windows
  • JDK 17 and the Android SDK when targeting Android; Android targets can be built on Windows, macOS, or Linux

Install the MAUI workload:

dotnet workload install maui

Scaffold an app

npm create vidra-app@latest

Choose a project name and reverse-domain app ID when prompted. The generated project contains:

  • ui/ — the web app.
  • src/<App>.Host/ — the .NET MAUI host and your C# contracts.
  • vidra.config.ts — typed native-access and update configuration.
  • ui/src/generated/ — TypeScript generated from those C# contracts.

The vidra CLI is installed locally in the project. No global install is required.

Check your environment

cd my-app
npm run doctor

doctor checks the .NET SDK, MAUI workload, platform tooling, and signing prerequisites. When something is missing, it prints the command needed to fix it.

Run the app

npm run dev

Vidra starts Vite and the native host together with hot reload. Edit the web UI or supported C# code and the running app updates; Vidra handles platform-specific recovery automatically.

The scaffold demonstrates all three bridge directions:

  • UI buttons call built-in C# modules such as app, clipboard, and notifications.
  • C# calls a generated JavaScript counter contract.
  • Native window and hot-reload events update the web UI.

The demonstrated native methods and events are explicitly granted in vidra.config.ts. Vidra denies unlisted WebView access by default.

Common commands

npm run dev                     # web UI + native host with hot reload
npm run build                   # package for the current platform
npm run doctor                  # verify the development environment
npx vidra run                   # launch the native host only
npx vidra dev --target windows  # run a specific target
npx vidra dev --target android  # run on a connected device or emulator
npx vidra build --target macos  # build a specific target

Preview a build without running it:

npx vidra build --target macos --plan

Android development

vidra dev --target android installs the host on a connected device or running emulator and points its WebView at the Vite dev server. It prefers adb reverse to forward the Vite port; when that is unavailable it falls back to 10.0.2.2 for emulators or a LAN address for physical devices. Set VIDRA_ANDROID_HOST to override the LAN address Vidra picks.

Add your first contract

Next, call C# from JavaScript. You will add a native method, register and grant it, and use the generated TypeScript proxy from the UI.