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:

Create or select your keystore
Enter passwords
Choose Android App Bundle (.aab)
Click Finish

Output:


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

12. Publish Your App

🅰️ Option 1 — Google Play Store

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

🅱️ Option 2 — Publish on Your Website

If you want users to download directly:

Build signed APK:
```
javascript
Build → Build APK(s)
```

Find the file:


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

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

Upload to your website:


javascript
/downloads/portfolio-app.apk

Add a download button:


javascript
<a href="/downloads/portfolio-app.apk" download>
  <button>Download Android App</button>
</a>

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:

Add PWA support:
```
javascript
npm install next-pwa
```

Update next.config.mjs:


javascript
import withPWA from 'next-pwa';

const nextConfig = withPWA({
  dest: 'public',
  register: true,
  skipWaiting: true,
  output: 'export',
});

export default nextConfig;

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"
    }
  ]
}

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.