Dev.to WebDev 🛠 Dev 👁 0 📖 19 min read

How to Turn Your Existing Web Project Into an Android App Using Capacitor CLI

Already built a website or web app? Here's how to turn it into a real Android app without starting over. If you've already spent hours (or days) building a web application, the last thing you probably want to do is rewr

Already built a website or web app? Here's how to turn it into a real Android app without starting over.

If you've already spent hours (or days) building a web application, the last thing you probably want to do is rewrite the entire thing just to get it running on Android.

Good news. You probably don't have to.

With Capacitor, you can take an existing web project, add Android support, and package it into an installable Android application. You can even get access to native phone features like the camera, notifications, and file system.

And you don't need to be an experienced Android developer to get started.

In this guide, I'll walk you through the process, from installing Capacitor to running your app on an Android device and generating an APK.

We'll use the command line for most of the work, so you can follow along whether you're using VS Code, VSCodium, or another editor.

Let's get into it.

What Is Capacitor?

Capacitor is an open-source tool developed by the Ionic team that allows you to turn web applications into native mobile applications.

It works with popular web frameworks like:

  • React
  • Vue
  • Angular
  • Svelte
  • Vite-based projects
  • Plain HTML, CSS, and JavaScript

Instead of rewriting your application in Java or Kotlin, Capacitor creates a native Android project that runs your web application inside an Android WebView.

Think of a WebView as a browser built into your app, except there's no address bar or browser interface.

Your app looks and behaves like a standalone application.

Capacitor also provides plugins that let your JavaScript communicate with native Android features.

One thing worth understanding: Capacitor doesn't magically convert your JavaScript into native Android code. Your web interface still runs inside a WebView. However, it's packaged as a real Android application that you can install, test, and potentially distribute through Google Play.

For many existing web applications, that's exactly what you need.

What You'll Need Before Starting

Before we touch the command line, let's make sure you have everything installed.

1. An Existing Web Project

I'm assuming you already have a working web application.

It should have a package.json file and a build process that produces static web files, typically inside a folder named dist, build, or www.

For example, a Vite or React project might look something like this:

my-project/
├── node_modules/
├── public/
├── src/
├── index.html
├── package.json
└── vite.config.js

If your project already runs in a browser, that's a good starting point.

However, your app must be capable of producing a web build. Projects that depend on a server to render every page may need additional configuration before they can work with Capacitor.

2. Node.js and npm

Capacitor uses Node.js and npm to install packages and run commands.

For Capacitor 8, you'll need Node.js 22 or newer.

Download Node.js here:

https://nodejs.org/

Once installed, open a terminal and check your version:

node -v

You can also check npm:

npm -v

If both commands return version numbers, you're good to go.

3. Android Studio

Even though we're using the Capacitor CLI, you'll still need Android development tools.

The easiest way to get them is by installing Android Studio.

Download it here:

https://developer.android.com/studio

For Capacitor 8, you'll need Android Studio 2025.2.1 or newer.

During installation, make sure the Android SDK and associated development tools are installed.

You can check these afterward by opening Android Studio and navigating to:

Tools → SDK Manager

You'll want the Android SDK Platform, SDK Build-Tools, SDK Platform-Tools, and other required components.

Capacitor 8 supports Android 7.0 (API 24) and newer, although you'll generally want a recent SDK installed for development.

You don't normally need to install Java separately. Android Studio includes the appropriate Java Development Kit (JDK).

Tip: You can do this on Windows, Linux, or macOS. You don't need a Mac to build an Android app.

Step 1: Open Your Existing Project

Let's start with the project you've already built.

Open your terminal and navigate to your project's root directory.

For example:

cd my-project

Make sure you're in the directory containing your package.json file.

You can check that by running:

ls

On Windows Command Prompt, use:

dir

If your dependencies aren't installed yet, run:

npm install

Before going any further, it's a good idea to make sure the existing application builds successfully.

npm run build

For a typical Vite project, this generates a dist folder containing the files that will eventually be packaged into your Android application.

If your project uses a different build command, use that instead.

Important: If your web project doesn't build successfully, fix that first. Capacitor won't fix problems with your existing application.

Step 2: Install Capacitor

Now we're ready to add Capacitor.

From your project's root directory, run:

npm install @capacitor/core

This installs the core Capacitor runtime.

Next, install the Capacitor command-line interface:

npm install -D @capacitor/cli

The CLI is what we'll use to initialize Capacitor, create the Android project, sync our files, and run the application.

You can confirm it's installed by running:

npx cap --version

You should see a version number.

What Does npx Mean?

You'll notice that we're using npx instead of typing capacitor directly.

npx allows us to execute the Capacitor CLI installed in our project without installing it globally on our computer.

That also makes it easier to keep different projects using their own versions of Capacitor.

Step 3: Initialize Capacitor

Now we need to tell Capacitor a little about our application.

Run:

npx cap init

Capacitor will guide you through the initial setup.

You'll be asked for information such as your app's name and app ID.

For example:

App Name:

My Awesome App

App ID:

com.example.myawesomeapp

The app name is the human-readable name of your application.

The app ID is a unique identifier used by Android to distinguish your app from other applications.

It typically follows a reverse-domain naming format.

If you own example.com, you might use:

com.example.myawesomeapp

You don't technically need to own a domain to experiment with Capacitor, but for a published app, use an identifier that you control and that won't conflict with another application.

Choose carefully. Changing an app's ID after publishing it can cause problems with updates and distribution.

Understanding the Capacitor Configuration File

Once initialization finishes, Capacitor creates a configuration file, usually called:

capacitor.config.ts

Here's an example:

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

const config: CapacitorConfig = {
  appId: 'com.example.myawesomeapp',
  appName: 'My Awesome App',
  webDir: 'dist',
};

export default config;

There are three important settings here.

appId is your application's unique identifier.

appName is your application's name.

webDir tells Capacitor where to find your compiled web application.

That last setting is especially important.

If you're using Vite, it's commonly:

webDir: 'dist'

If your build process outputs to a folder named build, use:

webDir: 'build'

Capacitor must point to the directory containing your built web files, including index.html.

If this is configured incorrectly, your Android app may launch with a blank screen or Capacitor may fail to sync the project.

Also, your built index.html must contain a <head> element so Capacitor can inject the code it needs.

Step 4: Install Android Support

Now that Capacitor is configured, let's add Android.

Run:

npm install @capacitor/android

This installs the Android platform package.

Next, generate the native Android project:

npx cap add android

Capacitor will create a new folder in your project:

android/

Your project should now look something like this:

my-project/
├── android/
├── dist/
├── node_modules/
├── public/
├── src/
├── capacitor.config.ts
├── package.json
└── vite.config.js

That new android directory contains the native Android project, including its Gradle configuration and Android-specific files.

You generally won't need to edit these files just to get started.

But they're there when you need to customize things like permissions, app appearance, or native functionality.

Don't delete the Android folder. Once you begin customizing your app, that folder becomes an important part of your project. It's also a good idea to keep it under version control with Git.

Step 5: Build Your Web Application

Before transferring our application into Android, we need to build the latest version of our web project.

Run:

npm run build

This creates the production-ready web files.

For a typical Vite application, the result will look similar to:

dist/
├── assets/
└── index.html

These are the files Capacitor will copy into the Android project.

Here's something important to remember:

Capacitor doesn't automatically rebuild your web application every time you change your code.

If you update your React components, change your CSS, or modify your JavaScript, you'll need to build your web project again before syncing those changes into Android.

We'll cover that workflow shortly.

Step 6: Sync Your Project With Android

Now we need to copy the web application into our native Android project.

Run:

npx cap sync android

This command does two main things:

  1. Copies your compiled web files into the Android project.
  2. Updates native dependencies and plugin configuration.

After syncing, your Android project contains the latest version of your built web application.

You can also run:

npx cap sync

That syncs all native platforms you've added.

Since we're only working with Android, I prefer specifying the platform explicitly.

The Three Commands You'll Use Most

Once your project is set up, these commands will become part of your normal workflow:

npm run build
npx cap sync android
npx cap open android

Build your web app, sync it, and open the Android project.

Pretty straightforward.

Step 7: Open Your App in Android Studio

Now comes the fun part.

Let's see your application running as an Android app.

Run:

npx cap open android

Capacitor should launch Android Studio and open your generated Android project.

The first time you open it, Android Studio may need to download dependencies and perform a Gradle sync.

Let that process finish before trying to run the app.

If Android Studio doesn't open automatically, you can launch it yourself and open the android folder inside your project.

Running Your App in an Android Emulator

If you don't have an Android phone available, you can test your app using an emulator.

In Android Studio:

  1. Open Device Manager.
  2. Select Create Device.
  3. Choose a phone model.
  4. Select and download an Android system image, if needed.
  5. Finish creating the virtual device.
  6. Start the emulator.
  7. Select that emulator as your deployment target.
  8. Click the Run button.

Android Studio will build your application and install it on the virtual Android device.

If everything is configured correctly, your existing web application should now appear as an Android app.

No rewriting everything in Kotlin required.

Running Your App on a Real Android Phone

Personally, I prefer testing on a physical device whenever possible.

An emulator is useful, but it's not quite the same as seeing how your app performs on an actual phone.

First, enable Developer Options on your Android device.

On many Android phones, you can do this by going to:

Settings → About Phone → Build Number

Tap the build number seven times.

The exact menu location may vary depending on your device.

Next, find Developer Options and enable USB Debugging.

Connect your phone to your computer with a USB cable, then approve the debugging authorization prompt on your phone.

Your device should become available in Android Studio.

Select it and click Run.

Android Studio will install and launch your application directly on your phone.

Can You Run the App Without Opening Android Studio?

Yes.

Capacitor provides a command for that:

npx cap run android

This command syncs the native project, builds the Android app, and deploys it to a selected device or emulator.

If multiple devices are available, Capacitor will prompt you to choose one.

Just remember that this doesn't replace your web framework's production build command. If your web code has changed, run npm run build first.

Step 8: Generate an APK File

At this point, you've got an Android application running.

But what if you want an APK that you can manually install or share with someone for testing?

You can generate one using Android's Gradle build tools.

Open your terminal and navigate into the Android folder:

cd android

On Linux or macOS, run:

./gradlew assembleDebug

On Windows Command Prompt, run:

gradlew.bat assembleDebug

Gradle will compile your Android project and produce a debug APK.

Once the build finishes, look for:

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

This is an installable Android package.

You can transfer the file to an Android device and install it, provided the device allows installation from that source.

You may need to approve an Android security prompt before installing.

What's the Difference Between a Debug APK and a Release APK?

A debug APK is intended for testing and development.

It's signed using a development debug key.

A release APK is intended for distribution and needs to be properly signed using your release signing credentials.

For quick testing on your own phone, a debug APK is usually fine.

For publishing or distributing a production application, you'll want a release build.

Step 9: Build a Release Version for Google Play

If your goal is to publish your app to the Google Play Store, there's another step.

Google Play normally expects new applications to be uploaded as an Android App Bundle (AAB) rather than a standard APK.

To create one, open your Android project in Android Studio.

Then navigate to:

Build → Generate Signed Bundle / APK

Select:

Android App Bundle

Follow the wizard to create or select a signing keystore.

The keystore contains the credentials used to sign your application.

You'll be asked to provide information including a keystore password, key alias, and key password.

Keep these credentials safe.

Losing access to your signing keys can create serious problems when maintaining or distributing your application. If you use Google Play App Signing, follow Google's guidance for managing your upload key.

Once the signed release bundle has been generated, you can upload it through the Google Play Console.

You can also use Capacitor's CLI to produce signed builds:

npx cap build android

This command supports signed APK and AAB builds, but requires the appropriate signing configuration.

For your first release, I recommend using Android Studio's signing wizard because it's easier to understand what's happening.

Before publishing: You'll also need to prepare your store listing, screenshots, privacy information, and any other requirements that apply to your app. Simply generating an AAB doesn't guarantee Play Store approval.

Step 10: Updating Your Android App After Making Changes

Here's where people sometimes get confused.

Let's say you've generated your Android app, but then you go back to your existing project and change a few things.

Maybe you fix a bug, add a button, or redesign a page.

How do you get those changes into the Android version?

Easy.

From your web project's root directory, run:

npm run build

Then:

npx cap sync android

Now you can run the app again in Android Studio or through the CLI:

npx cap run android

That's it.

The updated web files will be bundled with the rebuilt Android application.

A Handy Shortcut

If you find yourself doing this constantly, you can add an npm script to your package.json.

For example, add this to your existing scripts section:

{
  "scripts": {
    "android:sync": "npm run build && cap sync android"
  }
}

Keep any scripts already in your project. You only need to add the new android:sync entry.

Now you can simply run:

npm run android:sync

It builds your web app and syncs the result with Android.

One command instead of two.

You can also add:

"android:run": "npm run android:sync && cap run android"

Then use:

npm run android:run

This builds your web project, syncs it, and runs the Android application on a connected device or emulator.

It's a small convenience, but definitely useful when you're making frequent changes.

Step 11: Add Native Android Features

One of the nicest things about Capacitor is that you're not limited to displaying a website.

You can access native device functionality through plugins.

For example, let's say your app needs to use the phone's camera.

Capacitor has an official camera plugin.

Install it:

npm install @capacitor/camera

Then sync the plugin with Android:

npx cap sync android

In your JavaScript or TypeScript application, you can import the camera functionality.

Here's a basic example:

import { Camera, CameraResultType } from '@capacitor/camera';

async function takePhoto() {
  const photo = await Camera.getPhoto({
    quality: 90,
    allowEditing: false,
    resultType: CameraResultType.Uri
  });

  console.log('Photo URL:', photo.webPath);

  return photo.webPath;
}

This opens the camera interface and returns a reference to the captured image.

You could then display the photo in your application using its webPath.

Obviously, a real application will need additional code to handle canceled requests, errors, and whatever you intend to do with the image.

But this gives you an idea of how native functionality can be added without completely changing your application's architecture.

Other Capacitor plugins provide access to things like:

  • Geolocation
  • Local notifications
  • Device information
  • File storage
  • Haptic feedback
  • Network status
  • App lifecycle events

Some functionality requires additional Android permissions or native configuration, so always check the documentation for the plugin you're installing.

The official plugins are listed here:

https://capacitorjs.com/docs/plugins

Common Problems and How to Fix Them

Things don't always go perfectly the first time, especially when you're combining web development tools with Android development tools.

Here are a few problems you might run into.

Problem 1: The Android App Opens to a Blank Screen

This is one of the most common problems.

Usually, it means your web files weren't built, weren't copied correctly, or aren't loading properly.

First, check your capacitor.config.ts file.

Make sure the webDir setting points to the correct build output directory.

For example:

webDir: 'dist'

Next, rebuild your application:

npm run build

Then sync:

npx cap sync android

Run the Android app again.

If it still shows a blank screen, check Android Studio's Logcat and the WebView's JavaScript console.

For Vite applications, also check whether your build uses absolute asset paths that don't work correctly inside Capacitor. Relative asset paths may be necessary depending on your setup.

Problem 2: Capacitor Can't Find Your Web Assets

You might encounter an error saying Capacitor can't find the web assets directory.

This typically means the build output folder doesn't exist or your configuration points to the wrong location.

Run:

npm run build

Then verify that the expected folder exists and contains an index.html file.

Make sure webDir matches that folder.

Problem 3: My Changes Aren't Appearing in Android

You updated your web application, but Android is still showing the old version.

Most likely, you forgot to rebuild or sync.

Run:

npm run build
npx cap sync android

Then rebuild and run the Android application.

Remember, Capacitor packages your built files, not your live development server, unless you've specifically configured a live-reload workflow.

Problem 4: Android Studio Shows Gradle Errors

Gradle is Android's build system.

If Android Studio shows a Gradle error, first check that you've installed the required Android SDK components.

You can also try syncing Gradle again from Android Studio:

File → Sync Project with Gradle Files

If the error mentions Java, confirm that Android Studio is using a compatible Gradle JDK.

Also make sure your Android Studio version meets your installed Capacitor version's requirements.

Avoid randomly changing Gradle or Java versions without understanding the error. It's easy to introduce new problems while trying to fix the original one.

Problem 5: The App Works in My Browser but Not on Android

This can happen for several reasons.

Your application might rely on browser features that behave differently inside a WebView.

It might also be trying to connect to an API or development server that isn't accessible from the phone.

For example, if your code connects to:

http://localhost:3000

That usually won't connect to the development server running on your computer.

On an Android device, localhost refers to the device itself.

You'll need to configure an accessible backend URL or use an appropriate development networking setup.

Also check for CORS restrictions, blocked HTTP requests, authentication redirect issues, and browser APIs that need native equivalents.

For production applications, use HTTPS for network communication wherever possible.

Problem 6: My React Router Pages Don't Work

Single-page applications often use client-side routing.

If you're using React Router or a similar routing library, make sure your routing strategy works inside the Android WebView.

Some applications may require adjustments to their routing configuration.

For example, using hash-based routing can be an option when history-based routing causes problems.

But don't change your entire routing setup unless you've confirmed there's actually an issue.

A Few Things to Know Before Publishing

Getting your existing web application running on Android is a great first step.

But a working Android build doesn't automatically mean the application is ready for users.

There are a few things I recommend checking first.

Make Sure Your App Works Well on Mobile

If your existing project was designed mainly for desktop browsers, you'll probably need to make some adjustments.

Buttons need to be easy to tap, text needs to be readable, and layouts should adapt to smaller screens.

Also test how your app behaves with the Android keyboard, the system back button, and different screen sizes.

Give Your App a Proper Icon

Android apps need an appropriate launcher icon.

You can customize your app's Android resources directly or use Capacitor's asset generation tooling.

Check out:

https://github.com/ionic-team/capacitor-assets

It's worth taking the time to create a proper app icon instead of leaving the default Capacitor branding.

Think About Offline Functionality

A Capacitor app can package its interface locally, but that doesn't mean every feature automatically works offline.

If your application relies on a remote API, database, or authentication service, those features may still require an internet connection.

Plan for poor connections and decide what should happen when users go offline.

Don't Put Private Keys in Your Web Code

This is particularly important.

Your application might be packaged as an Android app, but your JavaScript is still part of the application bundle.

Never embed API secrets, private credentials, or sensitive server-side logic in your frontend code.

If something needs to remain secret, it belongs on a secure backend.

Don't Assume Every Website Makes a Good App

Capacitor is a useful tool, but simply packaging a website doesn't automatically create a great mobile experience.

Think about what makes the app useful on a phone.

Maybe it's quick access to a tool, offline functionality, notifications, camera integration, or a streamlined mobile interface.

If you plan to publish through Google Play, review the current store policies as well.

An app with minimal functionality or an experience that offers little beyond a basic website may have trouble meeting store quality expectations.

Quick Reference: Capacitor CLI Commands

Here's a handy reference for the commands covered in this guide.

Command What It Does
npm install @capacitor/core Installs the Capacitor runtime
npm install -D @capacitor/cli Installs the CLI
npx cap init Initializes Capacitor
npm install @capacitor/android Installs Android support
npx cap add android Creates the Android project
npm run build Builds your web application
npx cap sync android Syncs web files and native dependencies
npx cap open android Opens Android Studio
npx cap run android Runs the app on Android
npx cap doctor Checks Capacitor setup and dependencies
npx cap build android Builds a signed Android release with the required configuration

The Entire Initial Setup

If you've already installed Node.js and Android Studio, here's a quick recap of the commands.

Run these from your existing web project's root directory:

# Install Capacitor
npm install @capacitor/core
npm install -D @capacitor/cli

# Initialize Capacitor
npx cap init

# Install Android support
npm install @capacitor/android

# Create the Android project
npx cap add android

# Build your existing web app
npm run build

# Sync the web build to Android
npx cap sync android

# Open in Android Studio
npx cap open android

Don't forget to check the webDir setting after initialization.

And once everything is set up, your normal development workflow becomes:

npm run build
npx cap sync android
npx cap run android

That's the part you'll probably use most often.

Final Thoughts

I think one of the best things about modern web development is how much you can do with the tools you already know.

If you've built an application with React, Vue, or plain JavaScript, you don't necessarily need to learn an entirely different programming language just to get it running on Android.

Capacitor gives you a practical way to reuse that work.

You still need to understand a few Android-specific things, especially when it comes to testing, permissions, signing, and publishing.

But the initial setup is surprisingly manageable.

And once you get it working the first time, the process becomes a lot easier.

My advice? Start with an application you already have working in the browser. Add Capacitor, get it running on your phone, and experiment from there.

You might be surprised how quickly your web project starts feeling like a real mobile app.

Happy building!

Additional Resources

If you want to explore more, these are the official resources I'd recommend:

Written for TechRay.dev — making technology easier to understand, one project at a time.

This tutorial follows the Capacitor 8 documentation. If you're using a different major version, check the corresponding documentation because requirements and commands may change.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.