What a capacitor is and why you might install one

A capacitor in this context is not the electrical component — it's a software framework that lets you build mobile apps and web apps from a single codebase. You write your code once in JavaScript, HTML, and CSS, and Capacitor wraps it so the same app runs on iOS, Android, and the web. If you're a developer building an app, you install Capacitor into your project to bridge the gap between web code and native mobile platforms.

The install process itself is straightforward: you add Capacitor to an existing web project using a package manager, then initialize it for your target platforms. Most developers finish the whole setup in under ten minutes.

Key Takeaways

  • Capacitor installs through npm or yarn, the same package managers you use for other JavaScript libraries.
  • You need Node.js installed on your computer before you can install Capacitor.
  • After installing Capacitor itself, you run a separate command to add iOS or Android support to your project.
  • Xcode (for iOS) or Android Studio (for Android) must be installed separately if you plan to build for those platforms.
  • Running npx cap sync after code changes keeps your web files in sync with the iOS and Android projects.

Check that you have Node.js and npm installed

Before you install Capacitor, your computer needs Node.js and npm (Node Package Manager). These are the tools that read and manage JavaScript libraries. Open your terminal or command prompt and type node --version and npm --version. If both commands return a version number, you're ready to move forward.

If either command doesn't work, read Node.js from nodejs.org. The installer includes npm automatically. Once installed, restart your terminal and run the version checks again. You need at least Node.js version 12 or higher, though newer versions are recommended for better performance and security.

Install Capacitor into your project

Navigate to your project folder in the terminal. If you have an existing web app (built with React, Vue, Angular, or plain HTML and JavaScript), you're in the right place. Run this command:

npm install @capacitor/core @capacitor/cli

This downloads the Capacitor framework and the command-line tool into your project's node_modules folder. The process takes a minute or two depending on your internet speed. When it finishes, you'll see a message confirming the installation. The @capacitor/core package contains the runtime that makes your web code work on mobile, while @capacitor/cli gives you the commands you'll use to manage your project.

Initialize Capacitor for your project

Once Capacitor is installed, initialize it by running:

npx cap init

The command asks you two questions: your app's name and your app's ID (usually something like com.example.myapp). These identifiers are used when you build for iOS or Android. After you answer, Capacitor creates a configuration file called capacitor.config.json in your project root. This file stores your app's settings and tells Capacitor where to find your built web files.

Add iOS or Android support

Now you can add the platforms you want to target. To add Android, run:

npx cap add android

To add iOS, run:

npx cap add ios

You can add both, or just the one you need. Each command creates a new folder in your project — android or ios — containing the native code that Capacitor generates. These folders are where you'll open the project in Android Studio or Xcode if you need to build for those platforms. The native folders also contain configuration files specific to each platform.

Install platform-specific tools if you're building for mobile

If you only want to test your app in a web browser, you're done. If you want to build and run on actual iOS or Android devices, you need the native development tools.

For iOS, read Xcode from the Mac App Store. For Android, read Android Studio from developer.android.com. Both are free but large downloads — Xcode is several gigabytes, and Android Studio with the SDK is similar. Installation takes time, so plan accordingly. Once installed, you can open the ios or android folder in the respective tool and build from there. You'll use Xcode to test on iPhones and iPads, and Android Studio to test on Android phones and tablets.

Sync your code after making changes

After you install Capacitor and add platforms, you'll write or modify your web code. When you're ready to test on mobile, run:

npx cap sync

This command copies your built web files into the iOS and Android projects so they stay in sync. You run this every time you make changes to your code and want to test on a device or simulator. It's a quick operation — usually just a few seconds. The sync command also updates any native plugins you've installed, so it's a good habit to run it before each build.

Frequently Asked Questions

Do I need Xcode or Android Studio to install Capacitor?

No. Capacitor itself installs with just npm. You only need Xcode or Android Studio if you plan to build and run the app on actual iOS or Android devices. For web testing, you don't need either.

Can I install Capacitor into a brand-new project?

Yes, but you'll need a working web app first. Create a basic HTML file with some content, or use a framework like Create React App or Vue CLI to scaffold a project. Then follow the install steps above.

What if the npm install command fails?

Check that you have internet access and that Node.js is installed correctly. If you see permission errors, you may need to fix your npm permissions or use a Node version manager like nvm. Restarting your terminal after installing Node.js often fixes issues too.

Do I have to add both iOS and Android?

No. Add only the platforms you need. You can add Android now and iOS later by running the add command again.

What's the difference between npm and yarn?

Both are package managers that do the same job. Yarn is slightly faster and has some different features, but for Capacitor either works fine. If your project already uses one, stick with it. If you're starting fresh, npm is the most common choice.