desktop-framework

README

Ardeidae Desktop Framework

Overview

The Ardeidae Desktop Framework is an experimental development framework aimed at making it easier to build web-based desktop applications. It’s designed to be lightweight, cross-platform, and developer-friendly, with a Go backend and a Qt-based frontend.

This project is in its early stages. While it’s currently usable, it’s clunky and requires refinement to achieve its full potential.

A key motivation behind this framework is to address the challenges we faced with existing solutions and to create something that better suits our needs.

Why We Started This Project

We decided to build the Ardeidae Desktop Framework after struggling to find an existing framework that fit our requirements. Here's what we found:

• Electron

  • Too resource-heavy and demanding in terms of memory/CPU usage.
  • Complicated cross-platform setup.
  • Node.js backend doesn't work well for us, being mostly Go focused

• Tauri

  • Lightweight but requires a Rust backend.
  • Relies on WebKit, which lacks certain features we needed.

• Wails

  • Exciting due to its Go backend and simplicity, but tied to WebKit, which caused bugs and limitations similar to Tauri.

To address these gaps, we’re working on a framework better suited to our workflows and technical needs.

Current Features

• Qt Interface
  Provides a native, polished desktop application experience.
• Cross-Platform Support
  Applications can run on major operating systems with minimal configuration.
• Go Backend
  Designed to take advantage of Go’s simplicity, speed, and developer-friendly ecosystem.
• Basic IPC
  Enables communication between Go and JavaScript using JSON-over-WebSocket (though this still needs optimization).

Wishlist: Areas for Improvement

This project is a work in progress. Below are the key improvements and features we hope to implement:

• Better IPC Implementation
  Improve the efficiency of cross-language communication, as the current JSON-over-WebSocket layer is functional but not ideal.

• Qt Layer Exposure
  Allow developers to directly access and combine Qt components with web elements, enabling hybrid development.

• Improved Developer Workflow
  Currently, a lot of manual work is required to build and run an application.

Getting Started

Installing The Framework

To get started with the framework, you will need a couple of things first:

1. A working Qt6 toolchain - see your OS's instructions for installing the Qt
   development packages
2. A recent version of Golang - 1.24.3. Older versions may work but have not
   been tested.

Once you've sorted these things out, you can run:

go install ardeidae.org/tools/desktop-framework/cmd/ardeidae-desktop-framework@latest

This may take a while as the internal Qt bindings need to be compiled. It could take 10 minutes or more the first time you run this.

Create a Project From Scratch

The create command can be used to create a project from scratch:

ardeidae-desktop-framework create <project name> <web framework>

Currently only two options are supported for the <web framework> argument:

• vue Runs scaffolding for a Vue.js project
• custom Provides a minimal setup and allows you to create your own project configuration

This project is just a stripped-down Chrome browser. Most, if not all, web frameworks should work out-of-the-box.

Integrate With An Existing Web App

To add desktop functionality to an existing web app, you will need to convert your web project into a Go project:

cd /path/to/your/project
go mod init <project name>

Then you can copy and paste this code into the project directory. This is the bare minimum code you need to make a working desktop app:

package main

import (
    "ardeidae.org/tools/desktop-framework/pkg/app"
    "ardeidae.org/tools/desktop-framework/pkg/ipc"
    "ardeidae.org/tools/desktop-framework/pkg/qt"
    "embed"
)

// REQUIRED - This binds your application to the framework runtime
var ArdeidaeDesktopFramework__Application = MyApp{}

// Make sure to change the path to your actual distribution folder
//go:embed frontend/dist/*
var appFiles embed.FS

type MyApp struct{}

// RegisterWebContent registers your web application content to the renderer
func (a MyApp) RegisterWebContent() app.WebContent {
    return app.WebContent{
        Files: appFiles,
		
        // Make sure this is the same as the embed path above
        Root:  "frontend/dist",
    }
}

// RegisterServices - In the future this will allow you to create communication
// channels between Go and JavaScript.
func (a MyApp) RegisterServices(register ipc.ServiceBinder) {
}

// Setup allows you to interact with and modify parts of the Qt runtime. This
// function is called once the internal runtime setup has finished.
func (a MyApp) Setup(window qt.QMainWindow) {
  
    { // Optional - Modify renderer settings
        renderer := app.GetWebRenderer()
		
        // Update Chrome flags
        settings := renderer.Settings()
        settings.SetAttribute(qt.QWebEngineSettings__AllowRunningInsecureContent, false)
        settings.SetAttribute(qt.QWebEngineSettings__LocalStorageEnabled, true)
        settings.SetAttribute(qt.QWebEngineSettings__NavigateOnDropEnabled, true)

        // Enable Chrome DevTools - F12 to toggle
        rendererWithDevTools := app.EnableDevToolsToggle(renderer)
        window.SetCentralWidget(rendererWithDevTools)
		
        // Enable dev server support if needed
        renderer.SetUrl(qt.NewQUrl.FromString("http://localhost:5173", qt.QUrl__TolerantMode))
    }
	
    // Set your window options
    window.Resize(1280, 720)
    window.SetWindowTitle("Website Builder Prototype")
  
    // Display the window
    window.Show()
}

Run Your Application

ardeidae-desktop-framework run my_project

Or:

cd my_project
ardeidae-desktop-framework run .

Build And Distribute - TODO

As the framework is still in early development, there is no ability to create distribution builds yet. Sorry!