ionic-team / capacitor

Build cross-platform Native Progressive Web Apps for iOS, Android, and the Web ⚡️

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

---

Capacitor lets you run web apps natively on iOS, Android, Web, and more with a single codebase and cross-platform APIs.

Capacitor provides 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:

npm install @capacitor/android
npx cap add android
npm install @capacitor/ios
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 💙😊

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. 💖

capacitor's Issues

Move demo app to Ionic 4

Windows 10 support

Is there any future plans to support windows 10? There are now almost 1 billion windows 10 devices out there and more being added all the time.

Icons on the bottom-right corner of the website are almost invisible

Link: https://ionic-team.github.io/capacitor/
Screenshot:

iOS Checklist

Investigate random "null" script request on Android

For some reason a null script is being requested/added in the example. Unclear if it's related to capacitor or to the Ionic demo inside of it

Add network request handling from cordova-plugin-ionic-webview

https://github.com/ionic-team/cordova-plugin-ionic-webview/blob/608d64191405b233c01a939f5755f8b1fdd97f8c/src/ios/CDVWKWebViewEngine.m#L609

Review call callback lifecycle

In particular, we aren't properly cleaning up a callback in this case:

Plugin method uses a callback. Callback is retained by bridge (for example, watchPosition in Geo plugin). Callback is then removed when (ex: clearWatch) clear is called. Callback is not cleared from the client in this case

feat: Support Advertising Identifier in Device

But only if they've enabled ad framework, such that it won't trigger a deny from Apple

Clear stored callbacks on navigation

If we reload the app we should clear out all stored/remembered callbacks and saved calls

Error trying to run example app on Android

I'm trying to run the example app on android and when the app launches, it crashes immediately. Here's the relevant stack trace from logcat. Device I'm using is a Samsung Galaxy S8+ running Android 8.0. I'm compiling on Windows 10 in android Studio 3.0.

01-23 20:25:26.068 24749-24749/com.getcapacitor.myapp E/Capacitor: Unable to export Capacitor JS. App will not function!
com.getcapacitor.JSExportException: Unable to load native-bridge.js. Capacitor will not function!
at com.getcapacitor.JSExport.getCoreJS(JSExport.java:30)
at com.getcapacitor.Bridge.getJSInjector(Bridge.java:396)
at com.getcapacitor.Bridge.(Bridge.java:125)
at com.getcapacitor.BridgeActivity.load(BridgeActivity.java:45)
at com.getcapacitor.BridgeActivity.onCreate(BridgeActivity.java:35)
at com.getcapacitor.myapp.MainActivity.onCreate(MainActivity.java:11)
at android.app.Activity.performCreate(Activity.java:7174)
at android.app.Instrumentation.callActivityOnCreate(Instrumentation.java:1220)
at android.app.ActivityThread.performLaunchActivity(ActivityThread.java:2908)
at android.app.ActivityThread.handleLaunchActivity(ActivityThread.java:3030)
at android.app.ActivityThread.-wrap11(Unknown Source:0)
at android.app.ActivityThread$H.handleMessage(ActivityThread.java:1696)
at android.os.Handler.dispatchMessage(Handler.java:105)
at android.os.Looper.loop(Looper.java:164)
at android.app.ActivityThread.main(ActivityThread.java:6938)
at java.lang.reflect.Method.invoke(Native Method)
at com.android.internal.os.Zygote$MethodAndArgsCaller.run(Zygote.java:327)
at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:1374)
Caused by: java.io.FileNotFoundException: public/native-bridge.js
at android.content.res.AssetManager.openAsset(Native Method)
at android.content.res.AssetManager.open(AssetManager.java:388)
at android.content.res.AssetManager.open(AssetManager.java:362)
at com.getcapacitor.JSExport.getCoreJS(JSExport.java:20)
at com.getcapacitor.Bridge.getJSInjector(Bridge.java:396) 
at com.getcapacitor.Bridge.(Bridge.java:125) 
at com.getcapacitor.BridgeActivity.load(BridgeActivity.java:45) 
at com.getcapacitor.BridgeActivity.onCreate(BridgeActivity.java:35) 
at com.getcapacitor.myapp.MainActivity.onCreate(MainActivity.java:11) 
at android.app.Activity.performCreate(Activity.java:7174) 
at android.app.Instrumentation.callActivityOnCreate(Instrumentation.java:1220) 
at android.app.ActivityThread.performLaunchActivity(ActivityThread.java:2908) 
at android.app.ActivityThread.handleLaunchActivity(ActivityThread.java:3030) 
at android.app.ActivityThread.-wrap11(Unknown Source:0) 
at android.app.ActivityThread$H.handleMessage(ActivityThread.java:1696) 
at android.os.Handler.dispatchMessage(Handler.java:105) 
at android.os.Looper.loop(Looper.java:164) 
at android.app.ActivityThread.main(ActivityThread.java:6938) 
at java.lang.reflect.Method.invoke(Native Method) 
at com.android.internal.os.Zygote$MethodAndArgsCaller.run(Zygote.java:327) 
at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:1374) 
01-23 20:25:26.113 24749-24846/com.getcapacitor.myapp A/chromium: [FATAL:jni_android.cc(243)] Please include Java exception stack in crash report

Reduce debugging logging for GCD server

Use custom hostname for webserver on iOS

We now own capacitorapp.net for using in local capacitor apps

Re-insert required JS on webview reload (iOS)

Page navigations/etc. will require us to re-add our special JS magic

Look into using fragments for dialogs

Use random, unique port for server on start

Otherwise two apps listening on the same port will clash (iOS only right now)

iOS Auto-JS Generation

Support empty options catchall object

Plugin native event system

One difference between Capacitor and Cordova is that Cordova copies your source files directly next to your app source files. This makes it possible for plugins to do things, like, extend AppDelegate. We don't allow that as plugins are provided through linked frameworks that don't have access to app source.

To work around this, we should think about an abstracted native event handling system that makes it easy for a plugin to handle an AppDelegate method without having to do any extensions or anything.

E2E Testing for iOS and Android runtime

My gut says E2E testing is going to be easier than unit testing plugins and mocking native APIs. Perhaps we need an app that tests each plugin at the JS layer, or doing something at the native layer. Would be awesome to only have to write it once.

Rename AppState to App

Add redux-logger style logging of native calls/responses

Can enable/disable from the dev menu, perhaps

Properly resume android activity

Test this case: trigger Camera.getPhoto, remove permission while camera is open, come back to the app. RIght now it clears the session, but can we reload the state?

Don't encourage wildcard ambient module declarations

https://github.com/ionic-team/capacitor/blob/9f4720049df76023461c204fbaa2494a08672011/example/src/declarations.d.ts

This is for an example project, but as you know, our team doesn't consider this to be a best-practice. Maybe guide users to a better spot, but let them know how to opt out.

// In some cases, a package/library won't have declaration files for TypeScript.
// Depending on your settings, TypeScript may issue errors when importing an untyped library.
// To get around that, write your own .d.ts files, or add a line such as
//
//     declare module "your-package-name-here";
//
// If you want to get rid of these errors entirely, you can use a wildcard path as so:
//
//    declare module "*";
//
// But be careful! This will permit invalid imports, and give no verification for untyped modules.

Geolocation plugin should use listener system

Currently no way to cancel a watch

Implement Android auto-js generation

Another Random Avocado

@mlynch

feat: Dialogs should be programmatically dismissible

Un-emjoify windows

Windows can't handle the love of the emoji in the CLI. We should downgrade accordingly to avoid missing character boxes.

😭😭😭😭😭😭😭😭😭

Android likes avocados but not capacitors

@mlynch, Readme

Disable caching for GCDWebServer

Caching doesn't make sense for a local app and will only cause dev challenges

Services for handling background event?

How can we help apps handle background events even if the app is closed?

Add support for alert/confirm/prompt in webview for Android

Auto JS doc generation

We should auto generate documentation for the iOS and Android platforms and each API we offer (camera, etc.).

We need to figure out how to mix this into a site that has some non-generated content, or decide if we want to have the full docs specified in some source code repo, like our JS library.

Support encodings other than UTF-8 (and binary)

For filesystem API

Cordova Compat for Android

Placeholder issue for Android compatibility for Cordova plugins

Quiet/non-interactive mode for CLI

The CLI should support a quiet, non-interactive mode. Additionally, any prompts should be flaggable from the CLI to enable CI/etc.

Cordova Backwards-Compat Strategy

Placeholder issue for us to figure out our Cordova backwards-compatibility strategy and the implications

Dev-mode error handler

Nice error UI for dev-mode when errors happen

First go checklist

• capacitor update clean requirement for iOS? (needed to clean in Xcode before build would succeed) @jcesarmobile
• Make sure native-bridge.js gets copied with capacitor copy OR with installing the core command
• Can we use relative paths for capacitor update for pod files to node_modules, instead of the absolute path? @jcesarmobile
• Improve the pod deploy script to avoid the nasty github tag. Can we use lerna?
• Cli shouldn't use Capacitor pod from assets
• Note about pod repo update
• Ship android dependency and add update feature to cli

i18n, no hardcoded strings anywhere

do it

i18n support for native strings

Several native calls have hardcoded strings for titles/etc. Enable i18n on this

Windows: Nothing happens on `npm run capacitor open android`

C:\Projects\Capacitor
λ git clone https://github.com/ionic-team/capacitor-starter my-app
Cloning into 'my-app'...
remote: Counting objects: 12, done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 12 (delta 2), reused 12 (delta 2), pack-reused 0
Unpacking objects: 100% (12/12), done.

C:\Projects\Capacitor
λ cd my-app

C:\Projects\Capacitor\my-app (master -> origin) ([email protected])
λ npm install
npm notice created a lockfile as package-lock.json. You should commit this file.
added 155 packages in 11.61s

C:\Projects\Capacitor\my-app (master -> origin) ([email protected])
λ npm run capacitor init

> [email protected] capacitor C:\Projects\Capacitor\my-app
> capacitor "init"



⚡️  Initializing Capacitor project in C:\Projects\Capacitor\my-app ⚡️


? Is this a new app? Answer 'n' if adding Capacitor to an existing project y
√ Creating capacitor.config.json in 3.19ms
√ Downloading and installing seed project in 1.69s
√ Installing dependencies for seed project (npm install) in 3.26s
√ Installing Capacitor dependencies (npm install --save @capacitor/core@latest @capacitor/cli@latest) in 12.77s
√ Adding native android project in: C:\Projects\Capacitor\my-app\android in 85.23ms
√ Adding native platforms in 95.32ms


🎉   Your Capacitor project is ready to go!  🎉

Follow the Getting Started guide for next steps:
https://capacitor.ionicframework.com/docs/getting-started

C:\Projects\Capacitor\my-app (master -> origin) ([email protected])
λ ls
android/  capacitor.config.json  node_modules/  package.json  package-lock.json  public/  README.md

C:\Projects\Capacitor\my-app (master -> origin) ([email protected])
λ npm run capacitor copy android

> [email protected] capacitor C:\Projects\Capacitor\my-app
> capacitor "copy" "android"

√ Copying web assets from public to android\app\src\main\assets\public in 27.10ms

C:\Projects\Capacitor\my-app (master -> origin) ([email protected])
λ npm run capacitor open android

> [email protected] capacitor C:\Projects\Capacitor\my-app
> capacitor "open" "android"

  [info] Opening Android project at C:\Projects\Capacitor\my-app\android

C:\Projects\Capacitor\my-app (master -> origin) ([email protected])
λ

Nothing happens.

Move avc.js to use native-bridge.js from core

Then it's in one place

Random Avocado

@mlynch

Normalize ios and android plugin load lifeyclce

Right now ios calls load first time a plugin has been called. Android instead has just a load that gets called right after the constructor

I'm leaning towards doing load right after constructor, as any slow operations can be deferred through queuing and such

Auto register plugins on Android, remove registerCorePlugins

Cannot read property 'clobbers' of undefined

capacitor update ios
✔ Fetching plugins in 157.53ms
[error] TypeError: Cannot read property 'clobbers' of undefined
    at jsModules.map (/Users/mhartington/GitHub/tmp2/node_modules/@capacitor/cli/dist/ios/update.js:115:22)
    at Array.map (<anonymous>)
    at plugins.map (/Users/mhartington/GitHub/tmp2/node_modules/@capacitor/cli/dist/ios/update.js:113:19)
    at Array.map (<anonymous>)
    at generateCordovaPluginsJSFile (/Users/mhartington/GitHub/tmp2/node_modules/@capacitor/cli/dist/ios/update.js:111:13)
    at copyPluginsJS (/Users/mhartington/GitHub/tmp2/node_modules/@capacitor/cli/dist/ios/update.js:38:47)
    at Object.updateIOS (/Users/mhartington/GitHub/tmp2/node_modules/@capacitor/cli/dist/ios/update.js:16:11)
    at <anonymous>```

Normalize "changed" event names

Should we go with "change" or "changed"? That is the great question

ex:

addListener('networkStatusChanged'...
// vs
addListener('networkStatusChange', ...

Support background geolocation

Facility to easily remove event listener-style methods

Add watch id system for clearing watches

See: Geolocation