#Files and drag and drop
File associations, opening the files an app is launched with or handed by a second launch, and real paths of files dropped on a window.
Experimental. Part of Krate Native. Linux (WebKitGTK) is the platform where this is tested, including a real drag-and-drop between two GTK windows and a second launch handing a file to the running app. The macOS (
WKWebView) and Windows (WebView2) implementations compile and their logic is unit-tested, and the CI native job runs their GUI tests, but they have not been confirmed on those systems. The compatibility matrix has the per-platform status.
Three things make an app a good citizen for documents:
- the installer tells the operating system which file types the app opens
(
native.fileAssociations); - the app learns which files it was asked to open, at launch and later
(
onOpenFile,openedFiles); - the page learns the real paths of files dropped on it (
onFileDrop).
A file the user opens or drops is granted to the app: with the fs
permission the page can read it, exactly as it can read a file chosen in a
dialog. Nothing else outside the app directories becomes
readable.
#File associations
export default defineConfig({
native: {
appId: "com.acme.notes",
productName: "Acme Notes",
fileAssociations: [
{ ext: ["md", "markdown"], name: "Markdown document", mime: "text/markdown", role: "editor", icon: "assets/md.png" },
{ ext: ["log"], role: "viewer" },
],
},
});| Key | Meaning |
|---|---|
ext |
Extensions without the dot, required. Each is registered once; the match is case-insensitive |
name |
Display name of the type. Default: <EXT> file |
mime |
Media type. Default: application/x-<app>-<first extension>. Give the real one for a well-known type |
role |
editor (default) or viewer |
icon |
A PNG or JPEG for files of this type, relative to the project. Default: the app icon |
The config check rejects extensions with a dot or wildcard, duplicates across
entries, malformed media types, other roles, and the extensions of programs and
shortcuts (exe, bat, lnk, ...), which an app cannot claim. Each message
carries a hint. A typo inside an entry warns like any other config key.
An app with file associations also takes the single-instance
lock automatically (app.json gets "singleInstance": true
and the release build links the app SDK area even if no page calls it).
krate native package turns the list into:
| Platform | Output |
|---|---|
| macOS | CFBundleDocumentTypes in Info.plist (name, role, LSHandlerRank, extensions, media type, CFBundleTypeIconFile) and, for a type macOS does not declare itself, a UTExportedTypeDeclarations entry <appId>.filetype.<ext> conforming to public.data. About thirty common extensions (txt, json, csv, pdf, png, yaml, ...) use the system UTI and export nothing. A type with its own icon gets Resources/filetype-<ext>.icns. |
| Windows, MSIX | One windows.fileTypeAssociation extension per type in AppxManifest.xml, with the extensions (each with its ContentType), the display name and the logo. |
| Windows, NSIS | ProgID <appId>.file.<ext> with DefaultIcon and shell\open\command; HKCR\.<ext>\OpenWithProgids; and, for an editor, the default handler of an extension nobody handles yet. The uninstaller removes exactly what the installer wrote and refreshes the shell. The icon is filetype-<ext>.ico next to the executable. |
| Linux | MimeType= in the .desktop file (with %F, or %U when the app also has deepLinks) and usr/share/mime/packages/<appId>.xml, a shared-mime-info file with the globs, in the .deb, the .rpm and the AppImage's AppDir. |
What is not done: an installed app is not set as the default handler of a
type another program owns (Windows and macOS keep that choice with the user),
a viewer role has no Windows equivalent, and the Linux packages ship no
maintainer scripts (the distributions' triggers refresh the MIME and desktop
databases).
#Opening files
A file reaches the app when the user double-clicks it, chooses "Open with", runs
app file.md, or drops it on the Dock icon.
| Where | How the app hears of it |
|---|---|
| First launch, Windows and Linux | The file is on the command line (Linux launchers pass %F or %U; file:// URLs are converted to paths) |
| First launch, macOS | Launch Services calls the app delegate's application:openURLs:, even before the app finished starting; those calls are held until the SDK listens |
| App already running, Windows and Linux | The new process takes the single-instance lock, finds the first one and hands over its command line and working directory, then exits. The running app raises its window |
| App already running, macOS | The system sends application:openURLs: to the running app |
import { onOpenFile, openedFiles } from "@krate/app/app";
import { readText } from "@krate/app/fs";
const stop = onOpenFile(async (path) => {
const text = await readText(path); // allowed: the user opened this file
show(path, text);
});
const all = await openedFiles(); // every file opened since the app started, oldest first
onOpenFile calls the function once per file. By default it first replays the
files opened before the call, so a document that launched the app is not
missed whenever the page gets round to listening; pass { replay: false } for
new files only. Both need the app permission. A page that reloads gets the
launch files again.
import "github.com/kratejs/krate/packages/native/sdk/app"
files, _ := app.OpenedFiles()
app.OnOpenFile(func(path string) { open(path) }) // replays, then new filesIds: krate/app.openedFiles (call) and krate/app.openFileEvents (stream of
{paths, index, source} where source is launch, second-instance or
system).
What counts as a file. app.FilesFromArgs(args, dir) is the parser used for
command lines: it drops flags, deep links and other URLs, resolves relative
paths against the other launch's working directory, converts file:// URLs, and
keeps only existing regular files, each once. A directory argument is not an
opened file. At most 4096 files are kept per run.
Command line of the prebuilt shell. krate-shell [flags] [appDir] [files...]
treats the first argument as the app directory only when it holds an
app.json; otherwise every argument is a file or URL to open and the app is the
one next to the binary. The -psn_<n> argument older macOS versions pass is
ignored. A release build is app file.md.
Access. The same grant a dialog pick gets: the path (a file, not its folder)
becomes readable through @krate/app/fs and sdk/fs, and nothing else. The
grant lasts until the app exits. Go host code is trusted and never needs it.
macOS deep links. application:openURLs: also carries URLs of the schemes in
deepLinks; those reach onOpenURL like the ones a second launch carries.
#Drag and drop
import { onFileDrop } from "@krate/app/window";
const stop = onFileDrop(({ paths, x, y }) => {
for (const p of paths) importFile(p); // absolute paths of files and folders
});A web page never sees the path of a dropped file. The shell adds it: when the
user drops files from the desktop onto a view, onFileDrop fires with their
absolute paths and the drop position in CSS pixels. It needs the window
permission. By default it reports drops onto this page's view only (a window
with several views has one per pane); { all: true }
reports every view's drops, with view and window ids. In Go,
window.OnFileDrop(fn) receives every drop. Ids: krate/window.fileDrops
(stream) and krate/window.thisView (which view the caller is).
The page keeps its normal HTML5 drop events with the File objects; the
shell only watches. Dropped paths are granted like opened files.
| Platform | How the paths are read |
|---|---|
| Linux | The GTK drag-data-received, drag-drop and drag-leave signals of the web view are watched, never stopped. WebKitGTK asks the source for the text/uri-list while the drag hovers; the watcher keeps that list and reports it at the drop, or requests it itself when WebKit did not. |
| macOS | The web view is a WKWebView subclass whose performDragOperation: reads the dragging pasteboard's file URLs (file URLs only) and then calls WebKit's own implementation. |
| Windows | A script injected into the app's pages posts the dropped File objects with chrome.webview.postMessageWithAdditionalObjects from a capture-phase drop listener; the host reads ICoreWebView2File.Path from the message's additional objects. Needs a WebView2 Runtime that has ICoreWebView2WebMessageReceivedEventArgs2; without it a log line says so and no path is reported. |
Limits: coordinates are widget pixels on Linux and CSS pixels elsewhere, which
only differ on scaled displays; a File made by script has no path and is
skipped; on Linux a drag from a Flatpak or Snap application can hand over
document-portal paths instead of the original ones.
#Testing
go test covers the packaging output (plist, manifest, registry script,
.desktop, MIME XML), the config checks, argument parsing, the SDK event
flow with an in-memory platform, and the injected script (under Node).
examples/native-files is a small app that lists the files it was opened with
and the ones dropped on it; the end-to-end test starts the real shell with a
file argument, starts it again to hand over a second file, and sends a drop
through the dev control channel's drop command. On Linux, a GUI test drags a
file between two GTK windows with synthesized pointer events (xdotool, under
a window manager) and checks that the platform reports the path and the page
still gets its drop event.
Things only a person can check are listed in platform/darwin/MANUAL_TEST.md
and platform/windows/MANUAL_TEST.md: a real Finder double click, a drag from
Explorer, an installed package's "Open with" list.
Last updated: 2026-11-17
Contributors: Noinkin