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:

Check versions:

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:

npx create-next-app@latest portfolio
cd portfolio

---

4. Install Capacitor

Install Capacitor core packages:

npm install @capacitor/core @capacitor/cli

Initialise Capacitor in your project:

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:

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:

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

export default nextConfig;

Then build:

npm run build

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

---

7. Add Android Platform

Now add Android support:

npm install @capacitor/android
npx cap add android

If you get an error like:

[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:

npx cap sync

---

8. Fix Common Errors

---

9. Add Custom App Icon and Splash Screen

Install Capacitor Assets tool:

npm install @capacitor/assets --save-dev

Create an assets/ folder in your root:

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

Generate assets:

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

Sync changes:

npx cap sync android

This replaces the default Capacitor icon with your custom one.

---

10. Open in Android Studio

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:

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

Output:

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

Option 2: Release AAB (for Play Store)

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:

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:

    Build → Build APK(s)
   

2. Find the file:

    android/app/build/outputs/apk/release/app-release.apk
   

3. Rename it (e.g. portfolio-app.apk)

4. Upload to your website:

    /downloads/portfolio-app.apk
   

5. Add a download button:

    <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:

    npm install next-pwa
   

2. Update next.config.mjs:

    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:

    {
      "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:

    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.

---

---