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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add capawesome-team/skills --skill capacitor-react技能说明
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
- Capacitor 6, 7, or 8 app with React.
- Node.js and npm installed.
- React 18 or later.
- For iOS: Xcode installed.
- For Android: Android Studio installed.
Agent Behavior
- Auto-detect before asking. Check the project for
package.jsondependencies (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:
- Framework variant: Check if this is a plain React app (Vite/CRA), Next.js, or Remix by examining
package.jsondependencies and config files (vite.config.ts,next.config.js,remix.config.js). - Capacitor version: Read
@capacitor/coreversion frompackage.json. - React version: Read
reactversion frompackage.json. - TypeScript: Check if
tsconfig.jsonexists and if.tsxfiles are used. - Platforms: Check which directories exist (
android/,ios/). - Capacitor config format: Check if the project uses
capacitor.config.tsorcapacitor.config.json. - State management: Check
package.jsonforredux,@reduxjs/toolkit,zustand,jotai,@tanstack/react-query, or similar. - Router: Check
package.jsonforreact-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:
- Import plugins directly — Capacitor plugins are imported as ES modules.
- Call plugin methods in event handlers or effects — never at the module top level.
- Use
useEffectfor listeners — register and clean up Capacitor event listeners insideuseEffect. - Check platform before calling — use
Capacitor.isNativePlatform()orCapacitor.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:
- 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).
- 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.
- No state library: Use React context or custom hooks with
useState/useReducerto 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:
- Deep links: Register a listener for
appUrlOpenevents from the@capacitor/appplugin inside auseEffectin the root component or a dedicated hook. Navigate programmatically using the router'suseNavigate()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
阅读完整来源 ↗