Archangel

A small library for building web-based desktop applications in Zig.

Creating an Archangel Application

Prerequisites

• Zig compiler, version 0.15.2 or higher
• Platform specific dependencies
  • Windows
    • WebView2
  • Linux
    • webkit2gtk-4.1
  • MacOS
    • WebKit

There is currently no CLI or similar tooling for bootstrapping an Archangel application. You will need to do the following steps manually.

Initialize a New Project

You can bring your own frontend setup for your Archangel application, but below steps will assume you are using Vite as your build tool.

Create your Vite project

# or npm, yarn, pnpm e.t.c
$ bun create vite
$ cd <app-name>
$ bun add @shahwali/archangel

Create your archangel source directory inside the project

$ mkdir src-archangel
$ cd src-archangel
$ zig init --minimal
$ zig fetch --save git+https://codeberg.org/shahwali/archangel.git

Archangel is quite flexible in how you want to use it, but an archangel.conf.zon file is required to configure the application. Place it in src-archangel with the following content.

.{
 .app_name = "My Example App",
 .dev_url = "http://localhost:5173/", // Must be the same as the url your are hosting your frontend on locally.
 .frontend_build_path = "../dist", // Must be the same as the path your frontend is built to.
 .bindings_path = "../src/generated",
 .window = .{
 .width = 1280,
 .height = 720,
 .title = "My App",
 },
}

For a simple minimal Archangel application, you can create the following main.zig file in the src-archangel/src.

conststd=@import("std");constarchangel=@import("archangel");constHelloResponse=struct{message:[]constu8,timestamp:i64,};fnhelloHandler(name:[]constu8)!HelloResponse{if(std.mem.eql(u8,name,"John")){returnerror.InvalidName;}returnHelloResponse{.message=trystd.fmt.allocPrint(std.heap.page_allocator,"Hello, {s}!",.{name}),.timestamp=std.time.timestamp(),};}pubfnmain()!void{// Use whatever allocator you want.vargpa=std.heap.DebugAllocator(.{.safety=true}).init;constallocator=gpa.allocator();defer{if(gpa.deinit()==.leak){@panic("memory leak detected!");}}varapp=tryarchangel.App.init(allocator,.{.{"hello",archangel.handler.create(helloHandler)},},);deferapp.deinit();tryapp.run();}

And then you can build it with the following build.zig

conststd=@import("std");constarchangel=@import("archangel");pubfnbuild(b:*std.Build)void{consttarget=b.standardTargetOptions(.{.default_target=.{.cpu_model=.baseline,},});constoptimize=b.standardOptimizeOption(.{});constexe=b.addExecutable(.{.name="testapp",.root_module=b.createModule(.{.target=target,.optimize=optimize,.root_source_file=b.path("src/main.zig"),}),});constarchangel_dep=archangel.createApp(b,exe);_=archangel_dep;}

The archangel.createApp function will create a run step that you can use to run the application. It also creates an option dev which can be passed to enable development mode. In development mode, the webview will navigate to the dev_url you specified in the archange.conf.zon file, rather than embedding the frontend in the binary, thus allowing you to take advantage of HMR-like features with a tool like Vite for example.

For a more advanced example, you can look at the testapp example. This example shows a more realistic use case of archangel, where your app is contained to a Zig module which is then imported in your executable entry point. The module can then have its own tests and be self contained. It also creates a custom bundle step which in this simple example just installs the executable to zig-out/bin, but it can be customized to do all sorts of things such as install additional binaries, libraries and data required to run the app using the Zig build system.

Run the application in development mode

In the frontend root, start the dev server

$ bun dev

In the archangel root (src-archangel), start the application.

$ zig build run -Ddev

Build the application for production

In the frontend root, build the production version of the frontend

$ bun run build

In the archangel root (src-archangel), build the application.

$ zig build

You will find the executable in the zig-out/bin directory.

You can also run the application to test it in production mode

$ zig build run

Distribution

Archangel does not come with a built in bundler. You will have to define your own bundling code in your build.zig, and then use your preferred tool to create a distributable package for your application for each specific platform.

Experimental Features

Generate typescript bindings

You can generate typescript bindings for your handlers using the bindings step. To do this you must create an archangel_options declaration in your entry point file.

consttestapp=@import("testapp");constarchangel=@import("archangel");pubconstarchangel_options:archangel.Options(testapp.handlers)=.{.skip_binding=.initComptime(.{.{"hello"}}),// You can also specify handlers to skip/ignore.};pubfnmain()!void....

$ zig build bindings

This will place the bindings in the bindings_path specified in your archangel.conf.zon.