diff --git a/README.md b/README.md
index 5d5eb9bba7..973b7fd0d6 100644
--- a/README.md
+++ b/README.md
@@ -58,8 +58,9 @@ We've come a long way, but this project is still in Alpha, lots of development i
- [API Docs](#api)
- [Constructor](#ipfs-constructor)
- [Events](#events)
- - [start](#nodestartcallback)
- - [stop](#nodestopcallback)
+ - [ready](#nodeready)
+ - [start](#nodestart)
+ - [stop](#nodestop)
- [Core API](#core-api)
- [Files](#files)
- [Graph](#graph)
@@ -102,12 +103,10 @@ To create an IPFS node programmatically:
```js
const IPFS = require('ipfs')
-const node = new IPFS()
+const node = await IPFS.create()
-node.on('ready', () => {
- // Ready to use!
- // See https://github.com/ipfs/js-ipfs#core-api
-})
+// Ready to use!
+// See https://github.com/ipfs/js-ipfs#core-api
```
### Through command line tool
@@ -124,8 +123,7 @@ The CLI is available by using the command `jsipfs` in your terminal. This is ali
Learn how to bundle with browserify and webpack in the [`examples`](https://github.com/ipfs/js-ipfs/tree/master/examples) folder.
-
-You can also load it using a `
```
@@ -161,7 +159,7 @@ node.on('ready', () => {
### IPFS CLI
-The `jsipfs` CLI, available when `js-ipfs` is installed globally, follows(should, it is a WIP) the same interface defined by `go-ipfs`, you can always use the `help` command for help menus.
+The `jsipfs` CLI, available when `js-ipfs` is installed globally, follows (should, it is a WIP) the same interface defined by `go-ipfs`, you can always use the `help` command for help menus.
```sh
# Install js-ipfs globally
@@ -191,20 +189,14 @@ If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check ou
### IPFS Module
-Use the IPFS Module as a dependency of a project to __spawn in process instances of IPFS__. Create an instance by calling `new IPFS()` and waiting for its `ready` event:
+Use the IPFS Module as a dependency of a project to __spawn in process instances of IPFS__. Create an instance by calling `await IPFS.create()`:
```js
// Create the IPFS node instance
-const node = new IPFS()
-
-node.on('ready', () => {
- // Your node is now ready to use \o/
-
- // stopping a node
- node.stop(() => {
- // node is now 'offline'
- })
-})
+const node = await IPFS.create()
+// Your node is now ready to use \o/
+await node.stop()
+// node is now 'offline'
```
### [Tutorials and Examples](/examples)
@@ -215,12 +207,30 @@ You can find some examples and tutorials in the [examples](/examples) folder, th
#### IPFS Constructor
+```js
+const node = await IPFS.create([options])
+```
+
+Creates and returns a ready to use instance of an IPFS node.
+
+Alternative method to construct an IPFS node
+
+The recommended method of creating a new IPFS node is to use the `IPFS.create` method. However, IPFS is a `class`, and can also be constructed using the `new` keyword:
+
```js
const node = new IPFS([options])
```
-Creates and returns an instance of an IPFS node. Use the `options` argument to specify advanced configuration. It is an object with any of these properties:
+At this point, your node has been created but is **not** ready to use. You must either attach a listener for the "ready" event _or_ wait for the `node.ready` promise to resolve:
+```js
+node.on('ready', () => { /* Node is now ready to use */ })
+// OR
+await node.ready
+```
+Commonjs Environments
```js
-const node = new IPFS(
- {
- ipld: {
- formats: [require('ipld-git'), require('ipld-bitcoin')]
- }
+const node = await IPFS.create({
+ ipld: {
+ formats: [require('ipld-git'), require('ipld-bitcoin')]
}
-)
+})
```
Using script tags
```html
-
-
-
+
+
+
```
ESM Environments
```js
-const node = new IPFS(
- {
- ipld: {
- async loadFormat (codec) {
- if (codec === 'git-raw') {
- return import('ipld-git') // This is a dynamic import
- } else {
- throw new Error('unable to load format ' + multicodec.print[codec])
- }
+const node = await IPFS.create({
+ ipld: {
+ async loadFormat (codec) {
+ if (codec === multicodec.GIT_RAW) {
+ return import('ipld-git') // This is a dynamic import
+ } else {
+ throw new Error('unable to load format ' + multicodec.print[codec])
}
}
}
-)
+})
```
> For more information about dynamic imports please check [webpack docs](https://webpack.js.org/guides/code-splitting/#dynamic-imports) or search your bundler documention.
Using dynamic imports will tell your bundler to create a separate file (normally called *chunk*) that will **only** be requested by the browser if it's really needed. This strategy will reduce your bundle size and load times without removing any functionality.
With Webpack IPLD formats can even be grouped together using magic comments `import(/* webpackChunkName: "ipld-formats" */ 'ipld-git')` to produce a single file with all of them.
-
Commonjs Environments
```js
-const node = new IPFS(
- {
- ipld: {
- async loadFormat (codec) {
- if (codec === 'git-raw') {
- return require('ipld-git')
- } else {
- throw new Error('unable to load format ' + multicodec.print[codec])
- }
+const node = await IPFS.create({
+ ipld: {
+ async loadFormat (codec) {
+ if (codec === multicodec.GIT_RAW) {
+ return require('ipld-git')
+ } else {
+ throw new Error('unable to load format ' + multicodec.print[codec])
}
}
}
-)
+})
```
Using Script tags
```js
-
+
```
Starting using callbacks and events
- ```js
- const node = new IPFS({ start: false })
+If you pass a function to this method, it will be called when the node is started (Note: this method will **not** return a promise if you use a callback function).
- node.on('ready', () => {
- console.log('Node is ready to use!')
+```js
+// Note: you can use the class constructor style for more
+// idiomatic callback/events style code
+const node = new IPFS({ start: false })
- node.start(error => {
- if (error) {
- return console.error('Node failed to start!', error)
- }
- console.log('Node started!')
- })
- })
- ```
+node.on('ready', () => {
+ console.log('Node is ready to use but not started!')
-3. You can listen for the [`start` event](#events).
+ node.start(error => {
+ if (error) {
+ return console.error('Node failed to start!', error)
+ }
+ console.log('Node started!')
+ })
+})
+```
- ```js
- const node = new IPFS({ start: false })
+Alternatively you can listen for the [`start` event](#events):
- node.on('ready', () => {
- console.log('Node is ready to use!')
- node.start()
- })
+```js
+// Note: you can use the class constructor style for more
+// idiomatic callback/events style code
+const node = new IPFS({ start: false })
- node.on('error', error => {
- console.error('Something went terribly wrong!', error)
- })
+node.on('ready', () => {
+ console.log('Node is ready to use but not started!')
+ node.start()
+})
- node.on('start', () => console.log('Node started!'))
- ```
+node.on('error', error => {
+ console.error('Something went terribly wrong!', error)
+})
-#### `node.stop([callback])`
+node.on('start', () => console.log('Node started!'))
+```
-Close and stop listening for connections with other IPFS nodes, then release access to the node’s repo.
+Stopping using callbacks and events
-2. If you pass a function as the final argument, it will be called when the node is stopped (Note: this method will **not** return a promise if you use a callback function).
+If you pass a function to this method, it will be called when the node is stopped (Note: this method will **not** return a promise if you use a callback function).
- ```js
- const node = new IPFS()
+```js
+// Note: you can use the class constructor style for more
+// idiomatic callback/events style code
+const node = new IPFS()
- node.on('ready', () => {
- console.log('Node is ready to use!')
+node.on('ready', () => {
+ console.log('Node is ready to use!')
- node.stop(error => {
- if (error) {
- return console.error('Node failed to stop cleanly!', error)
- }
- console.log('Node stopped!')
- })
- })
- ```
+ node.stop(error => {
+ if (error) {
+ return console.error('Node failed to stop cleanly!', error)
+ }
+ console.log('Node stopped!')
+ })
+})
+```
-3. You can listen for the [`stop` event](#events).
+Alternatively you can listen for the [`stop` event](#events).
- ```js
- const node = new IPFS()
+```js
+const node = new IPFS()
- node.on('ready', () => {
- console.log('Node is ready to use!')
- node.stop()
- })
+node.on('ready', () => {
+ console.log('Node is ready to use!')
+ node.stop()
+})
- node.on('error', error => {
- console.error('Something went terribly wrong!', error)
- })
+node.on('error', error => {
+ console.error('Something went terribly wrong!', error)
+})
- node.on('stop', () => console.log('Node stopped!'))
- ```
+node.on('stop', () => console.log('Node stopped!'))
+```
+