A CLI for developing MetaMask plugins.
Always use node@10.16.3
, the version currently used to develop MetaMask.
We recommend NVM for managing Node versions.
To install and access the examples (recommended):
git clone git@github.com:MetaMask/mm-plugin.git
cd mm-plugin
npm link
You can also simply install globally: npm install -g mm-plugin
mkdir myPlugin
cd myPlugin
mm-plugin init
MetaMask plugins consist of two things: a JSON manifest and a JavaScript bundle.
For a variety of reasons, we decided to follow NPM conventions. Thus, the manifest file
is simply package.json
, with the following required standard fields:
name
version
description
main
(relative path to source entry point, not the bundle)repository
In addition, we use the following, required custom fields:
web3Wallet
(object
)bundle
(object
)local
(string
; relative path to bundle)url
(string
; absolute URL to bundle)- Set to e.g.
localhost:8081/dist/bundle.js
for local development.
- Set to e.g.
initialPermissions
({ string: object }
; permissions to be requested on plugin installation)- See this interface and examples in this repo for details.
If you exclude any required fields from package.json
, your plugin may not
work properly or install at all.
We recommend building your plugin using this tool.
You can bundle your plugin using your own tools, but it must run in the browser,
run in SES, and its contents must be wrapped in an anonymous function (() => ( ... )
).
This tool has default arguments assuming the following project structure:
.
|- index.js
|- dist/
|-- bundle.js
|- ... (all other project files and folders)
Source files other than index.js
are located through its imports.
The defaults can be overwritten using the mm-plugin.config.json
config file,
see below.
This module uses permissions as defined in rpc-cap
, MetaMask's JSON RPC
capabilities middleware.
See examples in this repo for details.
Always use node@10.16.3
, the version currently used to develop MetaMask.
mm-plugin --help
Usage: mm-plugin <command> [options]
Commands:
mm-plugin init Initialize plugin package [aliases: i]
mm-plugin build Build plugin from source [aliases: b]
mm-plugin eval Attempt to evaluate plugin bundle in SES [aliases: e]
mm-plugin manifest Validate project package.json as a plugin manifest
[aliases: m]
mm-plugin serve Locally serve plugin file(s) for testing [aliases: s]
mm-plugin watch Build plugin on change [aliases: w]
Options (build):
--help, -h Show help [boolean]
--src, -s Source file
[string] [required] [default: "index.js"]
--dist, -d Output directory
[string] [required] [default: "dist/"]
--outfileName, -n Output file name
[string] [default: "bundle.js"]
--port, -p Local server port for testing
[number] [required] [default: 8081]
--eval, -e Attempt to evaluate plugin bundle in SES
[boolean] [default: true]
--manifest, -m Validate project package.json as a plugin
manifest [boolean] [default: true]
--populate Update plugin manifest properties of
package.json [boolean] [default: true]
--verboseErrors, -v, --verbose Display original errors
[boolean] [default: false]
--suppressWarnings, -w Suppress warnings [boolean] [default: false]
Examples:
mm-plugin init Initialize plugin package from
scratch
mm-plugin build -s index.js -d out Build 'plugin.js' as
'./out/bundle.js'
mm-plugin build -s index.js -d out -n Build 'plugin.js' as
plugin.js './out/plugin.js'
mm-plugin serve -r out Serve files in './out' on port 8080
mm-plugin serve -r out -p 9000 Serve files in './out' on port 9000
mm-plugin watch -s index.js -d out Rebuild './out/bundle.js' on changes
to files in 'index.js' parent and
child directories
- Commands
watch --src ... --dist ...
rebuilds on all changes in the parent directory ofsrc
and its children except:node_modules/
test/
andtests/
- The specified
dist
directory - Dotfiles
serve --root ... --port ...
serves theroot
directory onlocalhost:port
- By default,
root
serves the current working directory:.
- By default,
- Arguments
src
,plugin
, andoutfileName
must be file paths when specifieddist
androot
must be directory paths when specified
mm-plugin.config.json
can be placed in the project root directory. It should have string keys matching
command arguments. Values become argument defaults, which can still be overriden on the command line.
Example:
{
"src": "src",
"dist": "plugins",
"port": 9000
}