January 21, 2021
  • Engineering
  • Tutorials
  • Capacitor
  • react

Understanding Changes to Capacitor 3 core plugins

Mike Hartington

Director of Developer Relation...

When we announced Capacitor 3.0 beta last week, one of the biggest changes we mentioned was around the core Capacitor APIs. All officially supported plugins are now installed and versioned separately from Capacitor core. While this may seem like a pretty drastic change, the migration is fairly straight forward. With these changes, developers actually have more control over what APIs are included in an app. Meaning not only is there a better developer experience, but a faster startup time for your app. Let’s take a look at how we can update an app to the latest beta and use the new APIs in our App.

Updating our App

Let’s start off by updating our app to use the latest beta release or Capacitor Core and the CLI.

npm install @capacitor/core@next
npm install @capacitor/cli@next

Next, we’ll install the beta releases of Capacitor iOS and Android

npm install @capacitor/ios@next
npm install @capacitor/android@next

If you’ve customized your native projects at all, you’ll want to manually update them to account for changes to Capacitor. A detailed guide can be found here in our docs for iOS and Android. Since I don’t have any changes in my project, I’m just going to rm the iOS and Android platforms (’cause YOLO).

rm -rf ios android
npx cap add ios
npx cap add android

Now with this bit out of the way, we can actually get to our main topic…Plugins.

Adding the new plugins

In this sample app, we make use of the File System API to save notes to our device. Let’s install the new npm package for File System and start to update our code.

npm install @capacitor/filesystem

In ./src/pages/Editor.tsx, we have an import statement, pulling a few things from @capacitor/core.

import {
  Plugins,
  FilesystemDirectory,
  FilesystemEncoding,
} from '@capacitor/core';

For this, we can update our import path to point to the new package, @capacitor/filesystem. Once this is updated, the types for FilesystemDirectory and FilesystemEncoding can stay, but we need to remove the Plugins object and replace that with the new FileSystem object. Now instead of destructuring FileSystem from the Plugins object, we can get direct access to from the package itself. Now our import should look like so:

import {
  Filesystem,
  FilesystemDirectory,
  FilesystemEncoding,
} from '@capacitor/filesystem';

Now in our implementations, we can remove and const {...} = Plugins and just call the API directly.

  const saveFile = async () => {
    const file = params.name ? params.name : `note-${Date.now()}.txt`;
    await Filesystem.writeFile({
      path: `notes/${file}`,
      data: state,
      directory: FilesystemDirectory.Documents,
      encoding: FilesystemEncoding.UTF8,
    });
    history.goBack();
  };

Parting thoughts

If you’re using any of the core Capacitor APIs in your app, the process to update for beta is basically the same as above. We’re currently working with the folks in the Capacitor Community Github Org to help update third-party plugins to the new API, so be on the lookout for pre-releases there. We’ll be going over more Capacitor beta content in the coming weeks, so keep out for the next post. Cheers!


Mike Hartington

Director of Developer Relation...