How do I install the Capacitor Compat skill?

Run npx skillmds@latest add soapbox-pub/capacitor-compat in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Capacitor Compat safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Capacitor Compat?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Capacitor Compat free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Capacitor Compat?

soapbox-pub (@soapbox-pub) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Capacitor Compat by soapbox-pub — Agent Skill

Name: Capacitor Compat
Author: soapbox-pub

Capacitor Compat

Browser-API gotchas inside Capacitor's WKWebView (iOS) and Android WebView — which common web APIs silently fail, the downloadTextFile/openUrl helpers that bridge web and native, platform detection, and the installed Capacitor plugins. Load when writing code that interacts with file downloads, external URLs, or platform-specific behavior.

soapbox-pub 9f1b682 3.4 KB Updated Sep 17, 2026

File contents

Capacitor Compatibility

Ditto runs inside Capacitor's WKWebView on iOS and WebView on Android. Several common web APIs do not work in this environment. Always account for native platforms when writing code that interacts with browser-specific features.

What Doesn't Work in WKWebView (iOS)

<a download> file downloads — programmatically creating an anchor with a.download and clicking it silently fails. WKWebView ignores the download attribute entirely.
<a target="_blank"> new tabs — programmatic clicks on anchors with target="_blank" are blocked. There are no tabs in a native app.
window.open() — may be blocked or behave unexpectedly without user-gesture context.

For a deeper list of Apple Lockdown Mode restrictions that also affect WKWebView, load the lockdown-mode skill.

File Downloads and URL Opening

src/lib/downloadFile.ts provides two utilities that handle the web/native split automatically. Always use these instead of manually constructing anchors.

`downloadTextFile(filename, content)`

Saves a text file to the user's device. On web it uses the <a download> pattern. On native it writes to the Capacitor cache directory via @capacitor/filesystem and presents the native share sheet via @capacitor/share.

import { downloadTextFile } from '@/lib/downloadFile';

await downloadTextFile('backup.txt', fileContents);

`openUrl(url)`

Opens a URL in a new browser tab on web, or presents the native share sheet on Capacitor.

import { openUrl } from '@/lib/downloadFile';

await openUrl('https://example.com/image.jpg');

CRITICAL: Never use document.createElement('a') with .click() for downloads or opening URLs. The utilities above work correctly on all platforms; manual anchors silently fail on iOS.

Detecting Native Platforms

Use Capacitor.isNativePlatform() from @capacitor/core when you need platform-specific behavior:

import { Capacitor } from '@capacitor/core';

if (Capacitor.isNativePlatform()) {
  // iOS or Android
} else {
  // Web browser
}

Reserve platform forks for cases where behavior genuinely differs (share sheets, secure storage, haptics). Most UI code should stay platform-agnostic.

Installed Capacitor Plugins

@capacitor/app — app lifecycle events (deep links, back button)
@capacitor/core — core runtime and platform detection
@capacitor/filesystem — read/write files on the native filesystem
@capacitor/haptics — native haptics
@capacitor/keyboard — keyboard control (hide accessory bar, etc.)
@capacitor/local-notifications — schedule local push notifications
@capacitor/share — native share sheet
@capacitor/status-bar — control the native status-bar style
@capgo/capacitor-autofill-save-password — iOS keychain autofill for nsec
capacitor-secure-storage-plugin — OS-level secure storage (iOS Keychain / Android KeyStore)

After adding or removing plugins, run npm run cap:sync to update the native projects.

---name: capacitor-compatdescription: Browser-API gotchas inside Capacitor's WKWebView (iOS) and Android WebView — which common web APIs silently fail, the downloadTextFile/openUrl helpers that bridge web and native, platform detection, and the installed Capacitor plugins. Load when writing code that interacts with file downloads, external URLs, or platform-specific behavior.---# Capacitor CompatibilityDitto runs inside Capacitor's WKWebView on iOS and WebView on Android. Several common web APIs **do not work** in this environment. Always account for native platforms when writing code that interacts with browser-specific features.## What Doesn't Work in WKWebView (iOS)- **`<a download>` file downloads** — programmatically creating an anchor with `a.download` and clicking it silently fails. WKWebView ignores the `download` attribute entirely.- **`<a target="_blank">` new tabs** — programmatic clicks on anchors with `target="_blank"` are blocked. There are no tabs in a native app.- **`window.open()`** — may be blocked or behave unexpectedly without user-gesture context.For a deeper list of Apple Lockdown Mode restrictions that also affect WKWebView, load the **`lockdown-mode`** skill.## File Downloads and URL Opening`src/lib/downloadFile.ts` provides two utilities that handle the web/native split automatically. **Always use these** instead of manually constructing anchors.### `downloadTextFile(filename, content)`Saves a text file to the user's device. On web it uses the `<a download>` pattern. On native it writes to the Capacitor cache directory via `@capacitor/filesystem` and presents the native share sheet via `@capacitor/share`.```typescriptimport { downloadTextFile } from '@/lib/downloadFile';await downloadTextFile('backup.txt', fileContents);```### `openUrl(url)`Opens a URL in a new browser tab on web, or presents the native share sheet on Capacitor.```typescriptimport { openUrl } from '@/lib/downloadFile';await openUrl('https://example.com/image.jpg');```**CRITICAL**: Never use `document.createElement('a')` with `.click()` for downloads or opening URLs. The utilities above work correctly on all platforms; manual anchors silently fail on iOS.## Detecting Native PlatformsUse `Capacitor.isNativePlatform()` from `@capacitor/core` when you need platform-specific behavior:```typescriptimport { Capacitor } from '@capacitor/core';if (Capacitor.isNativePlatform()) { // iOS or Android} else { // Web browser}```Reserve platform forks for cases where behavior genuinely differs (share sheets, secure storage, haptics). Most UI code should stay platform-agnostic.## Installed Capacitor Plugins- `@capacitor/app` — app lifecycle events (deep links, back button)- `@capacitor/core` — core runtime and platform detection- `@capacitor/filesystem` — read/write files on the native filesystem- `@capacitor/haptics` — native haptics- `@capacitor/keyboard` — keyboard control (hide accessory bar, etc.)- `@capacitor/local-notifications` — schedule local push notifications- `@capacitor/share` — native share sheet- `@capacitor/status-bar` — control the native status-bar style- `@capgo/capacitor-autofill-save-password` — iOS keychain autofill for nsec- `capacitor-secure-storage-plugin` — OS-level secure storage (iOS Keychain / Android KeyStore)After adding or removing plugins, run `npm run cap:sync` to update the native projects.

Frequently asked questions