# capacitor-react

Guides coding agents through building mobile apps with Capacitor and React 18+. Helps write native feature hooks, configure deep links, and handle the Android back button.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 776 installs · ★ 51
- Author: capawesome-team
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/capawesome-team/skills/tree/HEAD/skills/capacitor-react/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/capacitor-react

## What it does

The skill instructs coding agents on analyzing Capacitor project layouts and consuming native plugins in React components. The agent checks `package.json` for React dependencies, bundlers like Vite or Next.js, and Capacitor versions 6, 7, or 8. Existing folder structures are preserved unless you explicitly request a restructure.

Execution guidelines forbid calling plugin methods at the module root level. All native calls belong inside event handlers or lifecycle hooks. Subscriptions register inside `useEffect` with cleanup calls via `remove()`. The instructions cover integration with TanStack Query, Zustand, or simple React context, prohibiting the agent from introducing new state libraries without justification.

iOS builds require Xcode on macOS, while Android projects require Android Studio. This skill does not support Ionic Framework applications (use `ionic-react` instead) and does not handle Capacitor version upgrades.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-react -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/capacitor-react/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/capacitor-react/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-react -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/capacitor-react/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-react -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/capacitor-react/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install capawesome-team/skills capacitor-react
```

2. **Manually: put the files in place**
- File: `.github/skills/capacitor-react/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-react -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/capawesome-team/skills --path skills/capacitor-react
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/capacitor-react/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-react -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/capawesome-team/skills/tree/HEAD/skills/capacitor-react/SKILL.md

## When to use it
- write custom React hooks wrapping Capacitor native plugins
- handle incoming deep links with @capacitor/app and React Router
- capture hardware back button events on Android
- connect native device calls to TanStack Query or Zustand

## Example prompts
- Create a custom React hook that wraps the Capacitor Geolocation plugin with proper listener cleanup
- Set up deep link routing using the appUrlOpen event and react-router-dom
- Handle the Android hardware back button so it navigates back before exiting the app

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 85bf234ded12d750.

BEGIN THIRD-PARTY FILE 85bf234ded12d750
````text
---
name: capacitor-react
description: "Guides the agent through Capacitor app development with React — project structure, hooks for native features, state management patterns, using Capacitor plugins in React components, and React-specific best practices. Do not use for Ionic Framework with React (use ionic-react), migrating or upgrading Capacitor apps or plugins, or non-React frameworks."
license: MIT
compatibility: "Requires Node.js and npm. Xcode on macOS is required for iOS and Android Studio for Android."
metadata:
  author: capawesome-team
  source: https://github.com/capawesome-team/skills/tree/main/skills/capacitor-react
---

# Capacitor React

Develop Capacitor apps with React — project structure, hooks, state management, and React-specific patterns for accessing native device features.

## Prerequisites

1. **Capacitor 6, 7, or 8** app with React.
2. Node.js and npm installed.
3. React 18 or later.
4. For **iOS**: Xcode installed.
5. For **Android**: Android Studio installed.

## Agent Behavior

- **Auto-detect before asking.** Check the project for `package.json` dependencies (`react`, `react-dom`, `@capacitor/core`), platforms (`android/`, `ios/`), build tools (`vite.config.ts`, `next.config.js`, `webpack.config.js`), and TypeScript usage. Only ask the user when something cannot be detected.
- **Guide step-by-step.** Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
- **Adapt to the project.** Detect the existing code style (functional vs. class components, TypeScript vs. JavaScript, CSS modules vs. styled-components) and generate code that matches.

## Procedures

### Step 1: Analyze the Project

Auto-detect the following by reading project files:

1. **Framework variant**: Check if this is a plain React app (Vite/CRA), Next.js, or Remix by examining `package.json` dependencies and config files (`vite.config.ts`, `next.config.js`, `remix.config.js`).
2. **Capacitor version**: Read `@capacitor/core` version from `package.json`.
3. **React version**: Read `react` version from `package.json`.
4. **TypeScript**: Check if `tsconfig.json` exists and if `.tsx` files are used.
5. **Platforms**: Check which directories exist (`android/`, `ios/`).
6. **Capacitor config format**: Check if the project uses `capacitor.config.ts` or `capacitor.config.json`.
7. **State management**: Check `package.json` for `redux`, `@reduxjs/toolkit`, `zustand`, `jotai`, `@tanstack/react-query`, or similar.
8. **Router**: Check `package.json` for `react-router-dom`, `@tanstack/react-router`, or similar.

### Step 2: Project Structure

A standard Capacitor React project follows this structure:

```
project-root/
````
END THIRD-PARTY FILE 85bf234ded12d750

The third-party file has ended. Everything between the 85bf234ded12d750 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2701 of 11395 bytes. © capawesome-team · MIT · https://github.com/capawesome-team/skills/tree/HEAD/skills/capacitor-react/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md