From 0aa32b8bda92eb503206174157c5daafa5714b5e Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 25 Jan 2017 10:57:29 +0000 Subject: [PATCH 1/6] docs: update basics example --- examples/basics/hello.txt | 1 + examples/basics/index.js | 85 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 examples/basics/hello.txt create mode 100644 examples/basics/index.js diff --git a/examples/basics/hello.txt b/examples/basics/hello.txt new file mode 100644 index 0000000000..0c6da6cc39 --- /dev/null +++ b/examples/basics/hello.txt @@ -0,0 +1 @@ +Hello, how are you today? Welcome to the Distributed Web! diff --git a/examples/basics/index.js b/examples/basics/index.js new file mode 100644 index 0000000000..330990abe3 --- /dev/null +++ b/examples/basics/index.js @@ -0,0 +1,85 @@ +'use strict' + +const fs = require('fs') +const IPFS = require('../../src/core') // replace this by line below + +// const IPFS = require('ipfs') + +/* + * Create a new IPFS instance, using default repo (fs) on default path (~/.ipfs) + */ +const node = new IPFS() + + +/* + * Display version of js-ipfs + */ +node.version(gotVersion) + +function gotVersion (err, version) { + if (err) { + return console.error(err) + } + + console.log(version) + + /* + * Load the config into memory (generate the Public Key from the Private Key) + */ + node.load((err) => { + if (err) { + return console.log(err) + } + console.log('Repo was loaded\n') + + /* + * Our instance is set, now let's goOnline (turn on bitswap) and do cool + * stuff + */ + + node.goOnline((err) => { + if (err) { + return console.log(err) + } + + // We can test to see if we actually are online if we want to + if (node.isOnline()) { + console.log('\nYep, we are online') + } + + /* + * Add a file to IPFS - Complete Files API on: + * https://github.com/ipfs/interface-ipfs-core/tree/master/API/files + */ + + const file = { + path: 'hello.txt', + content: fs.createReadStream('./hello.txt') + } + + node.files.add(file, (err, result) => { + if (err) { + return console.error(err) + } + + /* + * Awesome we've added a file so let's retrieve and + * display its contents from IPFS + */ + + console.log('\nAdded file:') + console.log(result[0]) + + node.files.cat(result[0].hash, (err, stream) => { + if (err) { + return console.error(err) + } + + console.log('\nFile content:') + stream.pipe(process.stdout) + stream.on('end', process.exit) + }) + }) + }) + }) +} From 6a2d44434a85fb832c0f713c208221df1c48138d Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 25 Jan 2017 10:57:46 +0000 Subject: [PATCH 2/6] docs: improve documentation on the readme --- README.md | 99 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 51 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 0fcdceb40e..ca0077814e 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,8 @@ We've come a long way, but this project is still in Alpha, lots of development is happening, API might change, beware of the Dragons 🐉.. +**Want to get started?** Check our [examples folder](/examples) to learn how to spawn an IPFS node in Node.js and in the Browser. + You can check the development status at: - Original project [Roadmap](/ROADMAP.md). @@ -81,9 +83,9 @@ You can check the development status at: - [Usage](#usage) - [CLI](#cli) - [HTTP-API](#http-api) - - [IPFS Core examples (use IPFS as a module)](#ipfs-core-examples-use-ipfs-as-a-module) + - [IPFS Core (use IPFS as a module in Node.js or in the Browser)](#ipfs-core-examples-use-ipfs-as-a-module) - [Create a IPFS node instance](#create-a-ipfs-node-instance) - - [More to come](#more-to-come) + - [Tutorials and Examples](#tutorials-and-examples) - [API](#api) - [Generic API](#generic-api) - [Block API](#block-api) @@ -92,25 +94,23 @@ You can check the development status at: - [Files API](#files-api) - [Swarm API](#swarm-api) - [libp2p API](#libp2p-api) +- [Packages](#packages) - [Development](#development) - [Clone](#clone) - [Install Dependencies](#install-dependencies) - [Run Tests](#run-tests) - [Lint](#lint) - [Build a dist version](#build-a-dist-version) -- [Packages](#packages) - [Contribute](#contribute) - [Want to hack on IPFS?](#want-to-hack-on-ipfs) - [License](#license) ## Install -### npm - This project is available through [npm](https://www.npmjs.com/). To install: ```bash -$ npm install ipfs --save +> npm install ipfs --save ``` Requires npm@3 and node >= 4, tested on OSX & Linux, expected to work on Windows. @@ -119,10 +119,10 @@ Requires npm@3 and node >= 4, tested on OSX & Linux, expected to work on Windows To include this project programmatically: -```js -var IPFS = require('ipfs') +```JavaScript +const IPFS = require('ipfs') -var node = new IPFS() +const node = new IPFS() ``` ### Through command line tool @@ -139,12 +139,13 @@ The CLI is available by using the command `jsipfs` in your terminal. This is ali Simply require it as you would do for Node.js, but when transpiling+minifying with your bundler, make sure to swap `zlib` with a full replacement for the browser: `zlib: 'browserify-zlib-next'`. We have submited PR's to browserify and WebPack to make this as part of the standard node libraries that are transpiled, you can follow this development in [browserify](https://github.com/substack/node-browserify/issues/1672), [webpack](https://github.com/webpack/node-libs-browser/issues/51). +You can also find examples of how to do this bundling at: `https://github.com/ipfs/js-ipfs/tree/master/examples` ### Use in a browser using a script tag -Loading this module in a browser (using a ` diff --git a/examples/bundle-webpack/package.json b/examples/bundle-webpack/package.json index 6db2626770..91778b64ee 100644 --- a/examples/bundle-webpack/package.json +++ b/examples/bundle-webpack/package.json @@ -3,7 +3,7 @@ "version": "1.0.0", "description": "Bundle js-ipfs with WebPack", "scripts": { - "start": "node server.js" + "start": "node src/server.js" }, "license": "MIT", "keywords": [], @@ -16,5 +16,8 @@ "react-hot-loader": "^1.3.0", "webpack": "^1.9.6", "webpack-dev-server": "^1.8.2" + }, + "dependencies": { + "browserify-zlib-next": "^1.0.1" } } diff --git a/examples/bundle-webpack/server.js b/examples/bundle-webpack/server.js deleted file mode 100644 index dd1d4358b6..0000000000 --- a/examples/bundle-webpack/server.js +++ /dev/null @@ -1,16 +0,0 @@ -'use strict' -var webpack = require('webpack') -var WebpackDevServer = require('webpack-dev-server') -var config = require('./webpack.config') - -new WebpackDevServer(webpack(config), { - publicPath: config.output.publicPath, - hot: true, - historyApiFallback: true -}).listen(3000, 'localhost', function (err, result) { - if (err) { - console.log(err) - } - - console.log('Listening at localhost:3000') -}) diff --git a/examples/bundle-webpack/src/App.js b/examples/bundle-webpack/src/components/app.js similarity index 80% rename from examples/bundle-webpack/src/App.js rename to examples/bundle-webpack/src/components/app.js index eff2611ebb..095156931d 100644 --- a/examples/bundle-webpack/src/App.js +++ b/examples/bundle-webpack/src/components/app.js @@ -1,6 +1,8 @@ 'use strict' + const React = require('react') -const IPFS = require('ipfs') +const IPFS = require('../../src/core') // replace this by line below +// const IPFS = require('ipfs') const stringToUse = 'hello world from webpacked IPFS' @@ -83,22 +85,25 @@ class App extends React.Component { } } render () { - return
-

Everything is working!

-

Your ID is {this.state.id}

-

Your IPFS version is {this.state.version}

-

Your IPFS protocol version is {this.state.protocol_version}

-
+ return ( +
+

Everything is working!

+

Your ID is {this.state.id}

+

Your IPFS version is {this.state.version}

+

Your IPFS protocol version is {this.state.protocol_version}

+
Added a file!
{this.state.added_file_hash}
-
+
+
+

Contents of this file:
{this.state.added_file_contents} -

+

-
+ ) } } module.exports = App diff --git a/examples/bundle-webpack/src/components/index.js b/examples/bundle-webpack/src/components/index.js new file mode 100644 index 0000000000..32fef13ff3 --- /dev/null +++ b/examples/bundle-webpack/src/components/index.js @@ -0,0 +1,7 @@ +'use strict' + +const React = require('react') +const ReactDOM = require('react-dom') +const App = require('./app') + +ReactDOM.render(, document.getElementById('root')) diff --git a/examples/bundle-webpack/src/index.js b/examples/bundle-webpack/src/index.js deleted file mode 100644 index ec74d11ceb..0000000000 --- a/examples/bundle-webpack/src/index.js +++ /dev/null @@ -1,5 +0,0 @@ -'use strict' -const React = require('react') -const App = require('./App') - -React.render(, document.getElementById('root')) diff --git a/examples/bundle-webpack/src/server.js b/examples/bundle-webpack/src/server.js new file mode 100644 index 0000000000..0b4a68fcf6 --- /dev/null +++ b/examples/bundle-webpack/src/server.js @@ -0,0 +1,19 @@ +'use strict' + +const webpack = require('webpack') +const WebpackDevServer = require('webpack-dev-server') +const config = require('./webpack.config') + +const wds = new WebpackDevServer(webpack(config), { + publicPath: config.output.publicPath, + hot: true, + historyApiFallback: true +}) + +wds.listen(3000, 'localhost', (err, result) => { + if (err) { + throw err + } + + console.log('Listening at localhost:3000') +}) diff --git a/examples/bundle-webpack/webpack.config.js b/examples/bundle-webpack/src/webpack.config.js similarity index 66% rename from examples/bundle-webpack/webpack.config.js rename to examples/bundle-webpack/src/webpack.config.js index ca6675c546..edb77cad38 100644 --- a/examples/bundle-webpack/webpack.config.js +++ b/examples/bundle-webpack/src/webpack.config.js @@ -8,7 +8,7 @@ module.exports = { entry: [ 'webpack-dev-server/client?http://localhost:3000', 'webpack/hot/only-dev-server', - './src/index' + './src/components/index' ], output: { path: path.join(__dirname, 'dist'), @@ -29,5 +29,16 @@ module.exports = { fs: 'empty', net: 'empty', tls: 'empty' + }, + /* + * In order to transfer files, this is a very important step in your Webpack + * configuration, see more at: + * https://github.com/ipfs/js-ipfs#use-in-the-browser-with-browserify-webpack-or-any-bundler + */ + resolve: { + alias: { + zlib: 'browserify-zlib-next' + } } + } From 694f91c5cec9b273060c8ce36dfbb98a1a8d4c54 Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 25 Jan 2017 12:05:16 +0000 Subject: [PATCH 4/6] docs(examples): update browserify example and add more information about zlib shim --- examples/README.md | 13 +++ examples/basics/index.js | 2 - examples/bundle-browserify/README.md | 5 ++ examples/bundle-browserify/package.json | 9 +- .../bundle-browserify/{ => public}/index.html | 0 examples/bundle-browserify/{ => src}/index.js | 3 +- examples/bundle-webpack/package.json | 1 - examples/bundle-webpack/src/components/app.js | 2 +- examples/getting-started/hello.txt | 3 - examples/getting-started/index.js | 84 ------------------- 10 files changed, 28 insertions(+), 94 deletions(-) create mode 100644 examples/README.md rename examples/bundle-browserify/{ => public}/index.html (100%) rename examples/bundle-browserify/{ => src}/index.js (93%) delete mode 100644 examples/getting-started/hello.txt delete mode 100644 examples/getting-started/index.js diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000000..78b7c23347 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,13 @@ +# `js-ipfs` Examples and Tutorials + +In this folder, you can find a variety of examples to help you get started in using js-ipfs, in Node.js and in the Browser. Every example as a specific purpose and some of each incorporate a full tutorial that you can follow through, helping you expand your knowledge about IPFS and the Distributed Web in General. + +Let us know if you find any issue or if you want to contribute and add a new tutorial, feel welcome to submit a PR, thank you! + +## Examples + +- [js-ipfs basic, how to spawn a node and add a file to IPFS](/examples) +- [How to bundle js-ipfs with Browserify](/bundle-browserify) +- [How to bundle js-ipfs with WebPack](/bundle-webpack) + +## Tutorials diff --git a/examples/basics/index.js b/examples/basics/index.js index 330990abe3..a8a964604d 100644 --- a/examples/basics/index.js +++ b/examples/basics/index.js @@ -2,7 +2,6 @@ const fs = require('fs') const IPFS = require('../../src/core') // replace this by line below - // const IPFS = require('ipfs') /* @@ -10,7 +9,6 @@ const IPFS = require('../../src/core') // replace this by line below */ const node = new IPFS() - /* * Display version of js-ipfs */ diff --git a/examples/bundle-browserify/README.md b/examples/bundle-browserify/README.md index b4b4be515e..e3da1419d6 100644 --- a/examples/bundle-browserify/README.md +++ b/examples/bundle-browserify/README.md @@ -15,3 +15,8 @@ You should see the following: ![](https://ipfs.io/ipfs/QmNtpcWCEd6LjdPNfBFDaVZdD4jpgT8ZTAwoFJXKhYMJdo/1.png) ![](https://ipfs.io/ipfs/QmNtpcWCEd6LjdPNfBFDaVZdD4jpgT8ZTAwoFJXKhYMJdo/2.png) + +## Special note + +In order to use js-ipfs in the browser, you need to replace the default `zlib` library by `browserify-zlib-next`, a full implementation of the native `zlib` package, full in Node.js. +See the package.json to learn how to do this and avoid this pitfall. More context on: https://github.com/ipfs/js-ipfs#use-in-the-browser-with-browserify-webpack-or-any-bundler diff --git a/examples/bundle-browserify/package.json b/examples/bundle-browserify/package.json index 83c3836dd5..06468e79e8 100644 --- a/examples/bundle-browserify/package.json +++ b/examples/bundle-browserify/package.json @@ -4,7 +4,12 @@ "description": "Bundle js-ipfs with Browserify", "main": "index.js", "scripts": { - "start": "browserify index.js > bundle.js && http-server -a 127.0.0.1 -p 8888" + "bundle": "browserify src/index.js > public/bundle.js", + "serve": "http-server public -a 127.0.0.1 -p 8888", + "start": "npm run bundle && npm run serve" + }, + "browser": { + "zlib": "browserify-zlib-next" }, "keywords": [], "license": "MIT", @@ -12,7 +17,7 @@ "browserify": "^13.1.1", "concat-stream": "^1.5.2", "http-server": "^0.9.0", - "ipfs": "^0.18.0" + "browserify-zlib-next": "^1.0.1" }, "dependencies": {} } diff --git a/examples/bundle-browserify/index.html b/examples/bundle-browserify/public/index.html similarity index 100% rename from examples/bundle-browserify/index.html rename to examples/bundle-browserify/public/index.html diff --git a/examples/bundle-browserify/index.js b/examples/bundle-browserify/src/index.js similarity index 93% rename from examples/bundle-browserify/index.js rename to examples/bundle-browserify/src/index.js index 6ab84ab8d6..f4fa15d2ee 100644 --- a/examples/bundle-browserify/index.js +++ b/examples/bundle-browserify/src/index.js @@ -1,6 +1,7 @@ 'use strict' -var IPFS = require('ipfs') +var IPFS = require('../../../src/core') // replace this by line below +// var IPFS = require('ipfs') // Create the IPFS node instance // for simplicity, we create a new repo everytime the node diff --git a/examples/bundle-webpack/package.json b/examples/bundle-webpack/package.json index 91778b64ee..054a698c3d 100644 --- a/examples/bundle-webpack/package.json +++ b/examples/bundle-webpack/package.json @@ -10,7 +10,6 @@ "devDependencies": { "babel-core": "^5.4.7", "babel-loader": "^5.1.2", - "ipfs": "^0.18.0", "json-loader": "^0.5.3", "react": "^0.13.0", "react-hot-loader": "^1.3.0", diff --git a/examples/bundle-webpack/src/components/app.js b/examples/bundle-webpack/src/components/app.js index 095156931d..33c145b912 100644 --- a/examples/bundle-webpack/src/components/app.js +++ b/examples/bundle-webpack/src/components/app.js @@ -1,7 +1,7 @@ 'use strict' const React = require('react') -const IPFS = require('../../src/core') // replace this by line below +const IPFS = require('../../../../src/core') // replace this by line below // const IPFS = require('ipfs') const stringToUse = 'hello world from webpacked IPFS' diff --git a/examples/getting-started/hello.txt b/examples/getting-started/hello.txt deleted file mode 100644 index 7b0bc39e0c..0000000000 --- a/examples/getting-started/hello.txt +++ /dev/null @@ -1,3 +0,0 @@ -hello, how are you today? This is just some random content. - -e9a7fd36-d785-4c90-95ae-011329425f9a \ No newline at end of file diff --git a/examples/getting-started/index.js b/examples/getting-started/index.js deleted file mode 100644 index 4fb7fdf79a..0000000000 --- a/examples/getting-started/index.js +++ /dev/null @@ -1,84 +0,0 @@ -'use strict' - -const IPFS = require('../../src/core') // replace this by line below -// const IPFS = require('ipfs') - -/* - * Create a new IPFS instance, using default repo (fs) on default path (~/.ipfs) - */ -const node = new IPFS() - -const fs = require('fs') - -/* - * Display version of js-ipfs - */ -node.version(gotVersion) - -function gotVersion (err, version) { - if (err) { - return console.error(err) - } - - console.log(version) - - /* - * Load the config into memory (generate the Public Key from the Private Key) - */ - node.load((err) => { - if (err) { - return console.log(err) - } - console.log('Repo was loaded\n') - - /* - * Our instance is set, now let's goOnline (turn on bitswap) and do cool - * stuff - */ - - node.goOnline((err) => { - if (err) { - return console.log(err) - } - - // We can test to see if we actually are online if we want to - if (node.isOnline()) { - console.log('\nYep, we are online') - } - - /* - * Add a file to IPFS - Complete Files API on: - * https://github.com/ipfs/interface-ipfs-core/tree/master/API/files - */ - - const file = { - path: 'hello.txt', - content: fs.createReadStream('./hello.txt') - } - - node.files.add(file, (err, result) => { - if (err) { - return console.error(err) - } - - /* - * Awesome we've added a file so let's retrieve and - * display its contents from IPFS - */ - - console.log('\n', result, '\n') - - node.files.cat(result[0].hash, (err, stream) => { - if (err) { - return console.error(err) - } - - console.log('file content: \n') - - stream.pipe(process.stdout) - stream.on('end', process.exit) - }) - }) - }) - }) -} From f88ae956d9e6e12bef756d8b9850110a8d223621 Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 25 Jan 2017 12:32:08 +0000 Subject: [PATCH 5/6] docs(examples): revamp basics example, make it init the repo on tmp --- examples/basics/index.js | 124 +++++++++++++++++++-------------------- 1 file changed, 61 insertions(+), 63 deletions(-) diff --git a/examples/basics/index.js b/examples/basics/index.js index a8a964604d..cb127f3e33 100644 --- a/examples/basics/index.js +++ b/examples/basics/index.js @@ -1,83 +1,81 @@ 'use strict' const fs = require('fs') +const os = require('os') +const series = require('async/series') const IPFS = require('../../src/core') // replace this by line below // const IPFS = require('ipfs') /* * Create a new IPFS instance, using default repo (fs) on default path (~/.ipfs) */ -const node = new IPFS() +const node = new IPFS(os.tmpDir() + '/' + new Date().toString()) -/* - * Display version of js-ipfs - */ -node.version(gotVersion) +const fileToAdd = { + path: 'hello.txt', + content: fs.createReadStream('./hello.txt') +} -function gotVersion (err, version) { - if (err) { - return console.error(err) - } +let fileMultihash - console.log(version) +series([ + /* + * Display version of js-ipfs + */ + (cb) => { + node.version((err, version) => { + if (err) { return cb(err) } + console.log('IPFS Version:', version.version) + cb() + }) + }, + /* + * Initialize the repo for this node + */ + (cb) => node.init({ emptyRepo: true, bits: 2048 }, cb), + /* + * Load the repo config into the IPFS node + */ + (cb) => node.load(cb), + /* + * Take the node online (bitswap, network and so on) + */ + (cb) => node.goOnline(cb), /* - * Load the config into memory (generate the Public Key from the Private Key) + * Add a file to IPFS - Complete Files API on: + * https://github.com/ipfs/interface-ipfs-core/tree/master/API/files */ - node.load((err) => { - if (err) { - return console.log(err) + (cb) => { + if (node.isOnline()) { + console.log('\nNode is now ready and online') } - console.log('Repo was loaded\n') - /* - * Our instance is set, now let's goOnline (turn on bitswap) and do cool - * stuff - */ + node.files.add(fileToAdd, (err, result) => { + if (err) { return cb(err) } - node.goOnline((err) => { - if (err) { - return console.log(err) - } - - // We can test to see if we actually are online if we want to - if (node.isOnline()) { - console.log('\nYep, we are online') - } - - /* - * Add a file to IPFS - Complete Files API on: - * https://github.com/ipfs/interface-ipfs-core/tree/master/API/files - */ - - const file = { - path: 'hello.txt', - content: fs.createReadStream('./hello.txt') - } - - node.files.add(file, (err, result) => { - if (err) { - return console.error(err) - } - - /* - * Awesome we've added a file so let's retrieve and - * display its contents from IPFS - */ - - console.log('\nAdded file:') - console.log(result[0]) - - node.files.cat(result[0].hash, (err, stream) => { - if (err) { - return console.error(err) - } + console.log('\nAdded file:') + console.log(result[0]) + fileMultihash = result[0].hash + cb() + }) + }, + /* + * Awesome we've added a file so let's retrieve and + * display its contents from IPFS + */ + (cb) => { + node.files.cat(fileMultihash, (err, stream) => { + if (err) { return cb(err) } - console.log('\nFile content:') - stream.pipe(process.stdout) - stream.on('end', process.exit) - }) - }) + console.log('\nFile content:') + stream.pipe(process.stdout) + stream.on('end', process.exit) }) - }) -} + } +], (err) => { + if (err) { + return console.log(err) + } + console.log('Success!') +}) From b7ce4a70478219c318d2923338f55115ed543343 Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 25 Jan 2017 12:35:34 +0000 Subject: [PATCH 6/6] docs(example): fix webpack example --- README.md | 2 ++ examples/bundle-webpack/.babelrc | 5 ++++- examples/bundle-webpack/README.md | 4 ++++ examples/bundle-webpack/package.json | 17 +++++++++-------- examples/bundle-webpack/{src => }/server.js | 0 .../bundle-webpack/{src => }/webpack.config.js | 2 +- 6 files changed, 20 insertions(+), 10 deletions(-) rename examples/bundle-webpack/{src => }/server.js (100%) rename examples/bundle-webpack/{src => }/webpack.config.js (94%) diff --git a/README.md b/README.md index ca0077814e..bd916c09da 100644 --- a/README.md +++ b/README.md @@ -141,6 +141,8 @@ Simply require it as you would do for Node.js, but when transpiling+minifying wi You can also find examples of how to do this bundling at: `https://github.com/ipfs/js-ipfs/tree/master/examples` +Special note, if you are using webpack, make sure to use version 2 or above, otherwise it won't work. + ### Use in a browser using a script tag Loading this module in a browser (using a `