search

ionic-team / capacitor

Build cross-platform Native Progressive Web Apps for iOS, Android, and the Web ⚡️
https://capacitorjs.com
MIT License
11.31k stars 962 forks source link

RFC: Capacitor 4 Docs #5722

Closed thomasvidas closed 1 year ago

thomasvidas commented 1 year ago

Hello all! 👋

The team is completely refreshing the Capacitor documentation with the upcoming release of Capacitor 4 🎉 . As such, we'd love for you to comment here on issues you've run into that the documentation did not help you with. We are adding things like

We'd love it if you took the time to look through the documentation and give us feedback on the following things

Our NEW Capacitor 4 documentation is available here: https://next.capacitorjs.com/docs

It is a Work In Progress, most notably the search doesn't work at the moment, some of the links in the v2/v3 sections do not redirect properly, and not all of the v4 documentation is done. But we'd love to get your feedback on the above items as we continue to improve our documentation for anyone using Capacitor!

nathantaal commented 1 year ago

I would love to know how to get rid of the 'XyzPlugin' isn't implemented on the web Error when using writing custom native code without browser support and in plain JS & TS

hellokingdom commented 1 year ago

A few things that come to mind from building a few fairly large apps:

  1. Advice for sane defaults/concepts when dealing with forms and the keyboard. Specifically focusing an input and dealing with the various options for overlays and webview resizing.
  2. Advice for full screen applications where the content can scroll behind the status bar (Android) This includes dealing with safe areas and handling statusbar icon colours.
  3. App versioning/build numbers and how to manage within Capacitor and particulary in a CI/CD environment.
  4. Nx integration examples
  5. Kitchen sink splash screen example..i still can't resolve the initial black screen on app open for iOS .
  6. More example apps configured to solve common challenges possibly based on popular native apps?
leo-petrucci commented 1 year ago

Splash

I've mentioned this in ionic-team/capacitor-assets/issues/291, but I have not worked on a single Android Capacitor app with custom splash screen (both static images and 9 patches) where the splash wasn't horribly distorted depending on screen size.

The fix is literally:

    SplashScreen: {
      launchAutoHide: false,
      androidScaleType: 'CENTER_CROP',
      backgroundColor: '#fff',
    },

In the settings, so it may be worth adding a "Android distorted splash screen issue fix" to this page?

In app browser

I've seen a bunch of confused people asking why the Android in-app browser cannot be closed programmatically while the iOS one can. Obviously this is an API issue (I assume) but I think it should probably be mentioned.

However, a clever trick I've implemented to close the in-app browser on Android (or iOS, the solution is cross-platform) is implementing a deep link with a custom schema (myapp://myapp.com) and then redirecting to that URL from within the in-app browser.

I've used this successfully to implement web-auth within my capacitor app, and afaik it's one of the tricks used by Expo with React Native to get web-auth working natively.

Might be worth a mention somewhere on this page?

Full screen apps

2. Advice for full screen applications where the content can scroll behind the status bar (Android) This includes dealing with safe areas and handling statusbar icon colours.

To continue @hellokingdom's second point, the Android overlay mode is completely broken #2840.

There should be a mention about this on this page. And you should probably also link to the plugin that fixes it. https://github.com/capacitor-community/safe-area

(Ideally the fix should be implemented within Capacitor even if it is not a Capacitor bug, so ultimately I'd like you to reconsider the wontfix, but linking the plugin is a good enough solution)

Geolocation

getCurrentPosition

Earlier this year we implemented Geofencing and it was really really difficult. From my testing getCurrentPosition is really imprecise, even with enableHighAccuracy active. I don't know if this is a bug or by design, but it should be mentioned?

startWatch

From my testing, startWatch returned undefined after running once, which caused me a whole heap of problems. I had to manually call getCurrentPosition() before then doing startWatch().

I feel like this should be mentioned somewhere.

Device Registration

For months we were getting minor exceptions about devices being registered twice and we could not figure out what was wrong with our code. Turns out it's something to do about when the events are fired as explained in ionic-team/capacitor#1088.

More clarity around this would be great!

thomasvidas commented 1 year ago

@creativiii RE: in-app browser:

It is indeed an API mismatch between Android and iOS. And your other suggestions are good ones as well 😄

mlynch commented 1 year ago

@hellokingdom

A few things that come to mind from building a few fairly large apps: ...

  1. App versioning/build numbers and how to manage within Capacitor and particulary in a CI/CD environment.

fwiw we've got docs on how to do this with Capacitor + Appflow and can certainly add more docs on this in Capacitor proper https://ionic.io/docs/appflow/cookbook/auto-incrementing-build-numbers

Sampath-Lokuge commented 1 year ago

How do I do live reload?

This is a very outdated concept now hence we have Hot reload features on other most popular cross-platform frameworks like Flutter. So my question here is when will we have a Hot reload feature for Ionic/Angular/Capacitor native apps? This is really disappointing thing to see hence Angular has given that feature for almost 2 years now.

Ref: https://dev.to/iamscottcab/using-hot-module-replacement-in-angular-11-mji

Flutter: https://docs.flutter.dev/development/tools/hot-reload

No progress at all on this issue for almost 4 years now: Investigate HMR: https://github.com/ionic-team/ionic-cli/issues/3769

Please consider adding those most wanted features to Ionic/Angular/Capacitor native app developers. We are super frustrated with our apps right now due to the too much time we have to spend developing our UIs with Ionic. So please consider that soon. Thanks!

Wahsner commented 1 year ago

Edit: a capacitorjs community plugin has been released which allows the opening on files in conjunction with the filesystem.

~~ How to download and open a file and/or export it to the device (on iOS its Files, not Sure what it is on Android). Ive had a look at the Filesystem package but, unless im missing something obvious, I cannot get access to the files externally from the app.

Also encounter 'popups are blocked' message when trying to open a file.

I believe there are Cordova packages but ive yet to find a capacitorjs package which enables the same/similar functionality. ~~

thomasvidas commented 1 year ago

FYI @Sampath-Lokuge, you can use HMR dev servers with Capacitor today. However, our current docs only reference how to do it with the Ionic CLI and not how to do it with your own tooling. https://capacitorjs.com/docs/guides/live-reload. Definitely something we can improve on 😄

Sampath-Lokuge commented 1 year ago

@thomasvidas Yes, please let us know how to do this with Ionic/Angular apps. This is a super important feature of our app development UI workflows. i.e. Hot reload

indraraj26 commented 1 year ago

Capacitor push notification should add payload of body and title when app is in background.

Right now it does trigger notificationActionPerformed but that doesn't have the payload.

Also i can't find any tutorial or docs that cover the extending firebaseMessagingService

Link of Issue: https://github.com/ionic-team/capacitor-plugins/issues/964#issuecomment-1125272425

riderx commented 1 year ago

The doc to create plugin can be improved too. We don't have in the doc here : https://capacitorjs.com/docs/plugins/ios#accessing-call-data all the kinds of type we can get, to have them it's need to go in the code or use Xcode and android auto-completion. When i do plugin for example, i do all in VS Code first to be able to compare the 2 implementation.

Also, here we have explained on how to use config in native : https://capacitorjs.com/docs/plugins/configuration-values But nothing for web implementation, and in the code the only solution seems deprecated

Adding in the doc the way to run capacitor live reload without the ionic CLI can be nice.

Badisi commented 1 year ago

The other day I was trying to have a look at the @capacitor/storage source code but I couldn't find it as it was removed from the main branch of the capacitor-plugins repository. I later find out that @capacitor/storage was renamed @capacitor/preferences in v4.

Whether it is already on the main branch (instead of staying on the v4 branch until it's released) is questionnable but at least now it should be reflected on the README that @capacitor/storage is deprecated and replaced by @capacitor/preferences in v4, because actually the README says that @capacitor/storage could be found in ./storage which is wrong.

EinfachHans commented 1 year ago

Are there docs for plugin developers, what changes should be done to support capacitor v4 with our plugins?

jcesarmobile commented 1 year ago

There are no breaking changes for plugins (maybe if still using some deprecated thing that was removed)

You should update the target sdk to 32 and test that everything keeps working on Android 31/32 devices, but it's not a required change if your plugin's build.gradle has targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 30, as user apps will have the targetSdkVersion variable and if they set it to 32 your plugin will work as if it was set to 32.

Also, you should update the iOS deployment target to 13, but also, not really required because we are going to add a change that forces the deployment target to be at least 13 to avoid problems in plugins that have not been updated.

And also update the capacitor dependencies/peer dependencies in package.json to use 4 or to allow both 3 and 4 to minimize problems with npm7+

leo-petrucci commented 1 year ago

Full screen apps

  1. Advice for full screen applications where the content can scroll behind the status bar (Android) This includes dealing with safe areas and handling statusbar icon colours.

To continue @hellokingdom's second point, the Android overlay mode is completely broken #2840.

There should be a mention about this on this page. And you should probably also link to the plugin that fixes it. https://github.com/capacitor-community/safe-area

(Ideally the fix should be implemented within Capacitor even if it is not a Capacitor bug, so ultimately I'd like you to reconsider the wontfix, but linking the plugin is a good enough solution)

Out of all the suggestions it's a real bummer to see v4 get released and still no mention of this anywhere in the docs.

mcfarljw commented 1 year ago

@jcesarmobile I just updated everything to Capacitor 4.0.1 and noticed that all of my local plugins registered on Android (using registerPlugin(SomeCoolPlugin.class);) return Error: "SomeCoolPlugin" plugin is not implemented on android even though they previously worked on Capacitor 3. This only happens with Android as they work as intended on iOS. I've tried basic debugging steps like cleaning the build and invalidating the cache.

Any thoughts on what might have changed? If not I can open a new issue with more information.

jcesarmobile commented 1 year ago

I don’t appreciate being pinged, please, don’t do it in the future.

I see all the comments, but ignore the people who pings me on purpose.

I just updated today the docs about that, in capacitor 4 you have to call registerPlugin before super.onCreate

https://capacitorjs.com/docs/android/custom-code#register-the-plugin

also added it to the updating to 4.0 guide https://capacitorjs.com/docs/updating/4-0#change-registerplugin-order

mcfarljw commented 1 year ago

I'm sorry mentioning you directly by name has upset you. I pinged you because I thought it would make it more clear who I was responding to as you'd previously mentioned nothing changed with plugins and there was no other meaning behind it other than that. When I was following the migration guide a few hours ago it hadn't been updated yet but now I see the change in the docs.

I can also verify that changing the order solves my issue. Thanks for taking the time to respond and put me back on the right track.

mlynch commented 1 year ago

@creativiii

Out of all the suggestions it's a real bummer to see v4 get released and still no mention of this anywhere in the docs.

The docs and the actual capacitor releases aren't tied together, so your suggestions are still valuable and we can incorporate them over time. My preference would be that we just fix any bugs those docs reference but it's a tradeoff

tafelnl commented 1 year ago

It would be very useful to have the possible errors thrown by Capacitor API methods/Capacitor Plugins documented somewhere. Right now you would have to look in the source code to be able to know what errors can be thrown (and that the method you are calling can throw in the first place.

For example, I bumped into this issue https://github.com/ionic-team/capacitor-plugins/issues/1035 thinking that it was a bug (since iOS and Android used to behave differently, but that's slightly off-topic). But in the end it turned out to be a justified error being thrown. But it is not documented anywhere, and therefore I didn't expect it.

Ideally we would have typed errors. Unfortunately TypeScript is not exception-safe by nature, so it's not really possible. But maybe - just maybe, because I don't really have experience with it yet - it is worth taking a look at neverthrow. Which (sort of) makes errors typesafe.

Anyways, just documenting the possible errors thrown wouldn't hurt anyone :)

giralte-ionic commented 1 year ago

Please submit PRs for documentation improvements for Capacitor v4 to the 4.x branch. Please create new PRs and issues for v5 against main.

jcesarmobile commented 1 year ago

correction, docs are now located in this repository, everything related to the documentation (reporting issues, doing improvements) should be done there

ionitron-bot[bot] commented 1 year ago

Thanks for the issue! This issue is being locked to prevent comments that are not relevant to the original issue. If this is still an issue with the latest version of Capacitor, please create a new issue and ensure the template is fully filled out.