Type Safety For Plugins: How are we expected to use TypeScript definitions?

[fkirc]

To use Capacitor plugins, common sample code looks like this:

import { Plugins } from '@capacitor/core';
const { NFC } = Plugins;

await NFC.showSettings();

Unfortunately, this sample code lacks type safety. The TypeScript compiler does not know whether the plugin NFC or the function showSettings exists. This has two problematic outcomes:

• Plugins are less comfortable to use because autocomplete does not work.
• The likelihood of runtime errors increases.

(To illustrate this problem, I chose the plugin https://github.com/adrynov/Capacitor-NFC-Plugin, but this could be another plugin as well.)

Background

The reason why the above code snippet still compiles is a little hack in the Capacitor internals.
Specifically, core/src/core-plugin-definitions.ts contains the following PluginRegistry:

export interface PluginRegistry {
  // A few predefined plugins are declared:
  Storage: StoragePlugin;
  Toast: ToastPlugin;
  WebView: WebViewPlugin;

  // Custom plugins are not declared. Instead, this tells the TypeScript compiler to permit arbitrary property accesses without any further type checking:
  [pluginName: string]: {
    [prop: string]: any;
  };
}

As we can see, only a few predefined plugins are properly typechecked, but not any custom plugins.
Later on, to check whether a plugin is available at runtime, Capacitor checks for the existence of a property in this PluginRegistry:

function isPluginAvailable(name) {
    return PluginRegistry.hasOwnProperty(name);
}

Workaround: Cast Plugin To An Interface

Many plugin authors provide complete TypeScript definitions for their plugin.
Therefore, we should achieve type safety by importing this definition in our Ionic project.
However, it is not entirely obvious how to import and use this definition.
According to the the docs in https://capacitor.ionicframework.com/docs/plugins/, plugin authors should write definitions that are similar to the following snippet:

declare module "@capacitor/core" {
  interface PluginRegistry {
    NFC: NFCPlugin;
  }
}

export interface NFCPlugin {
  showSettings(): Promise<void>;
}

The problem is that the above snippet is not sufficient to achieve type safety with the tutorial snippets. Instead, I succeeded to achieve type safety with the following plugin cast and imports:

import { Plugins } from '@capacitor/core';
import { NFCPlugin } from 'capacitor-nfc/dist/esm/definitions';

const NFC = Plugins.NFC as NFCPlugin;
await NFC.showSettings();

Although this solution achieves the goal of type safety, it is still suboptimal.
Firstly, NFCPlugin is an undocumented interface that could have any other name as well. If users are expected to actually import the interface NFCPlugin, then this should be documented in the README.
Secondly, I am not sure whether this solution works well for all custom plugins.

This leads to my final questions:

• Are there better options to achieve plugin type safety, other than importing and casting some undocumented interfaces?
• Does Ionic plan to change the tutorials and/or the core implementation, such that plugins are typesafe out of the box?

[xzilja]

By default all capacitor core plugins are typed, I get correct auto completion and checks during tsc. If you are referring to custom plugins one approach could be:

import { Plugins } from '@capacitor/core';

/**
 * Types
 */
interface GoogleUser {
  idToken: string;
}

interface GoogleAuthInterface {
  signIn: () => Promise<GoogleUser>;
  signOut: () => Promise<void>;
}

/**
 * Plugin
 */
const { GoogleAuth } = Plugins;

export default GoogleAuth as GoogleAuthInterface;

And just import all your custom plugins from files like plugins/GoogleAuth.ts for example

[fkirc]

Yes, I am only referring to "custom" plugins (plugins that are not included in the Capacitor package itself).
Your approach seems to be very similar to the approach that I presented, but I wonder if there are better ways to gain type safety.

[Timeswitch]

This is related to #1547
Can't get his to work right either, casting around is the only thing that works.

[aaronksaunders]

how are you resolving this issue when using this work around?

Invalid module name in augmentation, module '@capacitor/core' cannot be found.  TS2664

  > 1 | declare module "@capacitor/core" {
      |                ^
    2 |   interface PluginRegistry {
    3 |     TestPlugin2: TestPlugin2Plugin;
    4 |   }

[uncvrd]

@aaronksaunders literally JUST ran in to this, by clicking around in current capacitor plugin repos we're supposed to declare as global? The docs don't do a good job at explaining this or maybe I'm missing something? Can we get some explanation here? Here's a link to firebase-analytics that declares as global: https://github.com/philmerrell/capacitor-firebase-analytics/blob/master/src/definitions.ts

Edit:
Ok take that back, this facebook plugin declares using@capacitor/core so im not quite sure anymore.. https://github.com/rdlabo-team/capacitor-facebook-login/blob/master/src/definitions.ts

Edit 2:
Alright, so...did you delete your web.ts file? I had no need for it (I thought, since I only needed iOS / Android functionality). Apparently, the error we have goes away when I add that file back. No clue why to be honest.

[kheftel]

thanks @fkirc, the "Cast Plugin To An Interface" workaround in the OP helped just now with a custom capacitor plugin i'm working on.

[aggregat-vision]

Thank you very much, fkirc. I have been struggling with this issue and searching for solutions for a long time already.

I would really appreciate if someone from the Capacitor team could shed some light on this. Is the solution provided by fkirc the right one? Is there a better recommended solution? Would be great, if the plugin documentation explained this.

What is the recommended way to consume other interfaces exported by a custom plugin? Using fkirc's solution, this is what I currently do:

import { Plugins } from '@capacitor/core';
import { MyCustomPluginPlugin, MyCustomInterface } from 'my-custom-plugin/dist/esm/definitions';
const MyCustomPlugin= Plugins.MyCustomPlugin as MyCustomPluginPlugin;
const data: MyCustomInterface = ...;

Thank you very much.

[aparajita]

In Capacitor 2.x you have to cast to your interface. It isn't optimal, but it isn't the end of the world.

In Capacitor 3 you will import plugins directly from a package, no casting will be necessary.

[aggregat-vision]

Thank you very much for the quick reply and elaboration.