DotCarbon.Plugins.FileSystem 0.2.8

<div align="center">

DotCarbon

Build fast, tiny, cross-platform desktop apps with C# and web technologies.

Write your interface with any web framework, your application logic in C#, and ship a single native binary — no runtime to install, no bloat.

</div>

DotCarbon lets you build native desktop applications using the web stack you already know for the UI and the full power of .NET for everything else. Your interface renders in the operating system's built-in web view, and your C# code runs natively alongside it — the two talk over a small, fully typed bridge.

Status: pre-release (0.1.x). The API is still stabilizing and may change between minor versions.

Highlights

• Single-file apps — The .NET runtime, native webview host, configuration, and compiled frontend ship as one compressed executable.
• Any frontend — First-class templates for React, Vue, Svelte, Solid, Preact, and Vanilla, all TypeScript + Vite.
• End-to-end type safety — Your C# commands are projected into TypeScript types, so invoke() calls are autocompleted and checked at compile time.
• C# backend — Use the entire .NET ecosystem for your application logic, file access, networking, and native OS integration.
• Built-in capabilities — Clipboard, dialogs, file system, notifications, shell, and window management, available as opt-in plugins.
• Batteries-included CLI — One command to develop, one to ship.

Quick start

npx @dotcarbon/create-app my-app
cd my-app
carbon dev

Pick a template with --template:

npx @dotcarbon/create-app my-app --template vue

Available templates: react · vue · svelte · solid · preact · vanilla.

carbon dev starts your frontend dev server and the C# host together with live reload. When you're ready to distribute, carbon build compiles a native app into out/.

Requirements

The scaffolder detects the carbon CLI and offers to install it for you if it's missing.

How it works

A DotCarbon app is two halves that share one window:

my-app/
├─ carbon.json          app, window, and build configuration
├─ carbon.schema.json   schema for carbon.json (editor autocomplete)
├─ src-carbon/          C# backend — the host and your commands
│  └─ Program.cs
└─ ui/                  web frontend (Vite)
   └─ src/

The C# host loads your web UI into the native OS web view. The frontend and backend communicate through a bridge: the frontend calls a command by name, a C# method handles it, and the typed result is returned as a promise.

Calling C# from the frontend

Define a command in C# — mark a method with [CarbonCommand] inside a plugin:

// src-carbon/Program.cs
using DotCarbon.Core.Bridge;
using DotCarbon.Core.Config;
using DotCarbon.Core.Host;
using DotCarbon.Core.Plugins;

var config = ConfigLoader.Load();

new CarbonHost(config)
    .WithPlugin(new AppCommands())
    .Run();

public record GreetRequest(string Name);

public partial class AppCommands : IPlugin
{
    public string Namespace => "app";

    [CarbonCommand("greet")]
    public string Greet(GreetRequest req) => $"Hello, {req.Name}!";
}

Call it from the frontend with a fully typed invoke:

import { invoke } from '@dotcarbon/api'

const message = await invoke('app:greet', { name: 'World' })
// message: string  →  "Hello, World!"

Run carbon types to (re)generate ui/src/carbon.d.ts from your commands — arguments and return values become real TypeScript types, so typos and mismatched payloads are caught before you run.

CLI

Configuration

Everything about your app lives in carbon.json, validated by the bundled schema:

{
  "$schema": "./carbon.schema.json",
  "app": {
    "name": "my-app",
    "version": "0.1.0",
    "identifier": "com.example.my-app"
  },
  "window": {
    "title": "my-app",
    "width": 1200,
    "height": 800,
    "resizable": true,
    "center": true
  },
  "build": {
    "devCommand": "npm run dev",
    "buildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "frontendDist": "ui/dist",
    "backendProject": "src-carbon"
  }
}

The window section supports size and position, minWidth/minHeight, resizable, fullscreen, maximized, alwaysOnTop, decorations, transparent, devtools, contextMenu, and icon.

Building for production

carbon build

By default this produces one compressed, trimmed, self-contained executable with the frontend and carbon.json embedded. The operating system's webview is reused, so no browser engine ships with the app.

NativeAOT is available as an experimental size/startup option, but Photino's native library currently remains beside the executable:

carbon build --aot

Target another platform with --target (e.g. --target win-x64, --target linux-x64, --target osx-arm64).

Installers and platform packages are opt-in so the normal output directory stays one file:

carbon build --bundle

Plugins

Native capabilities are opt-in — add the C# package, register the plugin, and call it from the frontend through its matching JS module.

Packages

Contributing

Contributions are welcome. This is early-stage software, so issues, ideas, and pull requests all help. Please open an issue to discuss significant changes before starting work.

License

Released under the MIT License.