capacitor-platforms — Claude Code skill: Capacitor on desktop

---
name: capacitor-platforms
description: "Guides the agent through adding, configuring, and using the Capawesome desktop platforms for Capacitor — @capawesome/capacitor-electron and @capawesome/capacitor-tauri. Covers choosing between Electron and Tauri, installation and scaffolding, sync/run workflows, live reload, deep links, plugin compatibility (Electron plugin implementations and web fallback; Tauri plugin tiers), packaging, and app updates. Do not use for the Android or iOS platforms, installing individual Capacitor plugins, migrating Capacitor apps or plugins to newer versions, or non-Capacitor desktop frameworks."
license: MIT
compatibility: "Requires Node.js 18+ and npm. Tauri additionally requires the Rust toolchain and its system dependencies."
metadata:
  author: capawesome-team
  source: https://github.com/capawesome-team/skills/tree/main/skills/capacitor-platforms
---

# Capacitor Platforms (Desktop)

Bring a Capacitor app to macOS, Windows, and Linux with the Capawesome desktop platforms: [`@capawesome/capacitor-electron`](https://github.com/capawesome-team/capacitor-electron) and [`@capawesome/capacitor-tauri`](https://github.com/capawesome-team/capacitor-tauri). Both use the standard Capacitor workflow (`cap add` / `cap sync` / `cap run`), report `Capacitor.isNativePlatform()` as `true`, and deliver deep links through the standard `@capacitor/app` events.

## Prerequisites

| Requirement | Electron | Tauri |
| --- | --- | --- |
| Node.js | LTS (18+) | LTS (18+) |
| Capacitor | 6+ | 8+ |
| Electron | >= 28 (installed by the scaffold) | — |
| Rust toolchain + system dependencies | — | Required — see the [Tauri prerequisites guide](https://v2.tauri.app/start/prerequisites/) |

On Capacitor 6 and 7, the Capacitor CLI ignores the exit code of platform hooks — a failing `npx cap sync` still reports success. Check the log output for `[capacitor-electron]` errors. Capacitor 8 fails the command properly.

## Agent Behavior

- **Auto-detect before asking.** Read `package.json` and the Capacitor config to determine installed platforms and plugins before prompting the user.
- **Help choose the platform first.** If the user has not committed to Electron or Tauri, apply Step 1 — plugin requirements usually decide it.
- **Always use the full package name** with Capacitor CLI commands (e.g. `npx cap sync @capawesome/capacitor-electron`). A bare `npx cap sync electron` or `npx cap sync tauri` silently does nothing.
- **Check plugin compatibility early.** On Tauri, list the app's Capacitor plugins and verify each is covered by a web implementation or a curated shim (see `references/tauri.md`) before recommending it.

## MCP Servers

Two hosted MCP servers serve the current documentation, so both are always ahead of the guidance bundled with this skill:

- **[Capawesome MCP server](https://capawesome.io/docs/ai/mcp/capawesome/)** — the Capawesome plugins, the Capawesome CLI, and Capawesome Cloud.
- **[Capacitor MCP server](https://capawesome.io/docs/ai/mcp/capacitor/)** (unofficial) — Capacitor itself: the CLI, the `capacitor.config` file, the native Android and iOS projects, and the official plugin APIs.

Both expose `search_docs` and `get_doc_page`, so pick the server by topic before calling either.

- **If the MCP tools are available**, call `search_docs` on the server that owns the topic and read the matching page with `get_doc_page` before applying the guidance below. Where the two disagree, follow the documentation.
- **If they are not available**, mention once that the servers can be added with the commands below, then continue with this skill. Never block on it.

```bash
claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
claude mcp add --transport http capacitor "https://capacitor-mcp.capawesome.io/mcp"
```

Neither server needs an account or a token for documentation. See the `capawesome-mcp` and `capacitor-mcp` skills for full setup, including the Capawesome Cloud tools.

## Procedures

### Step 1: Choose a Platform

| The app needs… | Choose |
| --- | --- |
| Reuse of Capacitor plugins with native (Node) desktop implementations | **Electron** |
| Web-bundle over-the-air updates | **Electron** (Capawesome Cloud Live Updates via `@capawesome/capacitor-live-update` >= 8.5.0, requires Capacitor 8 — see `references/electron.md`; Tauri compiles web assets into the binary — only full signed binary updates) |
| A single, predictable bundled Chromium across all OSes | **Electron** |
| Smallest binaries (~3–10 MB vs ~85–120 MB) and lowest memory use | **Tauri** |
| A deny-by-default security model with a Rust core | **Tauri** |
| No Rust toolchain in dev/CI | **Electron** |

Tauri's trade-offs are inherent, not bugs: no Node runtime (so no arbitrary Capacitor plugin reuse), three different system webviews (WKWebView/WebView2/WebKitGTK), no web-bundle OTA, and a required Rust toolchain. If in doubt, read the Honest Limitations section of the [Tauri platform README](https://github.com/capawesome-team/capacitor-tauri).

### Step 2: Install and Add the Platform

Electron:

```bash
npm install @capawesome/capacitor-electron
npx cap add @capawesome/capacitor-electron
cd electron && npm install && cd ..
```

Then add a `postinstall` script to the app's root `package.json` so the Electron dependencies are always installed together with the main app dependencies:

```json
{
  "scripts": {
    "postinstall": "cd electron && npm ci && cd .."
  }
}
```

Tauri (verify `rustc --version` works first; if not, stop and walk the user through the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/)):

```bash
npm install @capawesome/capacitor-tauri
npx cap add @capawesome/capacitor-tauri
```

Both scaffolds contain only files the user owns (config, icons, a few-line entry point); all runtime logic lives in the versioned package/crate and updates via `npm update` / `cargo update`.

### Step 3: Sync and Run

```bash
npx cap sync @capawesome/capacitor-electron   # or @capawesome/capacitor-tauri
npx cap run @capawesome/capacitor-electron    # or @capawesome/capacitor-tauri
```

Electron sync copies web assets and regenerates the plugin manifest. Tauri sync additionally scans the app's Capacitor plugin dependencies and generates a deny-by-default capability file, the curated `tauri-plugin-*` crate dependencies, and the Rust plugin registrations.

For live reload on either platform, set `server.url` in the Capacitor config to the local dev server and run the platform — see the platform reference for details.

### Step 4: Configure

- Electron: typed options in `electron/capacitor.electron.config.ts` (window, CSP, deep links, hooks) — see `references/electron.md`.
- Tauri: `src-tauri/tauri.conf.json` (window, CSP, deep links via `plugins.deep-link.desktop.schemes`, bundle) — see `references/tauri.md`.

### Step 5: Package for Distribution

- Electron: `cd electron && npm run pack` (electron-builder; vendors the runtime and plugin implementations automatically) — see `references/electron.md`.
- Tauri: `npx cap sync @capawesome/capacitor-tauri && npx tauri build` (native installers per OS) — see `references/tauri.md`.

## References

- `references/electron.md` — scaffold layout, configuration, live reload, deep links, plugin support and plugin development contract, packaging and vendoring, app updates (binary updates and Live Updates), migration from `@capacitor-community/electron`.
- `references/tauri.md` — Rust prerequisites, scaffold layout, sync-time codegen, the plugin tier model (built-in / curated / web fallback), configuration, live reload, deep links, packaging, honest limitations.

## Related Skills

- **`capacitor-app-creation`** — Create a new Capacitor app before adding a desktop platform.
- **`capacitor-app-development`** — General Capacitor development topics, configuration, and troubleshooting.
- **`capacitor-plugins`** — Install and configure Capacitor plugins, including checking desktop platform support.
- **`capawesome-cloud`** — Set up Capawesome Cloud Live Updates for the Electron platform (same app and config as Android/iOS).
- **`capawesome-mcp`** — Connect an MCP client to the hosted Capawesome MCP server for always-current documentation and Capawesome Cloud management.