# Capacitor: running a web app natively on iOS, Android and the web from one codebase

> Capacitor is an MIT-licensed TypeScript project from the Ionic team that wraps an existing web app in a native iOS or Android shell and exposes native SDKs to JavaScript. It is a good fit for teams with a working web build; it is not a UI toolkit, and it does not remove the need to open Xcode or Android Studio.

**ionic-team/capacitor** — Build cross-platform Native Progressive Web Apps for iOS, Android, and the Web ⚡️

- Repository: https://github.com/ionic-team/capacitor
- Website: https://capacitorjs.com
- Stars: 16,759 · Forks: 1,280
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/ionic-team-capacitor

## What Capacitor is for, and who it is aimed at

Capacitor targets a specific situation: you have a web app that already builds, and you want that same build running as an installed app on iOS and Android without rewriting it in Swift and Kotlin. The README describes it as a cross-platform API and code execution layer that lets web code call Native SDKs, plus first-class Progressive Web App support so one app can go to the app stores and to the mobile web.

The audience follows from that. Teams with an existing modern web app, since the README says Capacitor was designed to drop in to one. Teams that need native capabilities their browser build cannot reach, because the plugin API is the escape hatch. And teams that want the web build to remain a real deployment target rather than a debugging convenience. If you are starting from nothing and want a component library, this is not the project you are looking for. The README points new apps at Ionic Framework instead.

## The mechanism: a native shell, a bridge, and a plugin API

The repository is a Lerna workspace with four members listed in package.json: android, ios, cli and core. That split maps onto the runtime model. The core package is the JavaScript side, the CLI drives project setup and platform management, and the android and ios packages carry the native projects that get copied into your app.

Native projects are treated as source artifacts rather than build artifacts, which the README calls out as one of the differences from Cordova. In practice that means the generated ios/ and android/ directories are yours to edit and commit, and a sync does not silently overwrite them the way a build-artifact model would. That is a real design decision with consequences in both directions: it gives you a place to put native code, and it means you own the upgrade path when the native templates change.

On top of that sits the Plugin API. Plugins can live inside a Capacitor app or be published as an npm dependency for community use, and the README encourages Swift on iOS and Kotlin or Java on Android when writing them. The repository also contains capacitor-cordova-android-plugins/ and capacitor-cordova-ios-plugins/, which is where the Cordova compatibility layer lives.

## Installing Capacitor and adding your first platform

The README gives a two-step initialization for an existing app. Install the core package and the CLI, then run the initializer:

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

After that, each native platform is a package plus an add command. The README shows both platforms side by side:

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

Running npx cap add android is what creates the android project directory in your repository. The README does not document what npx cap init prompts for, so check the interactive output rather than assuming defaults. For a brand new app the README recommends a different entry point, the Ionic CLI, installed globally and used to scaffold:

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

One thing the README is explicit about: Ionic Framework is not required. Without it you may need to implement native UI yourself, and without the Ionic CLI you may need to configure tooling yourself for features such as livereload.

## Where Capacitor stops helping

The honest limitation is in the README itself. Without Ionic Framework, you implement native UI yourself. Capacitor moves your web code into a native container and gives it a bridge to native APIs; it does not give you navigation bars, tab bars, or platform-conformant controls. Teams that read "cross-platform" as "the platform differences are handled" will be surprised.

The second constraint is that the native projects are source. That is a benefit until you need to move to a new major version and your edits conflict with updated templates. The repository carries ios-pods-template/ and ios-spm-template/ alongside android-template/, which tells you the generated structure is templated and can change between releases. Treat local edits to those directories as a maintenance liability you are choosing to carry.

The third is Cordova. The README says Capacitor offers backward compatibility with a vast majority of Cordova plugins, not all of them, and points to the docs for the differences. If your app depends on a long tail of Cordova plugins, the compatibility layer is the first thing to verify, not the last.

## Capacitor compared with Cordova, and when Cordova is the better answer

The README frames the two as similar in spirit and different in execution. It lists three differences: Capacitor takes a more modern approach to tooling and plugin development, treats native projects as source artifacts instead of build artifacts, and is maintained by the Ionic team.

The second point is the one that actually changes day-to-day work. Under a build-artifact model the native directory is regenerated, so native customization is awkward and temporary. Under Capacitor's model the directory is committed, so customization is natural and permanent. If your team has already invested in a Cordova workflow with a stable set of plugins and no appetite for re-verifying that set, staying on Cordova is a defensible choice; the newer tooling is not by itself a reason to migrate. If you are starting fresh or your plugin set is small, the source-artifact model is the one that will not fight you later.

## Maintenance, releases and what the licence means for you

The repository is not archived and the last push was on 2026-09-18. Releases in the period visible here run on two tracks: 8.5.2 on 2026-09-11 and 8.5.1 on 2026-08-31 as stable, with 9.0.0-alpha.7 published on 2026-09-18. The package.json scripts confirm the shape of that process: separate npm dist-tags for nightly, alpha, beta, rc, latest and dev, driven through Lerna with conventional commits and provenance. In practical terms, installing without a tag gets you the stable line, and the alpha line is published under the next tag rather than latest.

Upgrade cost is the thing to budget for. Because ios/ and android/ are source, a major version bump is not just an npm update; you are reconciling your native directories with new templates and new native dependencies. The presence of both a CocoaPods template and a Swift Package Manager template in the repository also means iOS dependency management has more than one supported shape, and which one your project uses affects what an upgrade touches.

The licence is MIT, which permits commercial and closed-source use and requires preserving the copyright and permission notice. Nothing here is legal advice; if your organization has a policy on third-party notices, the LICENSE file at the repository root is the document to hand to whoever reviews that.

## Conclusion

Adopt Capacitor if you already ship a modern web build and want the same codebase in the app stores and on the mobile web, and if you accept that the ios/ and android/ directories are source you keep in version control. Do not adopt it expecting a UI layer: the README states you may need to implement native UI yourself without Ionic Framework. Before committing, verify your toolchain against the requirements for the Capacitor version you install, check whether the Cordova plugins you depend on are covered by the compatibility layer, and confirm your team can build and sign the native projects.

## FAQ

### How do I install Capacitor in an existing web app?

The README gives two commands: npm install @capacitor/core @capacitor/cli followed by npx cap init. Native platforms are then added one at a time, for example npm install @capacitor/android and npx cap add android.

### How do I use Capacitor to add an Android or iOS platform?

Install the platform package and run the matching add command. The README shows npm install @capacitor/android with npx cap add android, and npm install @capacitor/ios with npx cap add ios.

### Do I need Ionic Framework to use Capacitor?

No. The README states you do not need Ionic Framework with Capacitor, though without it you may need to implement Native UI yourself, and without the Ionic CLI you may need to configure tooling yourself for things such as livereload.

### What is the difference between Capacitor and Cordova?

The README says they are similar in spirit and that Capacitor offers backward compatibility with a vast majority of Cordova plugins. It lists three differences: more modern tooling and plugin development, native projects treated as source artifacts rather than build artifacts, and maintenance by the Ionic team.

### What language should I write a Capacitor native plugin in?

The README encourages Swift for plugins on iOS and Kotlin or Java on Android. Plugins can be written inside a Capacitor app or packaged into an npm dependency for community use.

## Sources

- [ionic-team/capacitor on GitHub](https://github.com/ionic-team/capacitor)
- [License: MIT](https://github.com/ionic-team/capacitor/blob/main/LICENSE)
- [Project website](https://capacitorjs.com)
- [README](https://github.com/ionic-team/capacitor/blob/main/README.md)
- [Releases](https://github.com/ionic-team/capacitor/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ionic-team-capacitor