From 739c280f6b5f5a1f0ff2120d73ff86aa7da9481e Mon Sep 17 00:00:00 2001 From: Manuel Araoz Date: Mon, 23 Feb 2015 19:30:25 -0300 Subject: [PATCH] document modern browser usage --- docs/browser.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/docs/browser.md b/docs/browser.md index 9db540acd..d34b358c0 100644 --- a/docs/browser.md +++ b/docs/browser.md @@ -1,25 +1,91 @@ --- title: Browser Builds -description: Guide to writing modules and optimizing browser bundles. +description: Guide to using and writing modules and optimizing browser bundles. --- # Browser Builds +Bitcore and most official submodules work in the browser, thanks to [browserify](http://browserify.org/) (some modules make no sense in the browser, like `bitcore-p2p`). + +The easiest and recommended way to use them, is via [Bower](http://bower.io/), a browser package manager, and get the release bundles. +For example, when building an app that uses `bitcore` and `bitcore-ecies`, you do: + +``` +bower install bitcore +bower install +``` + +You can also use a `bower.json` file to store the dependencies of your project: + +```json +{ + "name": "Your app name", + "version": "0.0.1", + "license": "MIT", + "dependencies": { + "bitcore-ecies": "^0.10.0", + "bitcore": "^0.10.4" + } +} +``` +and run `bower install` to install the dependencies. + +After this, you can include the bundled release versions in your HTML file: +```html + + + + + + + + + + + + + + + + +``` + +## Building custom bundles + +If you want to use a specific version of a module, instead of a release version (not recommended), you must run browserify yourself. +You can get a minified browser bundle by running the following on the project root folder. +``` +browserify --require ./index.js:bitcore | uglifyjs > bitcore.min.js +``` +(for bitcore) + +``` +browserify --require ./index.js:bitcore-ecies --external bitcore | uglifyjs > bitcore-ecies.min.js +``` +(for a bitcore module, `bitcore-ecies` in the example) + + +## Development of modules + +*Note:* You probably don't want to use this method, but `bitcore-build`, as explained above. This is left here as documentation on what happens under the hood with `bitcore-build`. + When developing a module that will depend on Bitcore, it's recommended to exclude Bitcore in the distributed browser bundle when using browserify and to use the `--external bitcore` parameter. It will produce a smaller browser bundle, as it will only include the JavaScript that is nessessary, and will depend on the Bitcore browser build which is better for distribution. -## Tutorial +### Building the bundle manually **Step 1**: Require Bitcore Here we require Bitcore and define the namespace (`index.js`): ```javascript - var bitcore = require('bitcore'); var PrivateKey = bitcore.PrivateKey; var PublicKey = bitcore.PublicKey; var Address = bitcore.Address; - ``` See the [main file](https://github.com/bitpay/bitcore/blob/master/index.js) for bitcore for a complete list, as well as the [Bitcore Documentation](index.md).