2016-07-06 11:04:26 -07:00
# MetaMask Plugin [![Build Status](https://circleci.com/gh/MetaMask/metamask-plugin.svg?style=shield&circle-token=a1ddcf3cd38e29267f254c9c59d556d513e3a1fd)](https://circleci.com/gh/MetaMask/metamask-plugin)
2015-12-20 16:25:45 -08:00
2016-09-09 20:01:27 -07:00
## Developing Compatible Dapps
If you're a web dapp developer, we've got two types of guides for you:
- If you've never built a Dapp before, we've got a gentle introduction on [Developing Dapps with Truffle and MetaMask ](https://blog.metamask.io/developing-for-metamask-with-truffle/ ).
- If you have a Dapp, and you want to ensure compatibility, [here is our guide on building MetaMask-compatible Dapps ](https://github.com/MetaMask/faq/blob/master/DEVELOPERS.md )
2016-07-15 18:04:52 -07:00
## Building locally
2016-07-28 11:58:37 -07:00
- Install [Node.js ](https://nodejs.org/en/ ) version 6.3.1 or later.
2016-07-15 18:04:52 -07:00
- Install local dependencies with `npm install` .
2016-07-26 15:15:40 -07:00
- Install gulp globally with `npm install -g gulp-cli` .
2016-07-15 18:04:52 -07:00
- Build the project to the `./dist/` folder with `gulp build` .
- Optionally, to rebuild on file changes, run `gulp dev` .
2016-07-26 15:15:40 -07:00
- To package .zip files for distribution, run `gulp zip` , or run the full build & zip with `gulp dist` .
2016-07-15 18:04:52 -07:00
2016-07-26 15:35:08 -07:00
Uncompressed builds can be found in `/dist` , compressed builds can be found in `/builds` once they're built.
2016-11-21 18:16:45 -08:00
## Installing Local Builds on Chrome
To install your locally built extension on Chrome, [follow this guide ](http://stackoverflow.com/a/24577660/272576 ).
The built extension is stored in `./dist/chrome/` .
2016-06-13 16:53:21 -07:00
## Architecture
[![Architecture Diagram ](./docs/architecture.png )][1]
2015-12-20 16:25:45 -08:00
## Development
```bash
npm install
2016-11-21 09:34:31 -08:00
npm start
```
## Build for Publishing
```bash
npm run dist
2015-12-20 16:25:45 -08:00
```
2016-06-30 18:44:37 -07:00
2016-07-21 18:08:35 -07:00
#### In Chrome
2015-12-20 16:31:44 -08:00
Open `Settings` > `Extensions` .
2016-02-08 12:07:29 -08:00
Check "Developer mode".
2015-12-20 16:31:44 -08:00
At the top, click `Load Unpacked Extension` .
2016-02-08 12:07:29 -08:00
2016-07-26 16:04:26 -07:00
Navigate to your `metamask-plugin/dist/chrome` folder.
2016-02-08 12:07:29 -08:00
2015-12-20 16:31:44 -08:00
Click `Select` .
You now have the plugin, and can click 'inspect views: background plugin' to view its dev console.
2016-03-02 12:14:23 -08:00
2016-07-26 16:04:26 -07:00
#### In Firefox
2016-07-25 13:36:30 -07:00
Go to the url `about:debugging` .
Click the button `Load Temporary Add-On` .
2016-07-26 16:04:26 -07:00
Select the file `dist/firefox/manifest.json` .
2016-07-25 13:36:30 -07:00
You can optionally enable debugging, and click `Debug` , for a console window that logs all of Metamask's processes to a single console.
2016-07-25 14:03:53 -07:00
If you have problems debugging, try connecting to the IRC channel `#webextensions` on `irc.mozilla.org` .
2016-07-25 14:50:19 -07:00
For longer questions, use the StackOverfow tag `firefox-addons` .
2016-07-21 18:08:35 -07:00
### Developing on UI Only
You can run `npm run ui` , and your browser should open a live-reloading demo version of the plugin UI.
Some actions will crash the app, so this is only for tuning aesthetics, but it allows live-reloading styles, which is a much faster feedback loop than reloading the full extension.
### Developing on UI with Mocked Background Process
You can run `npm run mock` and your browser should open a live-reloading demo version of the plugin UI, just like the `npm run ui` , except that it tries to actually perform all normal operations.
It does not yet connect to a real blockchain (this could be a good test feature later, connecting to a test blockchain), so only local operations work.
You can reset the mock ui at any time with the `Reset` button at the top of the screen.
### Developing on Dependencies
2016-03-02 12:14:23 -08:00
2016-04-13 15:46:39 -07:00
To enjoy the live-reloading that `gulp dev` offers while working on the `web3-provider-engine` or other dependencies:
2016-03-02 12:14:23 -08:00
2016-03-02 12:48:15 -08:00
1. Clone the dependency locally.
2016-03-02 12:14:23 -08:00
2. `npm install` in its folder.
3. Run `npm link` in its folder.
2016-03-02 12:48:15 -08:00
4. Run `npm link $DEP_NAME` in this project folder.
2016-11-21 09:34:31 -08:00
5. Next time you `npm start` it will watch the dependency for changes as well!
2016-03-22 10:43:56 -07:00
2016-04-13 15:46:39 -07:00
### Running Tests
Requires `mocha` installed. Run `npm install -g mocha` .
2016-04-18 11:41:29 -07:00
Then just run `npm test` .
You can also test with a continuously watching process, via `npm run watch` .
2016-04-13 15:46:39 -07:00
2016-06-21 12:07:13 -07:00
You can run the linter by itself with `gulp lint` .
2016-10-12 20:03:14 -07:00
#### Writing Browser Tests
To write tests that will be run in the browser using QUnit, add your test files to `test/integration/lib` .
2016-04-13 15:46:39 -07:00
### Deploying the UI
2016-03-22 10:43:56 -07:00
2016-07-06 11:04:26 -07:00
You must be authorized already on the MetaMask plugin.
2016-03-22 10:43:56 -07:00
0. Update the version in `app/manifest.json` and the Changelog in `CHANGELOG.md` .
1. Visit [the chrome developer dashboard ](https://chrome.google.com/webstore/developer/dashboard?authuser=2 ).
2016-07-26 16:04:26 -07:00
2. Run `gulp dist` (or `gulp zip` if you've already built)
3. Upload the latest zip file from `builds/metamask-$PLATFORM-$VERSION.zip` as the updated package.
2016-06-13 16:53:21 -07:00
[1]: http://www.nomnoml.com/#view/%5B%3Cactor%3Euser%5D%0A%0A%5Bmetamask-ui%7C%0A%20%20%20%5Btools%7C%0A%20%20%20%20%20react%0A%20%20%20%20%20redux%0A%20%20%20%20%20thunk%0A%20%20%20%20%20ethUtils%0A%20%20%20%20%20jazzicon%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20account-detail%0A%20%20%20%20%20accounts%0A%20%20%20%20%20locked-screen%0A%20%20%20%20%20restore-vault%0A%20%20%20%20%20identicon%0A%20%20%20%20%20config%0A%20%20%20%20%20info%0A%20%20%20%5D%0A%20%20%20%5Breducers%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20metamask%0A%20%20%20%20%20identities%0A%20%20%20%5D%0A%20%20%20%5Bactions%7C%0A%20%20%20%20%20%5BaccountManager%5D%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%5D%3A-%3E%5Bactions%5D%0A%20%20%20%5Bactions%5D%3A-%3E%5Breducers%5D%0A%20%20%20%5Breducers%5D%3A-%3E%5Bcomponents%5D%0A%5D%0A%0A%5Bweb%20dapp%7C%0A%20%20%5Bui%20code%5D%0A%20%20%5Bweb3%5D%0A%20%20%5Bmetamask-inpage%5D%0A%20%20%0A%20%20%5B%3Cactor%3Eui%20developer%5D%0A%20%20%5Bui%20developer%5D-%3E%5Bui%20code%5D%0A%20%20%5Bui%20code%5D%3C-%3E%5Bweb3%5D%0A%20%20%5Bweb3%5D%3C-%3E%5Bmetamask-inpage%5D%0A%5D%0A%0A%5Bmetamask-background%7C%0A%20%20%5Bprovider-engine%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bid%20store%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%3E%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%3C-%3E%5Bid%20store%5D%0A%20%20%5Bconfig%20manager%7C%0A%20%20%20%20%5Brpc%20configuration%5D%0A%20%20%20%20%5Bencrypted%20keys%5D%0A%20%20%20%20%5Bwallet%20nicknames%5D%0A%20%20%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%5Bconfig%20manager%5D%0A%20%20%5Bid%20store%5D%3C-%3E%5Bconfig%20manager%5D%0A%5D%0A%0A%5Buser%5D%3C-%3E%5Bmetamask-ui%5D%0A%0A%5Buser%5D%3C%3A--%3A%3E%5Bweb%20dapp%5D%0A%0A%5Bmetamask-contentscript%7C%0A%20%20%5Bplugin%20restart%20detector%5D%0A%20%20%5Brpc%20passthrough%5D%0A%5D%0A%0A%5Brpc%20%7C%0A%20%20%5Bethereum%20blockchain%20%7C%0A%20%20%20%20%5Bcontracts%5D%0A%20%20%20%20%5Baccounts%5D%0A%20%20%5D%0A%5D%0A%0A%5Bweb%20dapp%5D%3C%3A--%3A%3E%5Bmetamask-contentscript%5D%0A%5Bmetamask-contentscript%5D%3C-%3E%5Bmetamask-background%5D%0A%5Bmetamask-background%5D%3C-%3E%5Bmetamask-ui%5D%0A%5Bmetamask-background%5D%3C-%3E%5Brpc%5D%0A