node package manager

ipfs

IPFS in JavaScript logo

The JavaScript implementation of the IPFS protocol.




Project status

We've come a long way, but this project is still in Alpha, lots of development is happening, API might change, beware of the Dragons ūüźČ..

Want to get started? Check our examples folder to learn how to spawn an IPFS node in Node.js and in the Browser.

You can check the development status at the Waffle Board.

Throughput Graph

Important to note: DHT and Relay are not finalized yet, you won't have resource discovery happening by default as you get in go-ipfs, we are working actively on this pieces, please follow:

Table of Contents

Install

This project is available through npm. To install:

> npm install ipfs --save

Requires npm@3 and node >= 4.5, tested on OSX & Linux, expected to work on Windows.

Use in Node.js

To include this project programmatically:

const IPFS = require('ipfs')
 
const node = new IPFS()

Through command line tool

In order to use js-ipfs as a CLI, you must install it with the global flag. Run the following (even if you have ipfs installed locally):

$ npm install ipfs --global

The CLI is available by using the command jsipfs in your terminal. This is aliased, instead of using ipfs, to make sure it does not conflict with the Go implementation.

Use in the browser

With browserify, webpack or any bundler

Find examples of how to do this bundling at: https://github.com/ipfs/js-ipfs/tree/master/examples. If you are using webpack, make sure to use version 2 or above, otherwise it won't work.

With script tag

Loading this module in a browser (using a <script> tag) makes the Ipfs object available in the global namespace. The last published version of the package become available for download from unpkg and thus you may use it as the source:

<!-- loading the minified version -->
<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
 
<!-- loading the human-readable (not minified) version -->
<script src="https://unpkg.com/ipfs/dist/index.js"></script>

Usage

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.

# Install js-ipfs globally 
> npm install ipfs --global
> jsipfs --help
Commands:
  bitswap               A set of commands to manipulate the bitswap agent.
  block                 Manipulate raw IPFS blocks.
  bootstrap             Show or edit the list of bootstrap peers.
  commands              List all available commands
  config <key> [value]  Get and set IPFS config values
  daemon                Start a long-running daemon process
# ... 

js-ipfs uses some different default config values, so that they don't clash directly with a go-ipfs node running in the same machine. These are:

  • default repo location: ~/.jsipfs (can be changed with env variable IPFS_PATH)
  • default swarm port: 4002
  • default API port: 5002
  • default Bootstrap is off, to enable it set IPFS_BOOTSTRAP=1

If you want to use WebRTC in your local daemon, you will need to install it separatly by installing globally one of the following modules:

This is a separate step because there isn't still a good open source WebRTC implementation for Node.js that runs in all the envinronments correctly. Example: npm install electron-webrtc --global.

HTTP-API

The HTTP-API exposed by the js-ipfs daemon follows the http-api-spec. You can use any of the IPFS HTTP-API client libraries with it, such as: js-ipfs-api.

IPFS Core (use IPFS as a module)

Create a IPFS node instance

Creating an IPFS instance couldn't be easier, all you have to do is:

// 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'
  })
})

Advanced options when creating an IPFS node.

When starting a node, you can:

// IPFS will need a repo, it can create one for you or you can pass
// it a repo instance of the type IPFS Repo
// https://github.com/ipfs/js-ipfs-repo
const repo = <IPFS Repo instance or repo path>
 
// If you want to use the WebRTC transport in Node.js, you have to add it separately. Note, WebRTC comes out of the box in the Browser!
const wrtc = require('wrtc') // or require('electron-webrtc')()
const WStar = require('libp2p-webrtc-star')
const wstar = WStar({ wrtc: wrtc })
 
const node = new IPFS({
  repo: repo,
  init: true, // default
  // init: false,
  // init: {
  //   bits: 1024 // size of the RSA key generated
  // },
  start: true,
  // start: false,
  EXPERIMENTAL: { // enable experimental features
    pubsub: true,
    sharding: true, // enable dir sharding
    wrtcLinuxWindows: true, // use unstable wrtc module on Linux or Windows with Node.js,
    dht: true // enable KadDHT, currently not interopable with go-ipfs
  },
  config: { // overload the default config
    Addresses: {
      Swarm: [
        '/ip4/127.0.0.1/tcp/1337'
      ]
    }
  },
  libp2p: { // add custom modules to the libp2p stack of your node
    modules: { // here we show how to add WebRTC. Note, WebRTC comes out of the box in the Browser! You just need to do this for Node.js
      transport: [wstar]
      discovery: [wstar.discovery]
    }
  }
})
 
// Events
 
node.on('ready', () => {})    // Node is ready to use when you first create it
node.on('error', (err) => {}) // Node has hit some error while initing/starting
 
node.on('init', () => {})     // Node has successfully finished initing the repo
node.on('start', () => {})    // Node has started
node.on('stop', () => {})     // Node has stopped

Tutorials and Examples

You can find some examples and tutorials in the examples folder, these exist to help you get started using js-ipfs.

API

A complete API definition is in the works. Meanwhile, you can learn how to you use js-ipfs through the standard interface at .

bitswap
block
bootstrap
config
dag
dht (not implemented, yet!)
files
generic operations
object
pin (not implemented, yet!)
pubsub
repo
swarm
libp2p

Every IPFS instance also exposes the libp2p API at ipfs.libp2p. The formal interface for this API hasn't been defined by you can find documentation at its implementations:

Domain data types

A set of data types are exposed directly from the IPFS instance under ipfs.types. That way you're not required to import/require the following.

FAQ

Is there WebRTC support for js-ipfs with Node.js?

Yes there is, however, Linux and Windows support is limited/unstable. For Linux users, you need to follow the install the extra packages for Linux listed on the wrtc npm page and then, when doing initing the repo, do:

> IPFS_WRTC_LINUX_WINDOWS=1 jsipfs init

This will create a repo with a config file that contains a WebRTC multiaddr.

Packages

Package Version Deps DevDeps Build
API Specs
interface-ipfs-core npm Dep Status devDep Status Build Status
http-api-spec
cli spec
Repo
ipfs-repo npm Dep Status devDep Status Build Status
DAG
ipld-resolver npm Dep Status devDep Status Build Status
ipld-dag-pb npm Dep Status devDep Status Build Status
ipld-dag-cbor npm Dep Status devDep Status Build Status
Files
ipfs-unixfs-engine npm Dep Status devDep Status Build Status
Exchange
ipfs-block-service npm Dep Status devDep Status Build Status
Swarm/libp2p
js-libp2p npm Dep Status devDep Status Build Status
libp2p-ipfs-nodejs npm Dep Status devDep Status Build Status
libp2p-ipfs-browser npm Dep Status devDep Status Build Status
Data Types
ipfs-block npm Dep Status devDep Status Build Status
ipfs-unixfs npm Dep Status devDep Status Build Status
peer-id npm Dep Status devDep Status Build Status
peer-info npm Dep Status devDep Status Build Status
multiaddr npm Dep Status devDep Status Build Status
multihashes npm Dep Status devDep Status Build Status
Generics/Utils
ipfs-api npm Dep Status devDep Status Build Status
ipfs-multipart npm Dep Status devDep Status Build Status
multihashing npm Dep Status devDep Status Build Status
mafmt npm Dep Status devDep Status Build Status

Development

Clone and install dependencies

> git clone https://github.com/ipfs/js-ipfs.git
> cd js-ipfs
> npm install

Run unit tests

# run all the unit tsts 
> npm test
 
# run just IPFS tests in Node.js 
> npm run test:unit:node:core
 
# run just IPFS core tests 
> npm run test:unit:node:core
 
# run just IPFS HTTP-API tests 
> npm run test:unit:node:http
 
# run just IPFS CLI tests 
> npm run test:unit:node:cli
 
# run just IPFS core tests in the Browser (Chrome) 
> npm run test:unit:browser

Run interop tests

# run all the interop tsts 
> npm run test:interop
 
# run just IPFS interop tests in Node.js using one go-ipfs daemon and one js-ipfs daemon 
> npm run test:interop:node
 
# run just IPFS interop testsin the Browser (Chrome) using one instance in the browser and one go-ipfs daemon 
> npm run test:interop:browser

Run benchmark tests

# run all the interop tsts 
> npm run test:benchmark
 
# run just IPFS benchmarks in Node.js 
> npm run test:benchmark:node
 
# run just IPFS benchmarks in Node.js for an IPFS instance 
> npm run test:benchmark:node:core
 
# run just IPFS benchmarks in Node.js for an IPFS daemon 
> npm run test:benchmark:node:http
 
# run just IPFS benchmarks in the browser (Chrome) 
> npm run test:benchmark:browser

Lint

Conforming to linting rules is a prerequisite to commit to js-ipfs.

> npm run lint

Build a dist version

> npm run build

Runtime Support

Code Architecture and folder Structure

Source code
> tree src -L 2
src                 # Main source code folder
‚Ēú‚ĒÄ‚ĒĬ†cli¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†#¬†Implementation¬†of¬†the¬†IPFS¬†CLI
‚Ēā¬†¬†¬†‚ĒĒ‚ĒÄ‚ĒĬ†...
‚Ēú‚ĒÄ‚ĒĬ†http-api¬†¬†¬†¬†¬†¬†¬†¬†#¬†The¬†HTTP-API¬†implementation¬†of¬†IPFS¬†as¬†defined¬†by¬†http-api-spec
‚Ēú‚ĒÄ‚ĒĬ†core¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†#¬†IPFS¬†implementation,¬†the¬†core¬†(what¬†gets¬†loaded¬†in¬†browser)
‚Ēā¬†¬†¬†‚Ēú‚ĒÄ‚ĒĬ†components¬†¬†#¬†Each¬†of¬†IPFS¬†subcomponent
‚Ēā¬†¬†¬†‚ĒĒ‚ĒÄ‚ĒĬ†...
‚ĒĒ‚ĒÄ‚ĒĬ†...

IPFS Core Architecture

What does this image explain?

  • IPFS uses ipfs-repo which picks fs or indexeddb as its storage drivers, depending if it is running in Node.js or in the Browser.
  • The exchange protocol, bitswap, uses the Block Service which in turn uses the Repo, offering a get and put of blocks to the IPFS implementation.
  • The DAG api (previously Object) comes from the IPLD Resolver, it can support several IPLD Formats (i.e: dag-pb, dag-cbor, etc).
  • The Files API uses ipfs-unixfs-engine to import and export files to and from IPFS.
  • Swarm, the component that offers a network API, uses libp2p to dial and listen for connections, use the DHT, discovery mechanisms and more. libp2p-ipfs-nodejs is used in case of running in Node.js and libp2p-ipfs-browser is used in the case of the Browser.

Contribute

IPFS implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out:

  • Go through the modules below and check out existing issues. This would be especially useful for modules in active development. Some knowledge of IPFS may be required, as well as the infrastructure behind it - for instance, you may need to read up on p2p and more complex operations like muxing to be able to help technically.
  • Perform code reviews. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs.
  • Take a look at go-ipfs and some of the planning repositories or issues: for instance, the libp2p spec here. Contributions here that would be most helpful are top-level comments about how it should look based on our understanding. Again, the more eyes the better.
  • Add tests. There can never be enough tests.
  • Contribute to the FAQ repository with any questions you have about IPFS or any of the relevant technology. A good example would be asking, 'What is a merkledag tree?'. If you don't know a term, odds are, someone else doesn't either. Eventually, we should have a good understanding of where we need to improve communications and teaching together to make IPFS and IPN better.

Want to hack on IPFS?

License

FOSSA Status