Deprecation Notice

This package is deprecated in favor of https://ionic.io/portals. "Portals" provides a better dev-experience and is actively supported by Ionic and newer Capacitor-versions.

---

Embedded Capacitor

This project enables an "embedded usage" of https://capacitorjs.com/ within existing native apps. It exists because of the following frustrating situation:

• Capacitor 2.X provides only bad support for "embedded usage", but promised to deliver with Capacitor 3.X [3405]
• Capacitor 3.X deliberately destroyed "embedded usage", but promised to deliver an embedded closed-source-solution [4343, 4370]

For the time being, I consider Capacitor 2.X as more stable for embedded usage. Therefore, this project only works with Capacitor 2.X.

Improvements over Ionic's Capacitor

With only minimal changes, this project provides the following improvements over Ionic's Capacitor 2.X:

• Configure custom URL-paths for Android/iOS: 3405, 3106
• Make iOS CAPBridgeViewController extensible to better support embedded usage: 1972
• Fix Android-crashes related to unneeded plugins: 4379
• Disable splashscreen-plugin by default to speedup launches (you can still enable it).

To convince yourself, here are the differences between this project and Ionic's Capacitor: https://github.com/fkirc/embedded-capacitor/pull/1/files

Installation

Before you install this project, ensure that regular Capacitor 2.X is working with your project (e.g. it should work in "fullscreen-mode"). Once you finished a regular Capacitor 2.X setup, replace your @capacitor/android or @capacitor/ios packages as follows:

npm uninstall @capacitor/android
npm install capacitor-embedded-android

npm uninstall @capacitor/ios
npm install capacitor-embedded-ios

Next, create symlinks from the original package-locations to the new package-locations:

ln -s "$PWD/node_modules/capacitor-embedded-android/" node_modules/@capacitor/android
ln -s "$PWD/node_modules/capacitor-embedded-ios/" node_modules/@capacitor/ios

Those symlinks need to be created every time when node_modules is created. Therefore, I recommend adding a postinstall-script to your package.json:

  "scripts": {
    "postinstall": "ln -s \"$PWD/node_modules/capacitor-embedded-android/\" node_modules/@capacitor/android && ln -s \"$PWD/node_modules/capacitor-embedded-ios/\" node_modules/@capacitor/ios"
  },

Optionally, I recommend the capsafe tool to increase safety and traceability of your Capacitor-apps.

Finally, follow the Android/iOS-specific instructions below.

Embedded Android

For Android, I recommend to subclass BridgeFragment for embedded usage:

import android.os.Bundle
import com.getcapacitor.BridgeFragment

class MyBridgeFragment : BridgeFragment() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        super.setUrlPath("/#embedded_feature_1") // Set an URL-path for your embedded usage
    }
}

Embedded iOS

For iOS, I recommend to subclass CAPBridgeViewController for embedded usage:

public class MyCAPBridgeViewController: CAPBridgeViewController {
    public override func loadView() {
        super.setUrlPath(path: "/#embedded_feature_1") // Set an URL-path for your embedded usage
        super.loadView()
    }
}

---

⚡️ Cross-platform apps with JavaScript and the Web ⚡️

---

Capacitor is a cross-platform API and code execution layer that makes it easy to call Native SDKs from web code and to write custom native plugins that your app may need. Additionally, Capacitor provides first-class Progressive Web App support so you can write one app and deploy it to the app stores and the mobile web.

Capacitor comes with a Plugin API for building native plugins. Plugins can be written inside Capacitor apps or packaged into an npm dependency for community use. Plugin authors are encouraged to use Swift to develop plugins in iOS and Kotlin (or Java) in Android.

Getting Started

Capacitor was designed to drop-in to any existing modern web app. Run the following commands to initialize Capacitor in your app:

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

Next, install any of the desired native platforms:

npx cap add android
npx cap add ios

New App?

For new apps, we recommend trying the Ionic Framework with Capacitor.

To begin, install the Ionic CLI (npm install -g @ionic/cli) and start a new app:

ionic start --capacitor

FAQ

What are the differences between Capacitor and Cordova?

In spirit, Capacitor and Cordova are very similar. Capacitor offers backward compatibility with a vast majority of Cordova plugins.

Capacitor and Cordova differ in that Capacitor:

• takes a more modern approach to tooling and plugin development
• treats native projects as source artifacts as opposed to build artifacts
• is maintained by the Ionic Team itself 💙😊

See the docs for more details.

Do I need to use Ionic Framework with Capacitor?

No, you do not need to use Ionic Framework with Capacitor. Without the Ionic Framework, you may need to implement Native UI yourself. Without the Ionic CLI, you may need to configure tooling yourself to enable features such as livereload. See the docs for more details.

Contributing

See CONTRIBUTING.md.

Contributors

Made possible by the Capacitor community. 💖