MCPInstall

framework-to-capacitor

by cap-goFrontend & Design

Configures a web framework build so Capacitor can ship it as an iOS/Android app. Use for Next.js static export (output 'export', out/), Nuxt 4 (ssr false, nuxt generate, .output/public), Angular (dist/ /browser), SvelteKit adapter-static (SvelteKit 2 svelte.config.js or SvelteKit 3 vite.config), React/Vue/Svelte/Solid on Vite, and React Router framework SPA mode. Covers webDir mismatch, blank white screen after cap sync, missing index.html, SSR/API routes/middleware/server actions that cannot run in the app, next/image errors, deep-link reloads landing on the home page, router base paths, and env variables. Do not use for whole-app store readiness (webapp-to-capacitor), Cordova projects (cordova-to-capacitor), Capacitor major upgrades (capacitor-app-upgrades), or UI kits (ionic-design, konsta-ui, tailwind-capacitor).

Installs
872
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/cap-go/capgo-skills --skill framework-to-capacitor
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads framework-to-capacitor automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Framework to Capacitor

Make a framework emit a static bundle that Capacitor can copy into the native projects, and wire the scripts so build -> cap sync is one step.

When to Use

TRIGGER when:

  • Adding Capacitor to a Next.js, Nuxt, Angular, SvelteKit, Vite (React/Vue/Svelte/Solid), React Router, Qwik, or Astro project.
  • npx cap sync fails with The web assets directory (./dist) must contain an index.html file. or Could not find the web assets directory: ./dist.
  • The app launches to a white screen or loads the wrong page after a reload or deep link.
  • The framework build fails because of SSR-only features (output: 'export' errors, prerender errors, API routes, middleware, server actions).

Do not use for:

  • Store readiness, native UX, permissions, billing, review risk -> webapp-to-capacitor, capacitor-app-store, capacitor-apple-review-preflight.
  • Cordova/PhoneGap apps -> cordova-to-capacitor.
  • Capacitor version upgrades -> capacitor-app-upgrades.
  • Live updates setup -> capgo-live-updates.

Live Project Snapshot

Detected framework and build dependencies: !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const matchers=['next','nuxt','react','react-router','@react-router/dev','vue','@angular/core','@angular/build','@sveltejs/kit','@sveltejs/adapter-static','@builder.io/qwik','@qwik.dev/core','astro','@remix-run/react','solid-js','@solidjs/start','vite','@capacitor/core','@capacitor/cli'];const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(matchers.includes(name))out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(['build','export','generate','sync','cap:sync'].includes(name))out.push('scripts.'+name+'='+cmd)}console.log(out.join('\n'))"

Relevant framework and Capacitor config paths: !find . -maxdepth 3 -not -path '*/node_modules/*' \( -name 'next.config.*' -o -name 'nuxt.config.*' -o -name 'vite.config.*' -o -name 'angular.json' -o -name 'svelte.config.*' -o -name 'react-router.config.*' -o -name 'astro.config.*' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' \)

Core Facts (apply to every framework)

  • Capacitor copies webDir into the native app. It never runs Node. SSR, API routes, middleware, ISR, server actions, cookies()/headers(), and image optimization servers do not exist at runtime. Move them to a hosted backend and call it over HTTPS.
  • The app is served from capacitor://localhost (iOS) and https://localhost (Android). Your backend must allow those origins for CORS, or use CapacitorHttp.
  • Capacitor's local server returns the root index.html for any path without a file extension. History-mode SPA routing (createWebHistory, BrowserRouter, Angular default PathLocationStrategy) works; hash routing is not required.
  • The same fallback means per-route HTML files (Next.js export, SvelteKit prerender, Astro) are never served for extensionless URLs. A cold start or location.reload() on /settings/ loads the root index.html. Keep navigation client-side and route deep links through App.addListener('appUrlOpen', ...) + your router.
  • Asset paths: keep the framework's base at / (Vite base, Angular <base href="/">, Next basePath/assetPrefix unset). A CDN or sub-path base used for web hosting breaks asset loading in the app; use a separate mobile build config.
  • Environment variables are inlined at build time (NEXT_PUBLIC_*, VITE_*, NUXT_PUBLIC_*, PUBLIC_* in SvelteKit, Angular environment.ts). Rebuild before every cap sync; never point production builds at localhost.
  • Capacitor 8 needs Node 22+. Capacitor 9 (currently @next, not GA) needs Node 24+. Some framework majors also raise Node minimums (SvelteKit 3: Node 22.17+).

Procedure

  1. Read the snapshot. Identify framework, major version, and the current build output directory. If several apps live in a monorepo, ask which one ships to mobile.
  2. Load the matching reference (only the one in play):
Framework in package.jsonLoadwebDir
nextreferences/nextjs.mdout
nuxtreferences/vue-nuxt.md.output/public
vue + vite (no Nuxt)references/vue-nuxt.mddist
react + vite, react-router/@react-router/dev, CRAreferences/react.mddist, build/client, or build
@angular/corereferences/angular.mddist/<project>/browser
@sveltejs/kit or svelte + vitereferences/svelte.mdbuild or dist
solid-js, @builder.io/qwik/@qwik.dev/core, astro, @remix-run/*references/other-frameworks.mdvaries
  1. Inventory server-only features before changing config (grep for app/api/, pages/api/, middleware.ts/proxy.ts, 'use server', getServerSideProps, +page.server.ts, +server.ts, server/api/, @angular/ssr). Report the list to the user and agree where each moves (external API, client fetch, or native plugin) before deleting anything.
  2. Make the static build work and inspect the output directory: it must contain index.html at its root.
  3. Install and initialise Capacitor (use the repo's package manager for installs):
npm install @capacitor/core @capacitor/ios @capacitor/android
npm install -D @capacitor/cli
npx cap init "App Name" com.company.app --web-dir <webDir>
npx cap add ios
npx cap add android
  1. Add one script that always builds before syncing, e.g. "build:mobile": "<framework build> && cap sync".
  2. Run the verification below on both platforms.

Minimal config (androidScheme: 'https' is the default since Capacitor 6; only set it to keep an older origin):

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.company.app',
  appName: 'App Name',
  webDir: 'dist',
};

export default config;

Live Reload

Capacitor 8: npx cap run ios -l --host <LAN-IP> --port <port>. Capacitor 9: npx cap run ios --url http://<LAN-IP>:<port> (the -l/--host/--port/--https flags were merged into --url). The dev server must listen on the LAN (--host 0.0.0.0 / server.host: true in Vite). Never commit server.url into capacitor.config.*.

Verification

npm run build
test -f <webDir>/index.html && echo "index.html OK"
npx cap sync
npx cap run ios        # or open in Xcode
npx cap run android

Then on device/simulator:

  • App opens on the first screen without a white flash beyond the splash.
  • Navigate to a nested route, background + resume, and confirm the route survives.
  • Open a deep link (xcrun simctl openurl booted <url> / adb shell am start -a android.intent.action.VIEW -d <url>) and confirm it lands on the right screen.
  • Inspect the WebView (Safari Web Inspector / chrome://inspect) for 404s on JS/CSS and CORS errors.
  • grep -rn "localhost:\|127.0.0.1" <webDir> returns nothing unexpected.

Error Handling

Symptom / errorCauseFix
The web assets directory (./dist) must contain an index.html file.webDir points at the wrong folder or SSR build has no index.htmlSet webDir to the static output listed above; enable static/SPA mode
Could not find the web assets directory: ./out.Build not run or different output dirRun the build first; match webDir to the real folder
White screen, console Failed to load resource for /_next/... or /assets/...Non-root base path / CDN assetPrefixUse / base for the mobile build
White screen, no 404sJS error at boot (often window/document during prerender, or SSR-only import)Inspect WebView console; guard browser-only code
Reload or deep link opens home page or hydration errorCapacitor serves root index.html for extensionless pathsClient-side navigation + appUrlOpen handler; see framework reference
Page "/x/[id]" is missing "generateStaticParams()" (Next.js)Dynamic route in export modePre-generate params or switch to a query-string/client route
Image Optimization using the default loader is not compatible with output: exportnext/image default loaderimages.unoptimized: true or custom loader
API call works in browser, fails on deviceCORS for capacitor://localhost / https://localhost, or localhost URL baked inAllow origins on backend, or enable CapacitorHttp; fix env var

References

  • references/nextjs.md - Next.js 14-16 static export, App Router traps, dynamic routes, images.
  • references/react.md - Vite React, React Router framework SPA mode, CRA legacy.
  • references/vue-nuxt.md - Vue + Vite, Nuxt 4 SPA generate.
  • references/angular.md - Angular 17+ application builder output, SSR removal.
  • references/svelte.md - SvelteKit 2 and 3 with adapter-static, plain Svelte + Vite.
  • references/other-frameworks.md - Solid, Qwik, Astro, Remix v2.

Related skills: webapp-to-capacitor (store readiness), capacitor-deep-linking, safe-area-handling, capgo-live-updates.

FAQ

What does the framework-to-capacitor skill do?

Configures a web framework build so Capacitor can ship it as an iOS/Android app. Use for Next.js static export (output 'export', out/), Nuxt 4 (ssr false, nuxt generate, .output/public), Angular (dist/ /browser), SvelteKit adapter-static (SvelteKit 2 svelte.config.js or SvelteKit 3 vite.config), React/Vue/Svelte/Solid on Vite, and React Router framework SPA mode. Covers webDir mismatch, blank white screen after cap sync, missing index.html, SSR/API routes/middleware/server actions that cannot run in the app, next/image errors, deep-link reloads landing on the home page, router base paths, and env variables. Do not use for whole-app store readiness (webapp-to-capacitor), Cordova projects (cordova-to-capacitor), Capacitor major upgrades (capacitor-app-upgrades), or UI kits (ionic-design, konsta-ui, tailwind-capacitor).

How do I install framework-to-capacitor?

Run npx skills add https://github.com/cap-go/capgo-skills --skill framework-to-capacitor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/framework-to-capacitor/ (personal) or .claude/skills/framework-to-capacitor/ (project).

Which AI agents can use framework-to-capacitor?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is framework-to-capacitor safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains framework-to-capacitor?

It is published by cap-go in cap-go/capgo-skills. It has 872 recorded installs.

More from cap-go/capgo-skills

View all →

capacitor-best-practices

cap-go/capgo-skills

Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).

Code Quality & Workflow2.7K installs

ionic-design

cap-go/capgo-skills

Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).

Frontend & Design1.6K installs

capacitor-plugins

cap-go/capgo-skills

Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).

Frontend & Design1.6K installs

debugging-capacitor

cap-go/capgo-skills

Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).

Code Quality & Workflow1.3K installs

capacitor-testing

cap-go/capgo-skills

Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor

Testing & QA1.3K installs

safe-area-handling

cap-go/capgo-skills

Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).

Mobile1.3K installs

Popular frontend & design skills

View category →

setup-matt-pocock-skills

mattpocock/skills

Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

Frontend & Design1.1M installs

frontend-design

anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

OfficialFrontend & Design1M installs

hyperframes-animation

heygen-com/hyperframes

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Frontend & Design1M installs

prototype

mattpocock/skills

Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

Frontend & Design999.2K installs

hyperframes-core

heygen-com/hyperframes

The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Frontend & Design930.5K installs

vercel-react-best-practices

vercel-labs/agent-skills

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

OfficialFrontend & Design843.1K installs