From 739c280f6b5f5a1f0ff2120d73ff86aa7da9481e Mon Sep 17 00:00:00 2001 From: Manuel Araoz Date: Mon, 23 Feb 2015 19:30:25 -0300 Subject: [PATCH 1/5] 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 9db540a..d34b358 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). From 2f691e2caeb2f4932e671c2a7b4bebf9325be0ee Mon Sep 17 00:00:00 2001 From: Manuel Araoz Date: Mon, 23 Feb 2015 19:32:01 -0300 Subject: [PATCH 2/5] fix typo --- docs/browser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/browser.md b/docs/browser.md index d34b358..e61cc33 100644 --- a/docs/browser.md +++ b/docs/browser.md @@ -12,7 +12,7 @@ For example, when building an app that uses `bitcore` and `bitcore-ecies`, you d ``` bower install bitcore -bower install +bower install bitcore-ecies ``` You can also use a `bower.json` file to store the dependencies of your project: From 0772cd77f62be41f5da157558242f4f61676f38f Mon Sep 17 00:00:00 2001 From: Manuel Araoz Date: Mon, 23 Feb 2015 19:32:57 -0300 Subject: [PATCH 3/5] add sh types --- docs/browser.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/browser.md b/docs/browser.md index e61cc33..8a984ae 100644 --- a/docs/browser.md +++ b/docs/browser.md @@ -10,7 +10,7 @@ Bitcore and most official submodules work in the browser, thanks to [browserify] 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: -``` +```sh bower install bitcore bower install bitcore-ecies ``` @@ -58,12 +58,12 @@ After this, you can include the bundled release versions in your HTML file: 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. -``` +```sh browserify --require ./index.js:bitcore | uglifyjs > bitcore.min.js ``` (for bitcore) -``` +```sh browserify --require ./index.js:bitcore-ecies --external bitcore | uglifyjs > bitcore-ecies.min.js ``` (for a bitcore module, `bitcore-ecies` in the example) From 0a319b9fde054d51d705e572f5bdc2f085958274 Mon Sep 17 00:00:00 2001 From: Manuel Araoz Date: Tue, 24 Feb 2015 11:26:37 -0300 Subject: [PATCH 4/5] minor fixes --- docs/browser.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/browser.md b/docs/browser.md index 8a984ae..0ac0bba 100644 --- a/docs/browser.md +++ b/docs/browser.md @@ -5,7 +5,7 @@ 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`). +Bitcore and most official submodules work in the browser, thanks to [browserify](http://browserify.org/) (some modules are not fully compatible with web browsers). 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: @@ -75,7 +75,7 @@ browserify --require ./index.js:bitcore-ecies --external bitcore | uglifyjs > bi 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. -### Building the bundle manually +### Building the Bundle Manually **Step 1**: Require Bitcore From a4b72325cd2bf4d1c413fcf342815806c857b488 Mon Sep 17 00:00:00 2001 From: Manuel Araoz Date: Tue, 24 Feb 2015 12:59:36 -0300 Subject: [PATCH 5/5] capitalize --- docs/browser.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/browser.md b/docs/browser.md index 0ac0bba..775c01b 100644 --- a/docs/browser.md +++ b/docs/browser.md @@ -54,7 +54,7 @@ After this, you can include the bundled release versions in your HTML file: ``` -## Building custom bundles +## 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. @@ -69,7 +69,7 @@ browserify --require ./index.js:bitcore-ecies --external bitcore | uglifyjs > bi (for a bitcore module, `bitcore-ecies` in the example) -## Development of modules +## 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`.