Guide · Open source

How to use Capacitor: install, add platforms and build apps

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Capacitor is a runtime and toolkit that lets an existing web app run inside native iOS and Android app shells, with a cross-platform API for calling device features from web code. This guide shows how to add Capacitor to a web app, add the Android and iOS platforms, and decide whether it fits your project. You will need Node.js and npm, and either an existing web app or a new one to wrap.

Capacitorionic-team/capacitor · ★ 17k · MIT Install options & downloads

Quick start

1Confirm prerequisites. Make sure Node.js and npm are installed and that you have a web app or a new project to wrap.
2Install the core packages. Run npm install @capacitor/core @capacitor/cli in your project folder.
3Initialize Capacitor. Run npx cap init to set up Capacitor in your app.
4Add a native platform. Install @capacitor/android or @capacitor/ios, then run npx cap add android or npx cap add ios.
5Install native build tools. Set up Xcode for iOS or Android Studio for Android, since the README does not cover these in detail.
6Write plugins if needed. Use the Plugin API and Swift or Kotlin/Java to add native functionality your app requires.

What you need before you start

The README lists two prerequisites: Node.js and npm, and an existing web app or a new one to wrap. Capacitor is designed to drop into any existing modern web app, so you do not need to rebuild your project.

Node.js and npm installed
An existing web app, or a new one you plan to wrap
Familiarity with npm (the README relies on it for every install step)

Add Capacitor to your existing web app

Run the two commands below from your app's project folder. The first installs the Capacitor core library and the command-line tool. The second initializes Capacitor in your app.

npm install @capacitor/core @capacitor/cli
npx cap init

Add the Android and iOS platforms

Capacitor does not force you to target every platform. Install only the native platforms you need. Each platform is installed as an npm package and then added to the project with the cap command.

The README does not walk through Xcode or Android Studio setup, so you will need to install and configure those native build tools separately.

npm install @capacitor/android
npx cap add android
npm install @capacitor/ios
npx cap add ios

Start a new app with Ionic instead (optional)

For new apps, the README recommends the Ionic Framework with Capacitor. You install the Ionic CLI and start a new app with the Capacitor option.

The Ionic Framework is optional. Without it, you may need to build native-looking UI yourself and configure tooling such as livereload on your own.

npm install -g @ionic/cli
ionic start --capacitor

Plugins: reaching native features

Capacitor provides a cross-platform API for calling native SDKs from web code. When your app needs something the API does not cover, you can write a custom native plugin using its Plugin API.

The README encourages plugin authors to use Swift for iOS and Kotlin or Java for Android. Plugins can live inside a Capacitor app or be packaged as an npm dependency for others to use.

Use Swift for iOS plugins
Use Kotlin or Java for Android plugins
Share a plugin by packaging it as an npm dependency

Progressive Web App support

Capacitor also provides first-class Progressive Web App support. The README says you can write one app and deploy it to the app stores and to the mobile web.

What people use it for

Wrapping an existing JavaScript web app so it can be submitted to the iOS and Android app stores
Running one codebase across iOS, Android, and the mobile web as a Progressive Web App
Migrating an Apache Cordova project to a more modern tooling approach
Calling native SDKs from web code through the cross-platform API

Frequently asked questions

Is Capacitor free to use?

Capacitor is released under the MIT licence, according to the project's listing. The MIT licence is a permissive open-source licence, but check the licence file in the repository for the exact terms.

What do I need to install Capacitor?

The README lists Node.js and npm, plus an existing web app or a new one to wrap. You install the packages with npm and then initialize the project with npx cap init.

Do I need Ionic Framework to use Capacitor?

No. The README says you do not need Ionic Framework. Without it, you may need to implement native UI yourself and configure your own tooling, such as livereload.

How is Capacitor different from Cordova?

The README says the two are similar in spirit and that Capacitor offers backward compatibility with most Cordova plugins. Capacitor takes a more modern approach to tooling and plugin development, and it treats native projects as source artifacts rather than build artifacts.

Can I use Capacitor if I'm a beginner?

The project is a poor fit for beginners with no web development background. Setup requires npm and familiarity with native build tools like Xcode and Android Studio, which the README does not walk through in detail.

Can Capacitor replace SwiftUI or Jetpack Compose?

Not if you want only native interfaces. Capacitor runs web apps inside native shells, so it suits teams that want a shared web codebase. If you need fully native UI, a native toolkit is a better match.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Capacitor suits web developers who already have a modern web app and want it in the app stores, especially teams targeting iOS, Android and the web from one codebase, or teams migrating from Apache Cordova. If you need fully native interfaces with no web view, or you have no web development background, consider a native toolkit or a framework such as React Native or Flutter.

Install options & downloads