#Memory
Memory profiles, feature detection, Linux levers, shared web process, lean-page checks, the dev Memory panel, macOS and Windows levers, measured numbers.
Experimental. Part of Krate Native. Linux (WebKitGTK) is the platform where the levers are written and measured. The macOS (WKWebView) and Windows (WebView2) levers have unit-tested decision tables and run on every window the CI native job opens on those systems; what they save is measured but not asserted, see macOS and Windows.
#Profiles and config
A native app is several processes: the shell (the window, the Go runtime and the QuickJS host), the system webview's web process and network process, and a Go host child when the app has Go host code and is not linked into one executable. The profile decides how hard Krate trims them.
// krate.config.ts
export default {
native: {
memory: "balanced", // "balanced" (default) | "minimal" | "performance"
features: { media: true }, // optional overrides, see below
host: { memoryMB: 64 }, // optional QuickJS heap limit override
window: { keepAlive: false }, // tray apps: see Windows and background mode
},
};krate native build writes these to app.json as memory, features,
hostjs.memoryMB and window.keepAlive, and the shell reads them once at
load. One path carries the profile and the features to every platform layer.
| Profile | What it does |
|---|---|
performance |
The engine defaults. No lever below runs. This is how the preview behaved before profiles existed. |
balanced (default) |
Switches off the webview features the app does not use, uses the document-viewer cache model, drops the HTTP disk cache, sets memory pressure thresholds, lowers the host limits and returns freed memory to the OS when the app is idle. No measurable CPU cost. |
minimal |
Everything in balanced with tighter thresholds and limits, and JavaScriptCore's JIT turned off in the web and network processes (Linux). Page script runs several times slower than with the JIT. Pick it for apps whose scripts are light. |
#Features
The balanced and minimal profiles switch off optional engine features that
the UI does not use. krate native build scans the built UI (HTML and
JavaScript) and writes the result to app.json as features:
| Feature | Found by |
|---|---|
media |
<video>, <audio>, new Audio(, MediaSource, HTMLMediaElement, createElement("video" or "audio"); also on when webrtc is |
webaudio |
AudioContext, OfflineAudioContext, webkitAudioContext |
webgl |
getContext("webgl"), "webgl2", "experimental-webgl" |
webrtc |
RTCPeerConnection, getUserMedia, getDisplayMedia |
spellcheck |
contenteditable, or a spellcheck attribute that is not false |
Using getUserMedia or getDisplayMedia also decides who may ask: the page's
camera, microphone and screen capture requests go through the app's media
policy and need the media permission, which a derived
build adds for you.
The scan is textual and errs on the side of turning a feature on: a library in
your bundle that mentions AudioContext switches Web Audio on. A feature your
code reaches in a way the scan cannot see (an API name built at run time)
would be off, so set it explicitly:
native: { features: { webgl: true } } // force on
native: { features: { media: false } } // force off, even if detected
An app.json without a features block (built before profiles existed) keeps
every feature on.
#Linux levers
Verified on Linux. Each lever is a small function in platform/linux that checks
that the loaded WebKitGTK has the symbol it needs and skips itself otherwise.
| Lever | Profiles | What it saves |
|---|---|---|
Cache model DOCUMENT_VIEWER |
balanced, minimal | No resource cache between loads. The app's pages come from the custom scheme, so a browser-style cache would only hold memory. |
Memory pressure settings (webkit_website_data_manager_set_memory_pressure_settings) |
balanced, minimal | The web and network processes drop caches and collect garbage once they pass 200 MB (balanced: conservative 0.5, strict 0.75, polled every 5 s) or 150 MB (minimal: 0.4, 0.6, every 3 s). WebKitGTK has one process-wide setting for both processes. The kill threshold is off. Applied before the first process starts. |
WebKit settings off unless the feature is on: enable-media, -mediasource, -media-stream, -webaudio, -webgl, -webrtc, -encrypted-media |
balanced, minimal | The corresponding subsystem is not initialized in the web process. |
enable-dns-prefetching, enable-offline-web-application-cache, enable-page-cache off |
balanced, minimal | No prefetch resolver, no application cache, no whole previous pages kept for back navigation. |
Spell checking follows the spellcheck feature |
balanced, minimal | The enchant dictionaries are not loaded. |
| Throwaway HTTP disk cache directory, favicons off, intelligent tracking prevention off | balanced, minimal | Nothing is written to a cache that the app origin never fills. localStorage and IndexedDB stay in the app's data directory and persist. |
JSC_useJIT=false for the web and network processes |
minimal | The JIT code region. Costs CPU on script-heavy pages. A JSC_useJIT you set yourself wins. |
malloc_trim(0) (glibc, found with dlsym, skipped on musl) |
balanced, minimal | Returns freed GTK and GLib heap pages to the kernel. |
debug.FreeOSMemory() and a QuickJS full GC |
balanced, minimal | Returns the Go heap and collects cycles in the host VM. |
Go soft memory limit (GOMEMLIMIT) 64 MiB (balanced) or 32 MiB (minimal), unless the variable is set |
balanced, minimal | Keeps the Go heap from growing past the limit when idle. It is a soft limit: a program whose live heap is larger still works, with more GC. Applies to the shell, the Go host child and the one-process executable. |
QuickJS heap limit 64 MiB (balanced), 32 MiB (minimal) instead of 256 MiB; native.host.memoryMB overrides |
balanced, minimal | A runaway host script fails early instead of growing. |
Trimming happens 2 seconds after the app first goes quiet (the first page has
loaded), when a window closes, and after 30 seconds (15 on minimal) without
a request reaching the host.
#One process for apps with Go host code
krate native build links an app that has Go host code into one
executable when Go is installed, like --release. The Go host child's
runtime (its own heap, scheduler and socket) is gone. krate native build --layout shell keeps the prebuilt shell with a Go host child; krate native dev always runs two processes so that Go code can be rebuilt without closing
the window.
#Windows and background mode
A webview is most of an app's memory: the web process of one window costs more than the Go shell and the host code together. Three things keep that cost low as windows come and go.
#Windows share one web process
Every window of an app loads the same origin, so they do not need separate web processes.
| OS | What happens |
|---|---|
| Linux | The first window creates a WebKitWebView; every later one is created with webkit_web_view_new_with_related_view of a live view. They share the web context, the website data (cookies, local storage) and one WebKitWebProcess. Closing the first window is fine: the next window is related to any view that is still alive, and when the last view goes the web process exits and the next window starts a new one. Settings are applied to each view as it is created. |
| Windows | The app creates one ICoreWebView2Environment (one user data folder, %LOCALAPPDATA%\<appId>\WebView2) and every window asks it for a controller, so all windows run under one WebView2 browser process. The renderer processes are WebView2's own business; Krate does not pass --renderer-process-limit. |
| macOS | All windows use one WKProcessPool. WebKit starts a WebContent process per web view unless the pool says otherwise, so the pool is created with the private _WKProcessPoolConfiguration.usesSingleWebProcess switch when the class and both selectors exist (respondsToSelector is checked); a WebKit without them keeps one process per window. |
A window can also hold several views as split panes (Views); they share the same web process, and an extra view costs about 1 MB of web process memory on Linux.
#Release a window, run in the background
Hide with release hides a window and destroys its webview:
window.Get("settings").Hide(window.HideOptions{Release: true})
// later, for example on a tray click:
window.Get("settings").Show()import * as win from "@krate/app/window";
await win.get("settings").hide({ release: true });
await win.get("settings").show();When every window is released the web process is gone; what is left is the Go
shell, the Go host and, on Linux, the WebKit network process. Before the
webview is destroyed the shell asks the page for location.pathname + location.search + location.hash and the scroll position (a page that does
not answer within 1.5 seconds is released with the route WebKit reports).
Show (or Focus) creates a new webview on that route and scrolls back to
the saved position once the page has loaded. The page is loaded again, so it
starts with fresh JavaScript state and subscribes to the host signals again;
signals are the source of truth and the endpoint sends their current values
first. A route set with Navigate while the window is released replaces the
saved one. A window opened with a scoped permission list keeps its window id
across the restore.
The window events stream reports released and restored. Where the platform
cannot release a webview, app.Supports("window:release") is false and
Hide with Release only hides the window.
native.window.keepAlive (window.keepAlive in app.json) is for tray apps:
export default defineConfig({
native: { window: { keepAlive: true } },
});With it the app does not quit when its last window closes. Closing the last
window (the title bar button, or Close) releases that window instead of
destroying it, and Show brings it back, so a tray click, a menu item or a
second launch (app.OnSecondInstance) reopens the main window with
window.Main().Show(). At most one window is kept this way; another window
that closes while one is released is destroyed. Closing a window that is
already released destroys it, and the app keeps running with no window until
app.Quit(). Without keepAlive the app quits when the last window is gone,
as before.
#Hidden and minimized windows shrink
A window that is hidden (Hide) or minimized keeps its page. The shell tells
the page, then trims its own heap:
- The page gets a
krate:memory-pressureevent onwindow. A page uses it to drop caches and large buffers (onMemoryPressure(fn)in@krate/app/windowwraps it and returns a function that stops listening). It fires onHideand when the window is minimized; it does not fire when the window is merely covered. - The shell runs the same trim as the idle reaper (a Go collection that
returns free heap to the system and, on Linux, glibc
malloc_trim), about 400 ms later (once for a burst of hides).
| OS | Also |
|---|---|
| Linux | Nothing else: WebKitGTK has no call that puts a web process under memory pressure. It does throttle a page whose window is unmapped. |
| Windows | ICoreWebView2Controller::put_IsVisible(FALSE) and, through QueryInterface to ICoreWebView2_19, put_MemoryUsageTargetLevel(LOW); shown again, the level goes back to the one a visible view has in the profile (LOW for minimal, NORMAL otherwise) and the controller is visible. A WebView2 runtime without ICoreWebView2_19 skips the memory target. |
| macOS | Nothing: WebKit throttles hidden and miniaturized views by itself. |
Only a released window gives its web process memory back; a hidden page keeps what it has.
#Leaner pages
The webview is most of an app's memory, and what the page asks of it decides how much it uses. Four things are done for you in a native build, and five checks tell you about the rest.
#What a native build does by default
- Each page loads only its own code. A native build is multi-page: every route gets its own HTML file and its own script, plus the shared runtime chunk only when the page needs it. A route the user never opens is never read.
- A page without client code ships no JavaScript. A page with no event
handlers, no signals and no client-only components is plain HTML: no
<script>, no preload link and no__KRATE_CFG__block. A page that reads a host signal does need script, because the value only exists at run time; it is prerendered as an empty slot and the script fills it. - Lazy components stay lazy. The hydration code of a
lazy()component is its own chunk. The web build links it withmodulepreload; a native build does not, so the chunk is read and compiled when the component first renders, not when the page loads. A component behind a closed dialog costs nothing until it opens. - Dev builds are unchanged, so hot reload keeps working.
#The checks
krate native check and every native build run five checks over src, the
pages directory and the public directory. They are warnings: they never fail a
build. Each has its own code, and the message names the file and line.
| Code | Reports | How it decides |
|---|---|---|
KR7270 |
An <img> much larger than its rendered size |
The src is a local PNG, JPEG, GIF or WebP (a path under the public dir, or an imported file) and width/height (attributes or a literal style) are literal. It fires when the file is at least 256 px and more than imageRatio (default 2) times the rendered size. A decoded bitmap costs width x height x 4 bytes whatever the file size. Sizes set from CSS classes are not known to the compiler and are not checked. |
KR7271 |
A large base64 data: URL in a script or stylesheet |
The payload decodes to more than dataUriKb (default 16 KiB). |
KR7272 |
A web font | An @font-face rule with a url() font file, an @fontsource/* import, or a font service link (Google Fonts, Bunny, Typekit). Icon fonts (family names containing icon, symbol, awesome, material, glyph, emoji and the like) are skipped. This is a heuristic: it cannot know whether the design needs the typeface, so it only says what a web font costs (the file, a parsed copy and glyph caches per family and weight in the web process) and suggests a system stack. |
KR7273 |
A CSS effect that forces compositing layers | backdrop-filter (also the backdrop-blur utility); filter: blur() of 16 px or more; a blur inside @keyframes; a box-shadow with blur plus spread of 40 px or more on a tag or * selector; will-change on a tag or * selector, or in five or more places. A shadow on a class, a small blur or one will-change is not reported. |
KR7274 |
A long list without windowing | A .map() that returns JSX over an array known at build time with more than listItems (default 100) entries (a literal, Array.from({ length: n })), or over a value that comes from host code (a Go or .host.ts import, or a host signal) whose length the UI does not bound. A .slice() in the chain, or a windowing component (react-window, react-virtuoso, @tanstack/react-virtual or a component named Virtual*), silences it. |
The thresholds and a silence list live in the config:
export default defineConfig({
native: {
lean: {
dataUriKb: 32, // default 16
imageRatio: 3, // default 2
listItems: 200, // default 100
ignore: ["KR7272"], // the brand needs its typeface
},
},
});Only what the compiler can see is checked: a size chosen at run time, an image
from a URL or a list built from data fetched later is not. On this repository
examples/native-tasks produces no warning, and the docs site
(packages/web) reports its two variable fonts and the one backdrop-filter
of its header, all of which are real.
#The dev Memory panel
krate native dev adds a Memory button to the dev toolbar (the strip at
the bottom edge of the window). It opens a panel with:
- PSS and private dirty per process (shell, Go host child, host children, the
web, network and GPU processes of the webview), and the total, read from the
shell's
/__krate/dev/memoryendpoint; - the number of DOM nodes of the page;
- the JS heap of the page where the engine exposes it. WebKit (Linux and
macOS) has no heap size API (
performance.memoryis Chromium only), so the panel says it is unavailable; the web process row (PSS and private dirty) includes the JS heap and is the number to watch.
It samples once when opened and then every 2 seconds, and stops when closed, so a closed panel costs nothing.
#macOS and Windows
Run in CI, savings not asserted. The levers were written on Linux from Apple's WebKit headers and the WebView2 headers and documentation. The CI native job opens windows with them on macOS and Windows runners (the platform GUI tests), and on full runs its
Native memory reportstep runskrate native profile --memoryonexamples/native-tasksfor thebalancedandperformanceprofiles and uploadsreport.json. No test asserts what a lever saves, and the macOS and Windows budgets are planned (theNative memory budget comparisonstep prints the numbers next to the linux-amd64 limits and is informational).The last green run (commit 8cef55f3) measured, after the page had been idle for 10 seconds: on macOS (Apple silicon runner,
phys_footprint) a total of 52.4 MB forbalancedand 52.1 MB forperformance, with the web content process at 21.3 and 21.7 MB, so the profile made no visible difference there; on Windows (PrivateUsage) 144.6 MB and 149.4 MB, with the web process at 23.2 and 26.6 MB. Treat the savings on these two systems as unproven. The window release and hide behavior described above has no macOS or Windows test.
Every lever is guarded. A missing Objective-C selector, a failed
QueryInterface or a rejected argument skips that lever and logs one line to
stderr (on macOS only in debug mode, see below); it never stops the app from
starting. If the WebView2 runtime refuses
the memory arguments, the app starts again without them.
Inputs, read from app.json: memory (balanced when missing or unknown) and
features (media, webaudio, webgl, webrtc, spellcheck). When the
manifest has no features object, nothing is switched off for lack of
detection. When it has one, every feature that is missing or false counts as
unused and its lever applies.
#Profiles
| Profile | macOS (WKWebView) | Windows (WebView2) |
|---|---|---|
performance |
Nothing changes. | Nothing changes. |
balanced |
Page cache off, scripts cannot open windows on their own, unused features off. | One renderer process, spare renderer and back/forward cache off, unused features off. |
minimal |
balanced, plus the WebKit memory cache is purged after the first load and every two minutes. |
balanced, plus a 512 MB JavaScript heap limit, no on-disk shader cache and MemoryUsageTargetLevel LOW while visible. |
#macOS
The default WKWebsiteDataStore is always kept, so localStorage and
cookies persist. All windows already share one WKProcessPool.
| Lever | API | Profiles |
|---|---|---|
mediaTypesRequiringUserActionForPlayback = all |
public | balanced, minimal, when media is unused |
javaScriptCanOpenWindowsAutomatically = NO |
public | balanced, minimal |
Remove WKWebsiteDataTypeMemoryCache with removeDataOfTypes:modifiedSince:completionHandler: |
public | minimal |
WebGL off (WebGLEnabled, _setWebGLEnabled:) |
private | balanced, minimal, when webgl is unused |
Web Audio off (WebAudioEnabled, _setWebAudioEnabled:) |
private | when webaudio is unused |
navigator.mediaDevices off (MediaDevicesEnabled, _setMediaDevicesEnabled:) |
private | when webrtc is unused |
Back/forward page cache off (UsesBackForwardCache, _setUsesBackForwardCache: or _setPageCacheEnabled:) |
private | balanced, minimal |
Nothing here can crash the app on a WebKit that lacks a selector. Every
selector the memory code sends goes through one guard: the target object must
exist (a missing class or a nil preferences skips the lever), and it must
answer respondsToSelector:, because an unknown selector raises an Objective-C
exception that Go cannot catch. The result of +[WKPreferences _features] is
also checked to be an NSArray and each feature key to be an NSString. A
skipped lever is logged once, at debug level only (when the app runs with
Debug on, as krate native dev does). The levers are one table in
platform/darwin/memory.go (planLevers); the Objective-C side applies
nothing outside it, and a unit test pins the selectors each profile uses:
| Profile | Selectors that may be sent |
|---|---|
performance |
none |
balanced |
preferences, setJavaScriptCanOpenWindowsAutomatically:, setMediaTypesRequiringUserActionForPlayback: (media unused), and the private _features, key, _setEnabled:forFeature:, _setWebGLEnabled:, _setWebAudioEnabled:, _setMediaDevicesEnabled:, _setUsesBackForwardCache:, _setPageCacheEnabled: |
minimal |
the balanced set plus defaultDataStore and removeDataOfTypes:modifiedSince:completionHandler: |
The private levers use WKPreferencesPrivate.h names remembered without access
to the header. They try -[WKPreferences _setEnabled:forFeature:] with a
feature found by key in +[WKPreferences _features], then the direct setters,
each only after respondsToSelector:. They are not public API, may change in
any macOS release and can be absent, in which case they are skipped. The
completion handler of removeDataOfTypes:... is declared non-null, so a
no-op block is passed.
#Windows
Windows has one WebView2 environment for the whole app, so the browser
arguments are set once through an ICoreWebView2EnvironmentOptions object
implemented in Go (AdditionalBrowserArguments). WebView2 requires identical
arguments for one user data folder: a second copy of the app started with a
different memory profile while the first runs falls back to starting without
the arguments.
Every switch and feature name below was checked against the Chromium sources
(content_switches.cc, gpu_switches.cc, content_features.cc) and
Microsoft's WebView2 browser flag list, and a unit test lists each emitted name
with its source, so an argument cannot be added without that check. That a
name exists does not mean WebView2 honors it or that it saves memory: no
number has been measured on Windows. Microsoft's own page says browser flags
are for development and may change; the arguments are also skipped
automatically if the runtime refuses them.
| Argument | Profiles | Why |
|---|---|---|
--renderer-process-limit=1 |
balanced, minimal |
One origin, trusted content. A limit, not a guarantee: site isolation can still add processes for cross-origin frames. |
--disable-features=SpareRendererForSitePerProcess |
balanced, minimal |
Chromium feature that keeps an idle renderer process warm. |
...,BackForwardCache |
balanced, minimal |
Keeps whole previous pages alive. |
...,msWebOOUI,msPdfOOUI |
balanced, minimal |
Edge out-of-process UI surfaces. Not in Microsoft's flag list; Tauri ships the same two names by default, and Chromium ignores a feature name it does not know. Effect unmeasured. |
--js-flags=--max-old-space-size=512 |
minimal |
Caps the V8 heap. A page that really needs more crashes its renderer. |
--disable-gpu-shader-disk-cache |
minimal |
No on-disk shader cache. |
--disable-webgl --disable-webgl2 |
balanced, minimal, when webgl is unused |
No WebGL contexts. Both are defined in Chromium content_switches.cc. |
Not used on purpose: msSmartScreenProtection stays on because it is a
security feature; --disable-background-networking is left out because it also
stops component updates such as certificate revocation data; --disable-gpu
moves all rendering to the CPU and is only a choice the app can make through
WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS. media, webaudio and spellcheck
have no safe Chromium switch.
Two more Windows levers: when webrtc is unused, camera and microphone
permission requests are denied without a prompt (PermissionRequested; a
safeguard more than a saving), and in minimal the webview's
ICoreWebView2_19::MemoryUsageTargetLevel is set to LOW at creation. That
interface needs a recent runtime; on an older one the call is skipped. The
ICoreWebView2Settings stay as they are: none of them affects memory.
#Measuring
krate native profile --memory [dir] [--idle 30s] [--out dist-native] builds
the app, runs it and reports PSS and private dirty memory per process
role next to a blank-page floor built from the same shell; see
Measuring memory. On Linux you can
also sample the process tree yourself:
for p in $(pgrep -P $APP_PID) $APP_PID; do
awk '/^Pss:/{s=$2}/^Private_Dirty:/{d=$2}END{print s/1024, d/1024}' /proc/$p/smaps_rollup
doneEdit memory in a built app.json (prebuilt-shell layout) to compare profiles
without rebuilding.
#Measured
Linux only. WebKitGTK 2.54 under Xvfb with software rendering, on a shared
12-core machine (load average below 2 during the runs). The example is
examples/native-tasks with a scenario script baked into the page. Every
number is the median of 5 runs, interleaved between the "before" build
(the tree before profiles, shared web process and the one-process layout) and
the "after" build, sampled 14 s after launch from /proc/<pid>/smaps_rollup
summed over the process tree. Cells are PSS / private dirty in MB; the
Total column is the median of the totals, so a row need not equal the sum of
its cells.
| Setup | Shell | Web process(es) | Network process | Go host child | Total |
|---|---|---|---|---|---|
| Blank page, before | 70 / 29 | 76 / 17 | 32 / 13 | none | 183 / 64 |
| Blank page, after | 73 / 33 | 74 / 15 | 34 / 15 | none | 182 / 63 |
| 1 window, before (shell + Go host child) | 77 / 35 | 86 / 18 | 30 / 11 | 10 / 5 | 205 / 72 |
1 window, after (krate native build, one process, balanced) |
76 / 35 | 87 / 19 | 32 / 13 | none | 195 / 67 |
1 window, after, --layout shell (balanced) |
76 / 34 | 86 / 19 | 30 / 11 | 10 / 5 | 203 / 69 |
1 window, after, minimal |
74 / 33 | 81 / 19 | 30 / 11 | none | 186 / 64 |
| 3 windows, before (3 web processes) | 72 / 31 | 149 / 60 | 25 / 12 | 10 / 5 | 256 / 109 |
| 3 windows, after (1 web process) | 84 / 35 | 105 / 29 | 30 / 11 | none | 220 / 76 |
After, all windows released (keepAlive) |
90 / 32 | none | 38 / 11 | none | 131 / 47 |
What to read from this:
- Windows are where the big saving is. Three windows cost 256 / 109 before (three web processes) and 220 / 76 after (one). Releasing every window of a tray app drops the web process: 131 / 47, most of what is left being the shell and the network process.
- The one-process layout removes the Go host child, about 10 / 5 per app
(compare the two "after" 1 window rows with
--layout shell). balanceddoes not lower an idle small app by itself. The blank page is the same before and after (183 / 64 and 182 / 63), and the app minus the blank page shrinks from 22 / 7 to 13 / 4, which is mostly the host child. Its levers bound growth (caches, unused subsystems, a growing heap) rather than lowering the first number.minimalsaves about 9 / 3 more, mostly in the web process, by turning the JIT off.- Noise is large. Run to run, the PSS total of one configuration varied by up to 30 MB (for example 193 to 225 for the 1 window before row), so differences under about 15 MB between single-window rows are not significant; the 3-window and released rows are. Private dirty is steadier than PSS, which also counts shared library pages and moves with whatever else uses WebKit on the machine.
- Not measured: macOS and Windows, hardware rendering, apps with media, WebGL or large pages, and a page that grows its heap over time.
Last updated: 2026-11-17
Contributors: Noinkin