DEV Community: Kylmora

Six things about WKWebView the docs don't tell you

Kylmora — Sat, 19 Sep 2026 03:45:55 +0000

I have spent the last few months building a browser on WKWebView. Not a wrapper around a single web view — a real one, with tabs, separate cookie jars per workspace, downloads, extensions, the lot. WKWebView turns out to be a very good engine to build on and a slightly under-documented one. The class references are accurate about the API surface. What they do not tell you is what happens when you use several parts of it together.

Here are the six things that cost me the most time. All macOS, though most of it applies to iOS too.

1. WKProcessPool does nothing anymore

Every tutorial written before about 2021 tells you to share a WKProcessPool between web views so they share a process. Apple deprecated it in macOS 12 and it no longer influences process sharing at all. Creating one is dead weight.

What actually decides process sharing now is the data store. Web views that share a WKWebsiteDataStore share WebKit's network and content processes. Web views with different stores do not.

That is a more useful lever than the process pool ever was, because it means isolation and cost are the same decision. If you want two groups of tabs genuinely separated — different cookies, different local storage — give them different stores and accept another set of processes. If you want them cheap, give them the same store.

2. `WKWebsiteDataStore(forIdentifier:)` returns a new object every time

macOS 14 added persistent, named data stores, which is the API you want if you are building anything with profiles:

let store = WKWebsiteDataStore(forIdentifier: uuid)

Call it twice with the same UUID and you get two distinct objects pointing at the same data on disk. Nothing crashes. Nothing warns you. That is exactly the problem: you have silently given up the process sharing from point 1, because as far as WebKit is concerned those web views are in different stores.

So cache them, and hand the same object out every time:

private var stores: [Identity: WKWebsiteDataStore] = [:]

func dataStore(for identity: Identity) -> WKWebsiteDataStore {
    if let existing = stores[identity] { return existing }
    let store: WKWebsiteDataStore = switch identity {
    case .standard: .default()
    case .isolated(let id): WKWebsiteDataStore(forIdentifier: id)
    case .ephemeral: .nonPersistent()
    }
    stores[identity] = store
    return store
}

3. You cannot delete a data store while anything still holds it

WKWebsiteDataStore.remove(forIdentifier:) throws Data store is in use (by network process) if any reference to that store is still alive. That includes the one in the cache you just built in point 2, and it includes a web view you have already pulled out of the view hierarchy but are still holding somewhere.

Retrying on its own does not fix it — I measured that, and the retries fail for as long as the reference exists. What works is dropping your last reference first, then retrying a few times to cover the gap between the release and the deallocation actually landing:

releaseDataStore(for: identity)          // drop the cached object

for attempt in 1...5 {
    do {
        try await WKWebsiteDataStore.remove(forIdentifier: identifier)
        return
    } catch {
        if attempt == 5 { return }
        try? await Task.sleep(for: .milliseconds(250))
    }
}

And the asymmetry worth knowing: you cannot remove the default store at all. For that one you empty it with removeData(ofTypes:modifiedSince:) instead. Two different APIs for the same user-facing "delete everything", and you need both if you support more than one kind of profile.

4. `window.open` hands you a configuration, and you have to use it

The delegate method looks harmless:

func webView(_ webView: WKWebView,
             createWebViewWith configuration: WKWebViewConfiguration,
             for navigationAction: WKNavigationAction,
             windowFeatures: WKWindowFeatures) -> WKWebView?

It is tempting to ignore that configuration and build the new web view with your own, because your own is the one with all your content scripts and settings attached. Do not. The new web view has to be created with the configuration WebKit handed you, or the opener relationship breaks: window.opener comes back null, named targets stop finding the window, and OAuth popups that post back to their opener quietly fail.

So the shape you want is a function that wraps someone else's configuration rather than one that always makes its own:

func makeWebView(frame: NSRect, configuration: WKWebViewConfiguration) -> WKWebView {
    let webView = WKWebView(frame: frame, configuration: configuration)
    webView.allowsBackForwardNavigationGestures = true
    webView.allowsMagnification = true
    return webView
}

Anything you set on the WKWebView itself is fine here. Anything you attach at configuration time — user scripts, message handlers, content rules — has to be attached in that delegate too, because this configuration never went through your own setup path.

5. The web inspector has two switches, for two different things

webView.isInspectable = true (macOS 13.3+) is what lets Safari's Develop menu attach to your web views. It is not what puts Inspect Element in the page's own right-click menu. That is still the old preference, set by key:

webView.isInspectable = true
configuration.preferences.setValue(true, forKey: "developerExtrasEnabled")

You need both if you want the context menu item inside your own app. I spent an embarrassing afternoon on this one, convinced isInspectable was broken.

6. Downloads live on the web view, not on `WKDownload`

WKDownload looks self-contained, and then you try to implement retry. The two methods that start a download — resumeDownload(fromResumeData:) and startDownload(using:) — are methods on WKWebView, not on WKDownload. So "retry this download" means keeping a live web view around for it, potentially long after the tab that started it has been closed.

The second half of the same problem: WKDownload.delegate is weak, so something has to own it. One delegate serving every transfer is far less bookkeeping than one per transfer — every callback hands you the WKDownload back, so you can look up which row it belongs to:

func download(_ download: WKDownload,
              decideDestinationUsing response: URLResponse,
              suggestedFilename: String) async -> URL? {
    row(for: download)?.destination
}

The pattern

Five of these six are the same mistake in different clothes: treating a WebKit object as if it were a value you can make freely, when it is really a handle to a shared, process-backed resource with a lifetime. The data store, the configuration, the download — WebKit hands them to you, and the right move is almost always to hold on to exactly one of the thing and pass it around, rather than to construct a fresh one because constructing one is easy.

If you have hit a seventh, I would genuinely like to hear it.

All of the above came out of building Kylmora, a small open-source macOS browser — AppKit over the system WebKit, no bundled engine. The source is on GitHub if you want to see any of these in context.

I built a native macOS browser with no dependencies - my first open source project

Kylmora — Wed, 16 Sep 2026 13:39:16 +0000

I've been using Arc, then Zen, then back to Safari, and I kept running into the same thing: either the browser was fast and rigid, or it was flexible and ate my RAM. So over the last few months I built the one I wanted, and last week I put it on GitHub.

It's called Kylmora. It's an AppKit app over the system WebKit — the same engine Safari uses — with one window and Spaces inside it. No bundled Chromium, no Swift package dependencies, nothing but Apple's own frameworks.

This is my first open source project, so please be gentle with it. If something is broken or missing, tell me and I'll fix it as fast as I can.

Why no bundled engine

Every Electron or Chromium-based browser ships a copy of the web. That's where the hundreds of megabytes come from, and it's why they're slow to launch.

macOS already has WebKit in it. If you build on WKWebView, you get the engine for free, you get Apple's security updates for free, and your app is just the shell around it. The whole of Kylmora is a few hundred Swift files.

Here's what that costs, measured with 35 tabs restored and one page showing:

Metric	Value
Release bundle	5.2 MB
Window on screen	0.62 s warm, 0.97 s cold
Browser process at the window	38 MB
WebKit content process, one page	~200 MB — that's the page's, not mine

The trade is real and I want to be honest about it: you get Safari's engine, which means Safari's web compatibility and Safari's quirks. If a site only works in Chrome, it will only work in Chrome here too. I decided that was worth 5 MB.

Spaces are identities, not just tab groups

This is the part I actually built the browser for. Each Space has its own cookie jar, so the same site can be signed in as a different account in each one. Work Gmail in one, personal in another, a client's dashboard in a third — no profile switching, no separate windows.

Each Space gets its own look (light/dark, colour or gradient, a rim around the window) so a glance at any corner of the screen tells you which identity is in front. And Space Routing rules send matching addresses to the right Space, so a link from Slack lands where it belongs.

Tabs that aren't there until you look at them

A tab you haven't shown has no web view and no WebKit process behind it. Twenty-five restored tabs cost one content process, because twenty-four of them are still just a row in the sidebar with a title and a URL.

Background tabs sleep after an idle period and under memory pressure, then come back where they were — scroll position, form contents, history.

A few other things that are in there

Boosts — your own CSS and JS per site, plus a universal dark mode
Split view — side by side, stacked, or 2×2
Live folders — a folder that fills itself from an RSS feed or a GitHub repo's issues and PRs
Command palette (⌘K) that ranks tabs, Spaces, history, bookmarks and commands together
Translation on Apple's on-device model — the text never leaves the Mac
Extensions on WebKit's own engine, which reads the Chrome/Firefox manifest format
Content blocking on WebKit content rule lists, fed by EasyList and uBlock Origin's filters
Passwords in the macOS login Keychain, the same store Safari uses, so iCloud Keychain just works

What's deliberately not in it

No AI. No assistant, no summariser, no chat sidebar. Nothing about you or your Mac is sent anywhere. The update check asks for a JSON file once a day and that's the only request the app makes on its own.

Also: nothing in the UI is a mock. If a control is there, it does something. Where a feature genuinely can't work on macOS, it says so instead of pretending.

Please break it

It's Apache-2.0, macOS 14+, and there's a signed, notarized .dmg on the releases page.

Code: https://github.com/kylmora/kylmora
Site: https://kylmora.com
Issues: https://github.com/kylmora/kylmora/issues

I'm one person and this is my first open source project, so I'm sure there's plenty I've got wrong. If you hit a bug, open an issue and I'll try to have it fixed within a day or two. Same for features — if there's something your current browser does that you'd miss, tell me and I'll look at whether it fits. A lot of what's already in there came from people describing what they wanted somewhere in a thread.

Thanks for reading. Any feedback at all is genuinely welcome.