V2 Capacitor Documentation issues found in 'Creating Capacitor Plugins'

[dchappelle]

Bug Report

Capacitor Version

💊   Capacitor Doctor  💊

Latest Dependencies:

  @capacitor/cli: 3.3.2
  @capacitor/core: 3.3.2
  @capacitor/android: 3.3.2
  @capacitor/electron: 3.3.2
  @capacitor/ios: 3.3.2

Installed Dependencies:

  @capacitor/cli 2.5.0
  @capacitor/ios 2.5.0
  @capacitor/core 2.5.0
  @capacitor/android 2.5.0
  @capacitor/electron not installed

[success] Android looking great! 👌
  Found 1 Capacitor plugin for ios:
    call-svc-plugin (0.0.1)
[success] iOS looking great! 👌```

Platform(s)

All

Current Behavior

There are issues in the current V2 Creating Capacitor Plugins documentation.

1.) If the MyPlugin is created following the directions (even without making any changes), the npm run build will fail with the following errors

../../../../../node_modules/@types/mocha/index.d.ts:2624:13 - error TS2403: Subsequent variable declarations must have the same type.  Variable 'beforeEach' must be of type 'Lifecycle', but here has type 'HookFunction'.

2624 declare var beforeEach: Mocha.HookFunction;
                 ~~~~~~~~~~

  ../../node_modules/@types/jest/index.d.ts:36:13
    36 declare var beforeEach: jest.Lifecycle;
                   ~~~~~~~~~~
    'beforeEach' was also declared here.

../../../../../node_modules/@types/mocha/index.d.ts:2642:13 - error TS2403: Subsequent variable declarations must have the same type.  Variable 'afterEach' must be of type 'Lifecycle', but here has type 'HookFunction'.

2642 declare var afterEach: Mocha.HookFunction;
                 ~~~~~~~~~

  ../../node_modules/@types/jest/index.d.ts:38:13
    38 declare var afterEach: jest.Lifecycle;
                   ~~~~~~~~~
    'afterEach' was also declared here.

../../../../../node_modules/@types/mocha/index.d.ts:2658:13 - error TS2403: Subsequent variable declarations must have the same type.  Variable 'describe' must be of type 'Describe', but here has type 'SuiteFunction'.

2658 declare var describe: Mocha.SuiteFunction;
                 ~~~~~~~~

  ../../node_modules/@types/jest/index.d.ts:39:13
    39 declare var describe: jest.Describe;
                   ~~~~~~~~
    'describe' was also declared here.

../../../../../node_modules/@types/mocha/index.d.ts:2679:13 - error TS2403: Subsequent variable declarations must have the same type.  Variable 'xdescribe' must be of type 'Describe', but here has type 'PendingSuiteFunction'.

2679 declare var xdescribe: Mocha.PendingSuiteFunction;
                 ~~~~~~~~~

  ../../node_modules/@types/jest/index.d.ts:41:13
    41 declare var xdescribe: jest.Describe;
                   ~~~~~~~~~
    'xdescribe' was also declared here.

../../../../../node_modules/@types/mocha/index.d.ts:2693:13 - error TS2403: Subsequent variable declarations must have the same type.  Variable 'it' must be of type 'It', but here has type 'TestFunction'.

2693 declare var it: Mocha.TestFunction;
                 ~~

  ../../node_modules/@types/jest/index.d.ts:42:13
    42 declare var it: jest.It;
                   ~~
    'it' was also declared here.

../../../../../node_modules/@types/mocha/index.d.ts:2707:13 - error TS2403: Subsequent variable declarations must have the same type.  Variable 'test' must be of type 'It', but here has type 'TestFunction'.

2707 declare var test: Mocha.TestFunction;
                 ~~~~

  ../../node_modules/@types/jest/index.d.ts:45:13
    45 declare var test: jest.It;
                   ~~~~
    'test' was also declared here.

../../../../../node_modules/@types/mocha/index.d.ts:2714:13 - error TS2403: Subsequent variable declarations must have the same type.  Variable 'xit' must be of type 'It', but here has type 'PendingTestFunction'.

2714 declare var xit: Mocha.PendingTestFunction;
                 ~~~

  ../../node_modules/@types/jest/index.d.ts:44:13
    44 declare var xit: jest.It;
                   ~~~
    'xit' was also declared here.

Found 7 errors.

To fix this I had to add the entry "skipLibCheck": true to the plugin's tsconfig.json file

2.) Concerning the Local Testing section.

npm install plugin-name tries to install an official version of the plugin and results in 404 errors. Instead I found the v3 documentation for Local Testing (v3) worked i.e., no linking and just doing npm install ../path/to/echo

3.) Concerning the Usage section.

The following code is not valid JS code

// Import custom plugin package for web support too
import 'my-plugin';

Instead I had to use...

import { Plugins } from '@capacitor/core';
const { MyPlugin } = Plugins;
await MyPlugin.echo()

OR...

import { Plugins } from '@capacitor/core';
import { MyPlugin } from 'my-plugin';
await Plugins.MyPlugin.echo()

Expected Behavior

Documented process works without issues :)

Code Reproduction

This is using the code generated from Capacitor V2 - Creating Capacitor Plugins

Other Technical Details

npm --version output: 6.14.15

node --version output: v14.17.6

pod --version output (iOS issues only): 1.9.2

[jcesarmobile]

For 2 I had this issue reported, but will close it in favor of yours since it’s more complete.

but have in mind that we released capacitor 3 back in may, with an improved plugin generator, and we are already planning capacitor 4, so fixing capacitor 2 issues/docs is not a priority at the moment, we encourage you to upgrade to capacitor 3.

[dchappelle]

I would go to capacitor v3 but I saw the following known issue in the Quasar docs

HTTPS devserver (through quasar.conf.js > devServer > https: true) is not yet supported. If you are using Capacitor plugins that depend on it, it’s better to stay with Capacitor v2 for the moment.

We are using https testing locally and it didn't look like this was supported?

[jcesarmobile]

as you can see in your other issue, is not working fine on Capacitor 2 neither

[dchappelle]

touché

[jcesarmobile]

Going to close as won't do as we have launched Capacitor 4 recently and nobody should be using Capacitor 2 anymore nor creating plugins for it, so those docs won't be fixed.

I've sent a PR to quasar to add Capacitor 4 support, but they have not merged it.