Skip to main content

Overview

Setup​

npx gulp new-pkg

To create a new plugin

Minimum File Structure​

The following folder is automatically created by the command above.

packages/mask/src/plugins/{your-plugin-name}
├── README.md           # see `README driven development`
├── index.ts            # Plugin registration
├── base.ts             # Basic definition of a plugin
├── constants.ts        # Constant definition, e.g: api end-point, etc
├── types.ts            # Provide common typing definitions
├── SNSAdaptor/index.ts # (Optional) Provide SNSAdaptor part of the plugin
├── Dashboard/index.ts  # (Optional) Provide Dashboard part of the plugin
├── Worker/index.ts     # (Optional) Provide Worker part of the plugin
└── utils.ts            # Provide common utils function

About README.md file​

see README driven development

The file need to provide this information:

  • Feature-set as TODOs
  • Reference resource list
  • Known issues / Caveats

Plugin APIs​

  • Plugin definition: packages/plugin-infra/src/types.ts
  • Database: context.getDatabaseStorage() (2nd parameter of the init method of your Worker definition). See example in packages/plugins/example/src/Worker/index.ts.
  • Message emitter: createPluginMessage exported from @masknet/plugin-infra
  • RPC: createPluginRPC exported from @masknet/plugin-infra
  • Metadata reader: createTypedMessageMetadataReader in @masknet/shared-base
  • React renderer with metadata reader: createRenderWithMetadata in @masknet/shared-base

Architecture​

The extension we talk about here is a bunch of code compiled and running in the Mask Network extension. This plugin system is for decoupling purposes. It doesn't allow load the new plugin dynamically without compiling the whole extension from the source code. If you're looking for a dynamic plugin system, you're probably looking for External plugin that still in the very early stage.

Plugin state​

  • Registered, the default state. The plugin has been registered in the plug-in registry.
  • Loaded, the deferred definition of the plugin has been loaded.
  • Activated, the plugin is activated in the current context.

State transition:

  • Registered => Loaded
  • Loaded => Activated (enable/start the plugin)
  • Activated => Loaded (disable the plugin)

Metadata guide​

Metadata is JSON compatible data that's can be inserted into a post.

The most common use case of the metadata is the following.

Add a new entry in the composition dialogue, therefore, the user can interact with your plugin. When it's finished, you can insert your metadata into the post and it will be contained in the encrypted payload. When you see metadata in the post payload, you should render some UI to reveal the information in the metadata and allow the user to interact with it.

Notice please treat the metadata you received as non trustable data, make sure you have validated the formats and the data range. We provided a utility to read the data from the post and validate it with JSON schema.