Skip to content

Latest commit

 

History

History
435 lines (329 loc) · 15.3 KB

MODULE.md

File metadata and controls

435 lines (329 loc) · 15.3 KB

IPFS Module

Use the IPFS module as a dependency of your project to spawn in process instances of IPFS in node.js, the browser, electron, etc.

Table of contents

Getting started

Create a running node with:

// Create the IPFS node instance
const node = await IPFS.create()
// Your node is now ready to use \o/

await node.stop()
// node is now 'offline'

The node returned from IPFS.create() supports the IPFS Core API, along with some additional methods documented below.

IPFS.create([options])

const node = await IPFS.create([options])

Creates and returns a ready to use instance of an IPFS node.

Use the options argument to specify advanced configuration. It is an object with any of these properties:

options.repo

Type Default
string or ipfs.Repo instance '~/.jsipfs' in Node.js, 'ipfs' in browsers

The file path at which to store the IPFS node’s data. Alternatively, you can set up a customized storage system by providing an ipfs.Repo instance.

Example:

// Store data outside your user directory
const node = await IPFS.create({ repo: '/var/ipfs/data' })

options.repoAutoMigrate

Type Default
boolean true

js-ipfs comes bundled with a tool that automatically migrates your IPFS repository when a new version is available.

For apps that build on top of js-ipfs and run in the browser environment, be aware that disabling automatic migrations leaves the user with no way to run the migrations because there is no CLI in the browser. In such a case, you should provide a way to trigger migrations manually.

options.init

Type Default
boolean or object true

Perform repo initialization steps when creating the IPFS node.

Note that initializing a repo is different from creating an instance of ipfs.Repo. The IPFS constructor sets many special properties when initializing a repo, so you should usually not try and call repoInstance.init() yourself.

Instead of a boolean, you may provide an object with custom initialization options. All properties are optional:

  • emptyRepo (boolean) Whether to remove built-in assets, like the instructional tour and empty mutable file system, from the repo. (Default: false)
  • bits (number) Number of bits to use in the generated key pair. (Default: 2048)
  • privateKey (string/PeerId) A pre-generated private key to use. Can be either a base64 string or a PeerId instance. NOTE: This overrides bits.
    // Generating a Peer ID:
    const PeerId = require('peer-id')
    // Generates a new Peer ID, complete with public/private keypair
    // See https://github.com/libp2p/js-peer-id
    const peerId = await PeerId.create({ bits: 2048 })
  • pass (string) A passphrase to encrypt keys. You should generally use the top-level pass option instead of the init.pass option (this one will take its value from the top-level option if not set).
  • profiles (Array) Apply profile settings to config.
  • allowNew (boolean, default: true) Set to false to disallow initialization if the repo does not already exist.

options.start

Type Default
boolean true

If false, do not automatically start the IPFS node. Instead, you’ll need to manually call node.start() yourself.

options.pass

Type Default
string null

A passphrase to encrypt/decrypt your keys.

options.silent

Type Default
Boolean false

Prevents all logging output from the IPFS node.

options.relay

Type Default
object { enabled: true, hop: { enabled: false, active: false } }

Configure circuit relay (see the circuit relay tutorial to learn more).

  • enabled (boolean): Enable circuit relay dialer and listener. (Default: true)
  • hop (object)
    • enabled (boolean): Make this node a relay (other nodes can connect through it). (Default: false)
    • active (boolean): Make this an active relay node. Active relay nodes will attempt to dial a destination peer even if that peer is not yet connected to the relay. (Default: false)

options.offline

Type Default
Boolean false

Run ipfs node offline. The node does not connect to the rest of the network but provides a local API.

options.preload

Type Default
object { enabled: true, addresses: [...] }

Configure remote preload nodes. The remote will preload content added on this node, and also attempt to preload objects requested by this node.

  • enabled (boolean): Enable content preloading (Default: true)
  • addresses (array): Multiaddr API addresses of nodes that should preload content. NOTE: nodes specified here should also be added to your node's bootstrap address list at config.Boostrap.

options.EXPERIMENTAL

Type Default
object { ipnsPubsub: false, sharding: false }

Enable and configure experimental features.

  • ipnsPubsub (boolean): Enable pub-sub on IPNS. (Default: false)
  • sharding (boolean): Enable directory sharding. Directories that have many child objects will be represented by multiple DAG nodes instead of just one. It can improve lookup performance when a directory has several thousand files or more. (Default: false)

options.config

Type Default
object config-nodejs.js in Node.js, config-browser.js in browsers

Modify the default IPFS node config. This object will be merged with the default config; it will not replace it. The default config is documented in the js-ipfs config file docs.

options.ipld

Type Default
object ipld-nodejs.js in Node.js, ipld-browser.js in browsers

Modify the default IPLD config. This object will be merged with the default config; it will not replace it. Check IPLD docs for more information on the available options.

Browser config does NOT include by default all the IPLD formats. Only ipld-dag-pb, ipld-dag-cbor and ipld-raw are included.

To add support for other formats we provide two options, one sync and another async.

Examples for the sync option:

ESM Environments
import ipldGit from 'ipld-git'
import ipldBitcoin from 'ipld-bitcoin'

const node = await IPFS.create({
  ipld: {
    formats: [ipldGit, ipldBitcoin]
  }
})
Commonjs Environments
const node = await IPFS.create({
  ipld: {
    formats: [require('ipld-git'), require('ipld-bitcoin')]
  }
})
Using script tags
<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
<script src="https://unpkg.com/ipld-git/dist/index.min.js"></script>
<script src="https://unpkg.com/ipld-bitcoin/dist/index.min.js"></script>
<script>
async function main () {
  const node = await self.IPFS.create({
    ipld: {
      formats: [self.IpldGit, self.IpldBitcoin]
    }
  })
}
main()
</script>

Examples for the async option:

ESM Environments
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 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
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
<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
<script>
const load = (name, url) => new Promise((resolve, reject) => {
  const script = document.createElement('script')
  script.src = url
  script.onload = () => resolve(self[name])
  script.onerror = () => reject(new Error('Failed to load ' + url))
  document.body.appendChild(script)
})

const node = await self.IPFS.create({
  ipld: {
    async loadFormat (codec) {
      switch (codec) {
        case multicodec.GIT_RAW:
          return load('IpldGit', 'https://unpkg.com/ipld-git/dist/index.min.js')
        case multicodec.BITCOIN_BLOCK:
          return load('IpldBitcoin', 'https://unpkg.com/ipld-bitcoin/dist/index.min.js')
        default:
          throw new Error('Unable to load format ' + multicodec.print[codec])
      }
    }
  }
})
</script>

options.libp2p

Type Default
object libp2p-nodejs.js in Node.js, libp2p-browser.js in browsers
function libp2p bundle

The libp2p option allows you to build your libp2p node by configuration, or via a bundle function. If you are looking to just modify the below options, using the object format is the quickest way to get the default features of libp2p. If you need to create a more customized libp2p node, such as with custom transports or peer/content routers that need some of the ipfs data on startup, a custom bundle is a great way to achieve this.

You can see the bundle in action in the custom libp2p example.

Please see libp2p/docs/CONFIGURATION.md for the list of options libp2p supports.

Instance methods

node.start()

Start listening for connections with other IPFS nodes on the network. In most cases, you do not need to call this method — IPFS.create() will automatically do it for you.

This method is asynchronous and returns a promise.

const node = await IPFS.create({ start: false })
console.log('Node is ready to use but not started!')

try {
  await node.start()
  console.log('Node started!')
} catch (error) {
  console.error('Node failed to start!', error)
}

Static types and utils

Aside from the default export, ipfs exports various types and utilities that are included in the bundle:

These can be accessed like this, for example:

const { CID } = require('ipfs')
// ...or from an es-module:
import { CID } from 'ipfs'
Glob source

A utility to allow files on the file system to be easily added to IPFS.

globSource(path, [options])
  • path: A path to a single file or directory to glob from
  • options: Optional options
  • options.recursive: If path is a directory, use option { recursive: true } to add the directory and all its sub-directories.
  • options.ignore: To exclude file globs from the directory, use option { ignore: ['ignore/this/folder/**', 'and/this/file'] }.
  • options.hidden: Hidden/dot files (files or folders starting with a ., for example, .git/) are not included by default. To add them, use the option { hidden: true }.

Returns an async iterable that yields { path, content } objects suitable for passing to ipfs.add.

Example
const IPFS = require('ipfs')
const { globSource } = IPFS
const ipfs = await IPFS.create()
for await (const file of ipfs.add(globSource('./docs', { recursive: true }))) {
  console.log(file)
}
/*
{
  path: 'docs/assets/anchor.js',
  cid: CID('QmVHxRocoWgUChLEvfEyDuuD6qJ4PhdDL2dTLcpUy3dSC2'),
  size: 15347
}
{
  path: 'docs/assets/bass-addons.css',
  cid: CID('QmPiLWKd6yseMWDTgHegb8T7wVS7zWGYgyvfj7dGNt2viQ'),
  size: 232
}
...
*/
URL source

A utility to allow content from the internet to be easily added to IPFS.

urlSource(url)
  • url: A string URL or URL instance to send HTTP GET request to

Returns an async iterable that yields { path, content } objects suitable for passing to ipfs.add.

Example
const IPFS = require('ipfs')
const { urlSource } = IPFS
const ipfs = await IPFS.create()
for await (const file of ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))) {
  console.log(file)
}
/*
{
  path: 'ipfs-logo.svg',
  cid: CID('QmTqZhR6f7jzdhLgPArDPnsbZpvvgxzCZycXK7ywkLxSyU'),
  size: 3243
}
*/