diff --git a/README.md b/README.md
index 980ab55819..658a8cb668 100644
--- a/README.md
+++ b/README.md
@@ -58,8 +58,8 @@ 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)
+ - [start](#nodestart)
+ - [stop](#nodestop)
- [Core API](#core-api)
- [Files](#files)
- [Graph](#graph)
@@ -210,7 +210,26 @@ You can find some examples and tutorials in the [examples](/examples) folder, th
const node = await IPFS.create([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:
+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])
+```
+
+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
- node.on('ready', async () => {
- console.log('Node is ready to use!')
+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).
- try {
- await node.start()
- console.log('Node started!')
- } catch (error) {
- console.error('Node failed to start!', error)
- }
- })
- ```
+```js
+// Note: you can use the class constructor style for more
+// idiomatic callback/events style code
+const node = new IPFS({ start: false })
-2. If you pass a function as the final argument, 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 but not started!')
- ```js
- 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!')
+Alternatively 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!')
- })
- })
- ```
-
-3. You can listen for the [`start` event](#events).
+```js
+// Note: you can use the class constructor style for more
+// idiomatic callback/events style code
+const node = new IPFS({ start: false })
- ```js
- const node = new IPFS({ start: false })
+node.on('ready', () => {
+ console.log('Node is ready to use but not started!')
+ node.start()
+})
- node.on('ready', () => {
- console.log('Node is ready to use!')
- node.start()
- })
+node.on('error', error => {
+ console.error('Something went terribly wrong!', error)
+})
- node.on('error', error => {
- console.error('Something went terribly wrong!', error)
- })
+node.on('start', () => console.log('Node started!'))
+```
- node.on('start', () => console.log('Node started!'))
- ```
+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!'))
+```
+