Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

capacitor-react

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.

capawesome-team · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add capawesome-team/skills --skill capacitor-react

About this skill


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/
├── android/                  # Android native project (generated by Capacitor)
├── ios/                      # iOS native project (generated by Capacitor)
├── public/
├── src/
│   ├── components/           # Reusable UI components
│   ├── hooks/                # Custom React hooks (including native feature hooks)
│   ├── pages/                # Page/route components
│   ├── services/             # Service modules for Capacitor plugin calls
│   ├── App.tsx               # Root component
│   └── main.tsx              # Entry point
├── capacitor.config.ts       # Capacitor configuration
├── package.json
├── tsconfig.json
└── vite.config.ts            # Or other bundler config

If the project does not follow this structure, adapt all guidance to the project's actual directory layout. Do not restructure the project unless the user explicitly asks.

Step 3: Using Capacitor Plugins in React

Read references/plugin-usage-patterns.md for detailed patterns on how to use Capacitor plugins in React components and hooks.

Key principles:

  1. Import plugins directly — Capacitor plugins are imported as ES modules.
  2. Call plugin methods in event handlers or effects — never at the module top level.
  3. Use useEffect for listeners — register and clean up Capacitor event listeners inside useEffect.
  4. Check platform before calling — use Capacitor.isNativePlatform() or Capacitor.getPlatform() to guard platform-specific calls.

Step 4: Custom Hooks for Native Features

Read references/custom-hooks.md for reusable custom hook patterns that wrap Capacitor plugins.

Custom hooks encapsulate native feature access and provide a React-idiomatic API. When the user needs to access a native feature from multiple components, create a custom hook in src/hooks/ (or wherever the project keeps hooks).

Step 5: State Management with Native Data

When the project uses a state management library, integrate native data as follows:

  1. React Query / TanStack Query: Use query functions that call Capacitor plugins. This works well for data that is fetched from native APIs (e.g., device info, contacts, filesystem reads).
  2. Redux / Zustand / Jotai: Dispatch actions or update atoms from Capacitor plugin callbacks. Keep native API calls in action creators or service modules, not in reducers or stores.
  3. No state library: Use React context or custom hooks with useState/useReducer to share native data across components.

Do not recommend adding a state management library unless the user's requirements justify it.

Step 6: Navigation and Deep Links

If the project uses react-router-dom or another router:

  1. Deep links: Register a listener for appUrlOpen events from the @capacitor/app plugin inside a useEffect in the root component or a dedicated hook. Navigate programmatically using the router's useNavigate() hook.
import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { App, URLOpenListenerEvent } from '@capacitor/app';

const useDeepLinks = () => {
  const navigate = useNavigate();

  useEffect(() => {
    const listener = App.addListener('appUrlOpen', (event: URLOpenListenerEvent) => {
      const path = new URL(event.url).pathname;
      navigate(p
Read the complete source ↗