Skip to main content

​
Overview

Vocab Vault uses Capacitor to package the web app as a native Android application. Capacitor provides a web-native runtime that allows your React app to run as a native mobile app with access to native device APIs.

​
Prerequisites

Before building for Android, ensure you have:
  • Node.js and npm installed
  • Android Studio installed and configured
  • Java Development Kit (JDK) 17 or higher
  • Android SDK (installed via Android Studio)
  • Gradle (comes with Android Studio)

​
Capacitor Configuration

The app’s Capacitor configuration is defined in capacitor.config.ts: 
const config: CapacitorConfig = {
  appId: 'com.dbcreations.vocabvault',
  appName: 'Vocab Vault',
  webDir: 'dist'
};
Configuration details:
  • appId: Unique identifier for the Android package (com.dbcreations.vocabvault)
  • appName: Display name shown to users (Vocab Vault)
  • webDir: Directory containing the built web app (dist)

​
Setup Android Platform

1

Install Capacitor CLI

The Capacitor CLI is already included in the project dependencies. Verify installation:
npx cap --version
2

Build the web app

Create a production build of the React app:
npm run build
This generates optimized files in the dist/ directory.
3

Add Android platform

If you haven’t already added the Android platform:
npx cap add android
This creates an android/ directory with the native Android project.
4

Sync web assets

Copy the web app to the native platform:
npx cap sync android
Run this command whenever you rebuild the web app.

​
Building the Android App

​
Open in Android Studio

Open the Android project in Android Studio: 
npx cap open android
This launches Android Studio with your Capacitor Android project.

​
Build from Android Studio

1

Select build variant

In Android Studio, select Build > Select Build Variant and choose:
  • debug for development builds
  • release for production builds
2

Generate APK or Bundle

  • For testing: Build > Build Bundle(s) / APK(s) > Build APK(s)
  • For Google Play: Build > Build Bundle(s) / APK(s) > Build Bundle(s)
3

Sign the release build

For production releases, you’ll need to sign the app:
  1. Generate a keystore (one-time setup)
  2. Configure signing in android/app/build.gradle
  3. Build signed APK/Bundle

​
Build from Command Line

Alternatively, build from the command line: 
# Navigate to android directory
cd android

# Build debug APK
./gradlew assembleDebug

# Build release APK (requires signing configuration)
./gradlew assembleRelease

# Build release bundle for Google Play
./gradlew bundleRelease
Built files are located in:
  • APK: android/app/build/outputs/apk/
  • Bundle: android/app/build/outputs/bundle/

​
Testing on Device

​
Using Android Studio

  1. Connect an Android device via USB or start an emulator
  2. Click the Run button (green play icon) in Android Studio
  3. Select your target device
  4. The app will be installed and launched

​
Using Command Line

# Install debug build
adb install android/app/build/outputs/apk/debug/app-debug.apk

# Run the app
adb shell am start -n com.dbcreations.vocabvault/.MainActivity

​
Updating Web Assets

Whenever you make changes to the web app:
1

Rebuild the web app

npm run build
2

Sync to native platforms

npx cap sync
3

Rebuild in Android Studio or run from CLI

No need to rebuild if using live updates, otherwise rebuild the Android app.

​
Native Plugins Used

Vocab Vault uses the following Capacitor plugins:

​
Preferences Plugin

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

// Store data
await Preferences.set({ key: 'userProgress', value: JSON.stringify(data) });

// Retrieve data
const { value } = await Preferences.get({ key: 'userProgress' });
Used for persisting user progress, preferences, and settings locally.

​
Share Plugin

import { Share } from '@capacitor/share';

await Share.share({
  title: 'Check out Vocab Vault',
  text: 'Learn coding vocabulary with flashcards!',
  url: 'https://vocabvault.app',
});
Enables native sharing functionality.

​
Deployment to Google Play

1

Create a release build

Build a signed Android App Bundle (AAB):
cd android
./gradlew bundleRelease
2

Prepare store listing

Create:
  • App icon (512x512 PNG)
  • Feature graphic (1024x500 PNG)
  • Screenshots (at least 2)
  • App description and metadata
3

Upload to Google Play Console

  1. Create an app in Google Play Console
  2. Upload the AAB file
  3. Complete store listing
  4. Submit for review

​
Troubleshooting

​
Capacitor Sync Fails

  • Ensure the web app is built: npm run build
  • Check that dist/ directory exists and contains built files
  • Verify webDir: 'dist' in capacitor.config.ts

​
Android Studio Build Errors

Gradle sync failed: 
# Clear Gradle cache
cd android
./gradlew clean
Java version mismatch:
  • Ensure JDK 17+ is installed
  • Set JAVA_HOME environment variable
  • Configure JDK in Android Studio preferences

​
Plugin Not Found

If a Capacitor plugin isn’t recognized: 
# Reinstall plugins
npm install
npx cap sync

​
Live Reload for Development

For faster development cycles, use live reload: 
# Start dev server
npm run dev

# In capacitor.config.ts, add:
server: {
  url: 'http://192.168.1.x:8080',  // Your dev machine's IP
  cleartext: true
}

# Sync and run
npx cap sync
npx cap open android
Remember to remove the server configuration before building production releases!

​
App Crashes on Launch

  1. Check Android Studio Logcat for error messages
  2. Verify all plugins are installed: npx cap sync
  3. Ensure minimum SDK version requirements are met
  4. Test in a clean build: ./gradlew clean
Use npx cap doctor to diagnose common Capacitor configuration issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us