ipfs-provider

Connect to IPFS via an available provider.

This module tries to connect to IPFS via multiple providers, in order:

• webext looks for an instance in the background page of a WebExtension (used only in browser extensions, not regular pages).
• window.ipfs proxy in the current page (provided by the IPFS Companion browser extension).
• js-ipfs-http-client with either a user provided apiAddress, the current origin, or the default address (/ip4/127.0.0.1/tcp/5001).
• js-ipfs spawns an in process instance of IPFS (disabled by default: see Enable js-ipfs for more info).

This is a port of the ipfs-redux-bundle.

Install

> npm install ipfs-provider

Usage

import getIpfs from 'ipfs-provider'

const { ipfs, provider } = await getIpfs({
  // These are the defaults:
  tryWebExt: true,    // set false to bypass WebExtension verification
  tryWindow: true,    // set false to bypass window.ipfs verification
  permissions: {}     // set the window.ipfs options you want if tryWindow is true
  tryApi: true,       // set false to bypass js-ipfs-http-client verification
  apiAddress: null    // set this to use an api in that address if tryApi is true
  tryJsIpfs: false,   // set true to attempt js-ipfs initialisation
  getJsIpfs: null,    // must be set to a js-ipfs instance if tryJsIpfs is true
  jsIpfsOpts: {}      // set the js-ipfs options you want if tryJsIpfs is true
})

• ipfs is the running IPFS instance.
• provider is a string representing the chosen provider, either: WEBEXT, WINDOW_IPFS, IPFS_HTTP_API or JS_IPFS.

Enable js-ipfs

To enable js-ipfs, pass the following options:

const { ipfs, provider } = await getIpfs({
  tryJsIpfs: true,
  getJsIpfs: () => import('ipfs'),
  jsIpfsOpts: { /* advanced config */ }
})

• tryJsIpfs should be set to true.
• getJsIpfs should be a function that returns a promise that resolves with a JsIpfs constructor. This works well with dynamic import(), so you can lazily load js-ipfs when it is needed.
• jsIpfsOpts should be an object which specifies advanced configurations to the node.

Enable window.ipfs

window.ipfs is an experimental feature provided by ipfs-companion browser extension. It supports passing an optional list of permissions to display a single ACL prompt the first time it is used:

const { ipfs, provider } = await getIpfs({
  tryWindow: true,
  permissions: { commands: ['add','cat','id', 'version'] },
  tryJsIpfs: true,
...

Note: Make sure to enable at least one other provider such as js-ipfs as a fallback to ensure users without window.ipfs are able to use your app.

Test

> npm test

Lint

Perform standard linting on the code:

> npm run lint

Contribute

Feel free to dive in! Open an issue or submit PRs.

To contribute to IPFS in general, see the contributing guide.

License

MIT © Protocol Labs