docs/improve newcomers experience (#723)

* docs: update basics example

* docs: improve documentation on the readme

* docs: update webpack example to have a ref to browserify-zlib-next

* docs(examples): update browserify example and add more information about zlib shim

* docs(examples): revamp basics example, make it init the repo on tmp

* docs(example): fix webpack example

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

examples/basics/hello.txt

@@ -0,0 +1 @@
+Hello, how are you today? Welcome to the Distributed Web!

examples/basics/index.js

@@ -0,0 +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(os.tmpDir() + '/' + new Date().toString())
+
+const fileToAdd = {
+  path: 'hello.txt',
+  content: fs.createReadStream('./hello.txt')
+}
+
+let fileMultihash
+
+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),
+  /*
+   * Add a file to IPFS - Complete Files API on:
+   * https://github.com/ipfs/interface-ipfs-core/tree/master/API/files
+   */
+  (cb) => {
+    if (node.isOnline()) {
+      console.log('\nNode is now ready and online')
+    }
+
+    node.files.add(fileToAdd, (err, result) => {
+      if (err) { return cb(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)
+    })
+  }
+], (err) => {
+  if (err) {
+    return console.log(err)
+  }
+  console.log('Success!')
+})

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

examples/bundle-browserify/package.json

@@ -4,15 +4,20 @@
   "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",
   "devDependencies": {
     "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": {}
 }

examples/bundle-browserify/index.js → 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

examples/bundle-webpack/.babelrc

@@ -1,3 +1,6 @@
 {
-  "stage": 0
+  "presets": [
+    "stage-0",
+    "react"
+  ]
 }

examples/bundle-webpack/README.md

@@ -17,3 +17,10 @@ You should see the following:
 
 ![](https://ipfs.io/ipfs/QmZndNLRct3co7h1yVB72S4qfwAwbq7DQghCpWpVQ45jSi/1.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 WebPack config 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
+
+## Special note 2
+
+You need to use WebPack@2 or above, version 1 won't work

examples/bundle-webpack/index.html

@@ -3,8 +3,7 @@
     <title>Sample App</title>
   </head>
   <body>
-    <div id='root'>
-    </div>
+    <div id='root'></div>
     <script src="/static/bundle.js"></script>
   </body>
 </html>

examples/bundle-webpack/package.json

@@ -8,13 +8,16 @@
   "license": "MIT",
   "keywords": [],
   "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",
-    "webpack": "^1.9.6",
-    "webpack-dev-server": "^1.8.2"
+    "babel-core": "^6.22.1",
+    "babel-loader": "^6.2.10",
+    "babel-preset-react": "^6.22.0",
+    "json-loader": "^0.5.4",
+    "react": "^15.4.2",
+    "react-hot-loader": "^1.3.1",
+    "webpack": "^2.2.0",
+    "webpack-dev-server": "^1.16.2"
+  },
+  "dependencies": {
+    "browserify-zlib-next": "^1.0.1"
   }
 }

examples/bundle-webpack/server.js

@@ -1,15 +1,18 @@
 'use strict'
-var webpack = require('webpack')
-var WebpackDevServer = require('webpack-dev-server')
-var config = require('./webpack.config')
 
-new WebpackDevServer(webpack(config), {
+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
-}).listen(3000, 'localhost', function (err, result) {
+})
+
+wds.listen(3000, 'localhost', (err, result) => {
   if (err) {
-    console.log(err)
+    throw err
   }
 
   console.log('Listening at localhost:3000')

examples/bundle-webpack/src/App.js → 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 <div style={{textAlign: 'center'}}>
-      <h1>Everything is working!</h1>
-      <p>Your ID is <strong>{this.state.id}</strong></p>
-      <p>Your IPFS version is <strong>{this.state.version}</strong></p>
-      <p>Your IPFS protocol version is <strong>{this.state.protocol_version}</strong></p>
-      <div>
+    return (
+      <div style={{textAlign: 'center'}}>
+        <h1>Everything is working!</h1>
+        <p>Your ID is <strong>{this.state.id}</strong></p>
+        <p>Your IPFS version is <strong>{this.state.version}</strong></p>
+        <p>Your IPFS protocol version is <strong>{this.state.protocol_version}</strong></p>
+        <hr />
         <div>
           Added a file! <br />
           {this.state.added_file_hash}
         </div>
-        <div>
+        <br />
+        <br />
+        <p>
           Contents of this file: <br />
           {this.state.added_file_contents}
-        </div>
+        </p>
       </div>
-    </div>
+    )
   }
 }
 module.exports = App

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(<App />, document.getElementById('root'))

examples/bundle-webpack/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'),
@@ -21,13 +21,24 @@ module.exports = {
   module: {
     loaders: [{
       test: /\.js$/,
-      loaders: ['react-hot', 'babel'],
+      loaders: ['react-hot-loader', 'babel-loader'],
       include: path.join(__dirname, 'src')
     }, { test: /\.json$/, loader: 'json-loader' }]
   },
   node: {
     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'
+    }
   }
+
 }