Build your project. Connect it to macOS.

The HTML to App builder

The current builder requires macOS 12 or newer. Export includes an ad hoc signing step that also requires macOS 12 or newer. On macOS 11 or earlier, that step fails before the exported app is saved to your chosen destination.

The exported launcher

The current bundled launcher also targets macOS 12 or newer. It displays your HTML using the system WebKit engine, so test your project's web features and native integrations on the macOS version you use. Export does not add support for older macOS versions.

First launch and manual handling

1. Choose Open App on the export completion screen, or use Show in Finder to locate the saved app.
2. If macOS blocks an unidentified or unnotarized app, use Open Privacy & Security. After trying to open your trusted export, choose Open Anyway if macOS offers it, then confirm Open.
3. On macOS 12, the corresponding controls are in System Preferences under Security & Privacy. Later versions use System Settings and Privacy & Security.

If the completion screen offers Copy Commands and Open Terminal, review the generated commands for that specific export before choosing to run them. They are a manual local-launch option, not a distribution step.

If macOS reports damage or malicious software, stop and investigate instead of approving it. Consult Apple's guidance on safely opening apps for the warning you see.

Optional automation for later exports

1. Choose Install Script on the export completion screen. Use View Script to review what it does before installing it.
2. Keep the exact Application Scripts destination and the name HTMLtoAppApproval shown in the installation dialog.
3. Installation handles the current export. Once the script is installed and up to date, HTML to App runs it automatically after subsequent exports.
4. If Update Script is offered, review and install the current version to resume automation. If approval fails or is cancelled, the exported app remains saved. Use Retry Approval or the manual instructions.
5. To disable automation, use Scripts Folder and remove HTMLtoAppApproval. Manual handling remains available.

The user-installed script runs outside the App Sandbox and removes the com.apple.quarantine attribute from the specific exported bundle. It does not change its signature or turn off Gatekeeper across your Mac.

Open With registration

• Choose whether the app should open files, folders, or both.
• Set the role to Viewer or Editor.
• Enter file extensions such as jpg, png, or mp4.
• Export the app bundle with those document types included in the generated Info.plist.

Runtime delivery

• When the user opens a matching file from Finder, macOS launches your generated app.
• The launcher receives the opened file or folder URLs on the native side.
• HTML to App forwards those items into the page after the web content is ready.
• Editor-role apps can also write back inside the opened file or folder scope.
• The same page can also receive later open events while the app is already running.

Recommended meta tag

<meta
  name="htmltoapp:open-with"
  content="role=editor; files=jpg,jpeg,png; folders=true; permissions=camera,microphone"
>

Supported values

• role=viewer or role=editor
• files=jpg,jpeg,png for file extensions
• folders=true or folders=false
• permissions=camera,microphone,location for generated-app entitlements
• camera=true, microphone=true, and location=true are also accepted
• mic, audio, geolocation, and gps are accepted aliases
• The same metadata can also be written as an HTML comment if you prefer.

Send a macOS notification

Check for the API, request permission, then create a notification. On supported macOS releases, HTML to App forwards the request to the generated app's native notification handler.

async function sendAppNotification(title, body) {
  if (!("Notification" in window)) return false;

  const permission = await Notification.requestPermission();
  if (permission !== "granted") return false;

  new Notification(title, {
    body,
    tag: "html-to-app-status"
  });
  return true;
}

Set or clear the Dock badge

Badge values are strings. Numbers work well for counts, while short labels can represent states like paused, new, or sync pending. Request notification permission before enabling Dock badge controls, because macOS ties Dock badge visibility to notification authorization for the generated app.

const appBridge = window.HTMLtoApp;

async function setUnreadCount(count) {
  if (!appBridge || typeof appBridge.setBadge !== "function") return;
  if (!("Notification" in window)) return;

  const permission = await Notification.requestPermission();
  if (permission !== "granted") return;

  if (count > 0) {
    appBridge.setBadge(String(count));
  } else {
    appBridge.clearBadge();
  }
}

Dynamic menu bar menu

The native launcher calls your JavaScript menu provider each time the menu bar icon is clicked. Return a fresh array so the menu reflects current app state.

const appBridge = window.HTMLtoApp;
let paused = false;

appBridge?.menuBar?.setIcon({
  title: "TA",
  tooltip: "Task Agent",
  imagePosition: "left",
  closeToMenuBarOnWindowClose: true
});

appBridge?.menuBar?.setBadge("4");
// Later, remove it and allow the user to start over.
// appBridge?.menuBar?.hideIcon?.();

appBridge?.menuBar?.setMenu(() => [
  { id: "open", title: "Open Window" },
  { type: "separator" },
  { id: "paused", title: "Paused", checked: paused, toggle: true },
  {
    title: "Queues",
    submenu: [
      { id: "inbox", title: "Inbox" },
      { id: "done", title: "Done" }
    ]
  },
  { type: "separator" },
  { id: "quit", title: "Quit" }
]);

appBridge?.menuBar?.onItemClick((event) => {
  if (event.id === "open") appBridge.showWindow();
  if (event.id === "paused") paused = event.checked;
  if (event.id === "quit") appBridge.quit();
});

Window title and visibility

Update the native window title from JavaScript, hide or restore the window, and use a menu item callback to bring a background menu bar app forward again.

window.HTMLtoApp?.setWindowTitle?.("Syncing 4 files");
window.HTMLtoApp?.hideWindow?.();
window.HTMLtoApp?.showWindow?.();

Common fields

• id: opened-item identifier on root launch items
• itemId: same identifier, also included on folder listing entries
• name: display name of the file or folder
• path: original macOS path as a string
• relativePath: path inside the opened folder, or an empty string for the root item
• isDirectory: true for folders, false for files
• kind: file or directory on root launch items

File and folder extras

• url: loadable URL for a file item, usable in img, video, audio, or fetch()
• baseURL: base URL for a folder item
• listingURL: JSON endpoint for the folder contents

Read and overwrite the opened file

If the launched item is a file, omit relativePath and write directly back to that same file.

const fileItem = launchItems.find((item) => !item.isDirectory);
const opened = await window.HTMLtoApp.fs.readText(fileItem.id);
editor.value = opened.text;

await window.HTMLtoApp.fs.writeText(fileItem.id, editor.value);

Create, replace, move, and remove inside an opened folder

If the launched item is a folder, target descendants by relative path. The bridge never grants access outside that opened folder tree.

const folder = launchItems.find((item) => item.isDirectory);

await window.HTMLtoApp.fs.createDirectory(folder.id, "drafts");
await window.HTMLtoApp.fs.writeText(folder.id, "# Notes\n", "drafts/today.md");
await window.HTMLtoApp.fs.move(folder.id, "drafts/today.md", "archive/today.md", {
  createIntermediates: true,
  overwrite: true
});

Viewer vs editor

• Viewer and Editor control how the app is registered with Finder and Launch Services.
• Viewer keeps the bridge read-only.
• Editor enables window.HTMLtoApp.fs write methods for the opened item scope only.
• Use Viewer for galleries, players, and browsers.
• Use Editor when the app should overwrite the opened file or manage files inside the opened folder.

Source HTML vs opened content

• HTML to App still exposes loadable item URLs for media tags, image previews, and fetch().
• Folder items can be expanded through window.HTMLtoApp.fs.list() or the provided listing URL.
• When you export in external-source mode, the selected HTML source folder remains read-only.
• Opened document files and folders are a separate scope, and editor-role apps can modify only that specific opened file or folder tree.