HTMA

WARNING: DO NOT USE! This software does not have a stable release yet.

HTMA is a file format and an application runner built on top of Electron.

HTMA stands for "Hypertext Markup Application". HTMA applications are frontend-only web apps that are fully packaged into a binary .htma file. This file can be created and run by the HTMA runner.

HTMA files are supposed to be fully self-contained applications. They only use standard browser APIs. They do not have access to the file system, but they can persist their data using browser APIs such as localStorage.

Goals of the project

• Allow non-technical users to package HTML-based projects (e. g. Twine games) using a simple GUI
• Enable a device on which the HTMA runner is installed to run HTMA files via double-click
• Package all resources of a project into a single file so that it can be easily shared
• Obfuscate the resources in a binary format so that regular users cannot easily steal them¹

1: Please be aware that this is not a fool-proof way of hiding your source files. The binary format is very simple and users with some knowledge can easily write software that extracts the resources. However, 99 percent of users will likely not bother to do so. HTMA itself can read the format but it does not offer any way to extract the contents as files out of the box.

Anatomy of an HTMA application

To package your web app as an HTMA app there are very few requirements you need to keep in mind.

Firstly, your project needs a package.json file in its main directory. This file has to have an htma property that configures your app and its main window.

A package.json config can look like this:

{
  "htma": {
    "app": {
      "name": "My App",        // Name of your app
      "logging": true,         // If true, console output of your app will be written to stdout
      "debug": false           // If true, web dev tools can be accessed in your app (ctrl+shift+i)
    },
    "window": {
      "icon": "/icon.png",     // The app's window icon (displayed in docks etc when running)
      "width": 1000,           // The initial window width
      "heigth": 700,           // The initial window height
      "fullscreen": false      // Starts app in fullscreen mode if set to 'true'
    }
  }
}

The only required configuration key is htma.app.name. This is because the application name determines which "bucket" the application data is written to. Updating the application is as simple as replacing its HTMA file with a new version. The existing data will still be available by the new version of your app.

Secondly, your application needs an index.html file that acts as an entry-point to your application. You are free to decide whether your application will be structured as a single page app or contains multiple separate HTML file.