# Build Your App with Capacitor JS: A Comprehensive Guide

## 1\. Introduction

Capacitor JS allows you to convert any **web app (like Next.js)** into a **native Android or iOS app** — without rewriting your frontend.  
It wraps your app inside a native WebView and lets you access mobile features like Camera, Storage, Push Notifications, etc.

---

## 2\. Prerequisites

Before starting, make sure you have:

| Tool | Purpose |
| --- | --- |
| Node.js (v18 or above) | Build your Next.js app |
| Android Studio | For building APK/AAB |
| Java JDK 11+ | Required for Android builds |
| Capacitor CLI | To integrate Capacitor |
| Git (optional) | Version control |

Check versions:

```javascript
node -v
npm -v
java -version
```

---

## 3\. Create and Build a Next.js App

If you don’t already have a Next.js app, create one:

```javascript
npx create-next-app@latest portfolio
cd portfolio
```

---

## 4\. Install Capacitor

Install Capacitor core packages:

```javascript
npm install @capacitor/core @capacitor/cli
```

Initialise Capacitor in your project:

```javascript
npx cap init
```

When prompted:

* **App name:** Portfolio
    
* **App ID:** com.aditya.portfolio
    
* **Web directory:** `out` (for static exports)
    

---

## 5\. Update Capacitor Config

Open `capacitor.config.ts` and set this:

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

const config: CapacitorConfig = {
  appId: 'com.aditya.portfolio',
  appName: 'Portfolio',
  webDir: 'out',
  bundledWebRuntime: false,
};

export default config;
```

---

## 6\. Export Your Next.js App

Next.js no longer supports `next export` CLI directly — use the **new config option**.

In `next.config.mjs`, add:

```javascript
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Required for static build
};

export default nextConfig;
```

Then build:

```javascript
npm run build
```

After build, Next.js will generate a static `out/` folder.

---

## 7\. Add Android Platform

Now add Android support:

```javascript
npm install @capacitor/android
npx cap add android
```

If you get an error like:

```javascript
[error] The web assets directory (.\public) must contain an index.html file.
```

👉 It means you haven’t built your app yet — **run** `npm run build` first.

Then sync your project:

```javascript
npx cap sync
```

---

## 8\. Fix Common Errors

| Error | Cause | Fix |
| --- | --- | --- |
| ❌ `Could not find web assets directory` | Missing `out` folder | Run `npm run build` again |
| ❌ `Cannot run init for non-JSON config` | You have `capacitor.config.ts` | Do not run `npx cap init` again |
| ❌ `android platform has not been added` | Android not linked | Run `npx cap add android` |
| ❌ `Asset directory not found` | Missing icon.png | See section below |

---

## 9\. Add Custom App Icon and Splash Screen

Install Capacitor Assets tool:

```javascript
npm install @capacitor/assets --save-dev
```

Create an `assets/` folder in your root:

```javascript
/portfolio/
 ├─ android/
 ├─ assets/
 │   ├─ icon.png
 │   └─ splash.png (optional)
```

Generate assets:

```javascript
npx capacitor-assets generate --android --iconBackgroundColor "#FFFFFF"
```

Sync changes:

```javascript
npx cap sync android
```

This replaces the default Capacitor icon with your custom one.

---

## 10\. Open in Android Studio

```javascript
npx cap open android
```

Android Studio will open your native project.

If you see build errors:

* Click **File → Sync Project with Gradle Files**
    
* Click **Build → Clean Project**
    
* Then **Build → Rebuild Project**
    

---

## 11\. Build the Android App

### Option 1: Debug APK

Quick test version:

```javascript
Build → Build Bundle(s)/APK(s) → Build APK(s)
```

Output:

```javascript
android/app/build/outputs/apk/debug/app-debug.apk
```

### Option 2: Release AAB (for Play Store)

```javascript
Build → Generate Signed App Bundle / APK
```

Follow the wizard:

1. Create or select your keystore
    
2. Enter passwords
    
3. Choose **Android App Bundle (.aab)**
    
4. Click **Finish**
    

Output:

```javascript
android/app/build/outputs/bundle/release/app-release.aab
```

---

## 12\. Publish Your App

### 🅰️ **Option 1 — Google Play Store**

1. Go to Play Console
    
2. Pay a one-time $25 fee
    
3. Create a new app listing
    
4. Upload your `.aab` file
    
5. Fill out:
    
    * Description
        
    * Screenshots
        
    * Privacy Policy
        
6. Submit for review  
    ✅ Google will publish after 1–3 days.
    

---

### 🅱️ **Option 2 — Publish on Your Website**

If you want users to download directly:

1. Build signed APK:
    
    ```javascript
    Build → Build APK(s)
    ```
    
2. Find the file:
    
    ```javascript
    android/app/build/outputs/apk/release/app-release.apk
    ```
    
3. Rename it (e.g. `portfolio-app.apk`)
    
4. Upload to your website:
    
    ```javascript
    /downloads/portfolio-app.apk
    ```
    
5. Add a download button:
    
    ```javascript
    <a href="/downloads/portfolio-app.apk" download>
      <button>Download Android App</button>
    </a>
    ```
    
6. Optional: Add instructions for users to enable *Install from Unknown Sources*.
    

---

### 🅾️ **Option 3 — As a Web App (PWA)**

If you want to host it on your domain:

1. Add PWA support:
    
    ```javascript
    npm install next-pwa
    ```
    
2. Update `next.config.mjs`:
    
    ```javascript
    import withPWA from 'next-pwa';
    
    const nextConfig = withPWA({
      dest: 'public',
      register: true,
      skipWaiting: true,
      output: 'export',
    });
    
    export default nextConfig;
    ```
    
3. Add a `public/manifest.json`:
    
    ```javascript
    {
      "name": "Portfolio",
      "short_name": "Portfolio",
      "start_url": "/",
      "display": "standalone",
      "background_color": "#ffffff",
      "theme_color": "#000000",
      "icons": [
        {
          "src": "/icon.png",
          "sizes": "512x512",
          "type": "image/png"
        }
      ]
    }
    ```
    
4. Deploy to:
    
    * **Vercel**
        
    * **Netlify**
        
    * **Firebase Hosting**
        
    * or your own domain
        

✅ Your site will become *installable* on Android and desktop browsers.

---

## 13\. Pro Tips

* Always rebuild after editing anything in Next.js before syncing:
    
    ```javascript
    npm run build
    npx cap sync
    ```
    
* Keep a backup of your keystore file (it’s required for updates).
    
* Use `adb install app-debug.apk` to quickly test on your phone.
    
* Use `npx cap open android` whenever you edit web assets.
    

---

---