framework-to-capacitor

What this skill does

# Framework to Capacitor Integration

Comprehensive guide for integrating web frameworks with Capacitor to build mobile apps.

## When to Use This Skill

- Converting a Next.js app to a mobile app
- Integrating React, Vue, Angular, or Svelte with Capacitor
- Configuring static exports for Capacitor
- Setting up routing for mobile apps
- Optimizing framework builds for native platforms

## 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','react','vue','@angular/core','@sveltejs/kit','@builder.io/qwik','@remix-run/react','solid-js','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','sync','cap:sync'].includes(name))out.push('scripts.'+name+'='+cmd)}console.log(out.join('\n'))"`

Relevant framework and Capacitor config paths:
!`find . -maxdepth 3 \( -name 'next.config.js' -o -name 'next.config.mjs' -o -name 'vite.config.ts' -o -name 'vite.config.js' -o -name 'angular.json' -o -name 'svelte.config.js' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' \)`

## Framework Support Matrix

| Framework | Static Export | SSR Support | Recommended Approach |
|-----------|--------------|-------------|---------------------|
| Next.js | ✅ Yes | ❌ No | Static export (output: 'export') |
| React | ✅ Yes | N/A | Create React App or Vite |
| Vue | ✅ Yes | ❌ No | Vite or Vue CLI |
| Angular | ✅ Yes | ❌ No | Angular CLI |
| Svelte | ✅ Yes | ❌ No | SvelteKit with adapter-static |
| Remix | ✅ Yes | ❌ No | SPA mode |
| Solid | ✅ Yes | ❌ No | Vite |
| Qwik | ✅ Yes | ❌ No | Static site mode |

**CRITICAL**: Capacitor requires **static HTML/CSS/JS files**. SSR (Server-Side Rendering) does not work in native apps.

---

## Next.js + Capacitor

Next.js is popular for React apps. Capacitor requires static export.

### Step 1: Create or Update next.config.js

**For Next.js 13+ (App Router):**
```javascript
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true, // Required for static export
  },
  trailingSlash: true, // Helps with routing on mobile
};

module.exports = nextConfig;
```

**For Next.js 12 (Pages Router):**
```javascript
// next.config.js
module.exports = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  trailingSlash: true,
};
```

### Step 2: Build Static Files

```bash
npm run build
```

This creates an `out/` directory with static files.

### Step 3: Install Capacitor

```bash
npm install @capacitor/core @capacitor/cli
npx cap init
```

**Configuration:**
- **App name**: Your app name
- **App ID**: com.company.app
- **Web directory**: `out` (Next.js static export output)

### Step 4: Configure Capacitor

**Create capacitor.config.ts:**
```typescript
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.company.app',
  appName: 'My App',
  webDir: 'out', // Next.js static export directory
  server: {
    androidScheme: 'https',
  },
};

export default config;
```

### Step 5: Add Platforms

```bash
npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android
```

### Step 6: Build and Sync

```bash
# Build Next.js
npm run build

# Sync with native projects
npx cap sync
```

### Step 7: Run on Device

**iOS:**
```bash
npx cap open ios
# Build and run in Xcode
```

**Android:**
```bash
npx cap open android
# Build and run in Android Studio
```

### Next.js Routing Considerations

**Use hash routing for complex apps:**

```typescript
// next.config.js
const nextConfig = {
  output: 'export',
  basePath: '',
  assetPrefix: '',
};
```

**Or use Next.js's built-in routing** (works with `trailingSlash: true`).

### Next.js Image Optimization

**next/image doesn't work with static export. Use alternatives:**

**Option 1: Use standard img tag**
```jsx
// Instead of next/image
<img src="/images/photo.jpg" alt="Photo" />
```

**Option 2: Use a custom Image component**
```tsx
// components/CapacitorImage.tsx
import { Capacitor } from '@capacitor/core';

export const CapacitorImage = ({ src, alt, ...props }) => {
  const isNative = Capacitor.isNativePlatform();
  const imageSrc = isNative ? src : src;
  
  return <img src={imageSrc} alt={alt} {...props} />;
};
```

### Next.js API Routes

**API routes don't work in static export.** Use alternatives:

1. **External API**: Call a separate backend
2. **Capacitor plugins**: Use native features
3. **Local storage**: Use `@capacitor/preferences`

```typescript
import { Preferences } from '@capacitor/preferences';

// Save data
await Preferences.set({
  key: 'user',
  value: JSON.stringify(userData),
});

// Load data
const { value } = await Preferences.get({ key: 'user' });
const userData = JSON.parse(value || '{}');
```

### Next.js Middleware

**Middleware doesn't work in static export.** Handle logic client-side:

```typescript
// In your React components
import { useEffect } from 'react';
import { useRouter } from 'next/router';

export default function ProtectedPage() {
  const router = useRouter();

  useEffect(() => {
    const checkAuth = async () => {
      const { value } = await Preferences.get({ key: 'token' });
      if (!value) {
        router.push('/login');
      }
    };
    checkAuth();
  }, []);

  return <div>Protected content</div>;
}
```

### Complete Next.js + Capacitor Example

**package.json:**
```json
{
  "name": "my-capacitor-app",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "build:mobile": "next build && cap sync",
    "ios": "cap open ios",
    "android": "cap open android"
  },
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "@capacitor/core": "^6.0.0",
    "@capacitor/ios": "^6.0.0",
    "@capacitor/android": "^6.0.0",
    "@capacitor/camera": "^6.0.0"
  },
  "devDependencies": {
    "@capacitor/cli": "^6.0.0",
    "typescript": "^5.0.0"
  }
}
```

---

## React + Capacitor

React works great with Capacitor using Vite or Create React App.

### Option 1: Vite (Recommended)

**Create new project:**
```bash
npx create-vite@latest my-app --template react-ts
cd my-app
npm install
```

**Install Capacitor:**
```bash
npm install @capacitor/core @capacitor/cli
npx cap init
```

**Configure vite.config.ts:**
```typescript
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'dist', // Capacitor webDir
  },
});
```

**capacitor.config.ts:**
```typescript
import type { CapacitorConfig } from '@capacitor/cli';

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

export default config;
```

**Add platforms and build:**
```bash
npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android
npm run build
npx cap sync
```

### Option 2: Create React App

**Create new project:**
```bash
npx create-react-app my-app --template typescript
cd my-app
```

**Install Capacitor:**
```bash
npm install @capacitor/core @capacitor/cli
npx cap init
```

**capacitor.config.ts:**
```typescript
const config: CapacitorConfig = {
  appId: 'com.company.app',
  appName: 'My App',
  webDir: 'build', // CRA outputs to build/
};
```

**Build and sync:**
```bash
npm run build
npx cap sync
```

### React Router Configuration

**Use HashRouter for mobile:**
```tsx
import { HashRouter as Router, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/" element={<Home />} />
        <R