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.
Please read this: DHT (automatic content discovery) and Circuit Relay (pierce through NATs and dial between any node in the network) are two fundamental pieces that are not finalized yet. There are multiple applications that can be built without these two services but nevertheless they are fundamental to get that magic IPFS experience. If you want to track progress or contribute, please follow:
This project is available through npm. To install run
> npm install ipfs --save
Requires npm@3 and node@6 or above, tested on OSX & Linux, expected to work on Windows.
To include this project programmatically:
const IPFS = require('ipfs')
const node = new IPFS()
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.
Learn how to bundle with browserify and webpack in the examples
folder.
You can also load it using a <script>
using the unpkg CDN or the jsDelivr CDN. Inserting one of the following lines will make a Ipfs
object available in the global namespace.
<!-- loading the minified version -->
<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/ipfs/dist/index.min.js"></script>
<!-- loading the human-readable (not minified) version -->
<script src="https://unpkg.com/ipfs/dist/index.js"></script>
<script src="https://cdn.jsdelivr.net/npm/ipfs/dist/index.js"></script>
Inserting one of the above lines will make an Ipfs
object available in the global namespace.
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 variableIPFS_PATH
) - default swarm port:
4002
- default API port:
5002
- default Bootstrap is off, to enable it set
IPFS_BOOTSTRAP=1
The IPFS Daemon exposes the API defined http-api-spec
. You can use any of the IPFS HTTP-API client libraries with it, such as: js-ipfs-api.
If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check out ipfsd-ctl 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:
// 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'
})
})
You can find some examples and tutorials in the examples folder, these exist to help you get started using js-ipfs
.
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:
-
repo
(string oripfs.Repo
instance): The file path at which to store the IPFS node’s data. Alternatively, you can set up a customized storage system by providing anipfs.Repo
instance. (Default:'~/.jsipfs'
in Node.js,'ipfs'
in browsers.)Example:
// Store data outside your user directory const node = new IPFS({ repo: '/var/ipfs/data' })
-
init
(boolean or object): Initialize the repo when creating the IPFS node. (Default:true
)If you have already initialized a repo before creating your IPFS node (e.g. you are loading a repo that was saved to disk from a previous run of your program), you must make sure to set this to
false
. Note that initializing a repo is different from creating an instance ofipfs.Repo
. The IPFS constructor sets many special properties when initializing a repo, so you should usually not try and callrepoInstance.init()
yourself.Instead of a boolean, you may provide an object with custom initialization options. All properties are optional:
init.emptyRepo
(boolean) Whether to remove built-in assets, like the instructional tour and empty mutable file system, from the repo. (Default:false
)init.bits
(number) Number of bits to use in the generated key pair. (Default:2048
)init.pass
(string) A passphrase to encrypt keys. You should generally use the top-levelpass
option instead of theinit.pass
option (this one will take its value from the top-level option if not set).
-
start
(boolean): Iffalse
, do not automatically start the IPFS node. Instead, you’ll need to manually callnode.start()
yourself. (Default:true
) -
pass
(string): A passphrase to encrypt/decrypt your keys. -
EXPERIMENTAL
(object): Enable and configure experimental features.pubsub
(boolean): Enable libp2p pub-sub. (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
)dht
(boolean): Enable KadDHT. This is currently not interopable withgo-ipfs
.relay
(object): Configure circuit relay (see the circuit relay tutorial to learn more).enabled
(boolean): Enable circuit relay dialer and listener. (Default:false
)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
)
-
config
(object) Modify the default IPFS node config. Find the Node.js defaults atsrc/core/runtime/config-nodejs.js
and the browser defaults atsrc/core/runtime/config-browser.js
. This object will be merged with the default config; it will not replace it. -
libp2p
(object) add custom modules to the libp2p stack of your nodemodules
(object):transport
(Array<libp2p.Transport>): An array of additional Libp2p transport instances to use. See libp2p/interface-transport for details.discovery
(Array<libp2p.PeerDiscovery>): An array of additional Libp2p peer discovery instances to use. See libp2p/peer-discovery for details.
IPFS instances are Node.js EventEmitters. You can listen for events by calling node.on('event', handler)
:
const node = new IPFS({ repo: '/var/ipfs/data' })
node.on('error', errorObject => console.error(errorObject))
-
error
is always accompanied by anError
object with information about the error that ocurred.node.on('error', error => { console.error(error.message) })
-
init
is emitted after a new repo has been initialized. It will not be emitted if you set theinit: false
option on the constructor. -
ready
is emitted when a node is ready to use. This is the final event you will receive when creating a node (afterinit
andstart
).When creating a new IPFS node, you should almost always wait for the
ready
event before calling methods or interacting with the node. -
start
is emitted when a node has started listening for connections. It will not be emitted if you set thestart: false
option on the constructor. -
stop
is emitted when a node has closed all connections and released access to its repo. This is usually the result of callingnode.stop()
.
Start listening for connections with other IPFS nodes on the network. In most cases, you do not need to call this method — new IPFS()
will automatically do it for you.
This method is asynchronous. There are several ways to be notified when the node has finished starting:
- If you call
node.start()
with no arguments, it returns a promise. - 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.)
- You can listen for the
start
event.
const node = new IPFS({ start: false })
// Use a promise:
node.start()
.then(() => console.log('Node started!'))
.catch(error => console.error('Node failed to start!', error))
// OR use a callback:
node.start(error => {
if (error) {
console.error('Node failed to start!', error)
return
}
console.log('Node started!')
})
// OR use events:
node.on('error', error => console.error('Something went terribly wrong!', error))
node.on('start', () => console.log('Node started!'))
node.start()
Close and stop listening for connections with other IPFS nodes, then release access to the node’s repo.
This method is asynchronous. There are several ways to be notified when the node has completely stopped:
- If you call
node.stop()
with no arguments, it returns a promise. - 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.)
- You can listen for the
stop
event.
const node = new IPFS()
node.on('ready', () => {
console.log('Node is ready to use!')
// Stop with a promise:
node.stop()
.then(() => console.log('Node stopped!'))
.catch(error => console.error('Node failed to stop cleanly!', error))
// OR use a callback:
node.stop(error => {
if (error) {
console.error('Node failed to stop cleanly!', error)
return
}
console.log('Node stopped!')
})
// OR use events:
node.on('error', error => console.error('Something went terribly wrong!', error))
node.stop()
})
The IPFS core API provides all functionality that is not specific to setting up and starting or stopping a node. This API is available directly on an IPFS instance, on the command line (when using the CLI interface), and as an HTTP REST API. For a complete reference, see .
The core API is grouped into several areas:
-
ipfs.files.add(data, [options], [callback])
ipfs.files.addReadableStream([options])
ipfs.files.addPullStream([options])
ipfs.files.cat(ipfsPath, [options], [callback])
ipfs.files.catReadableStream(ipfsPath, [options])
ipfs.files.catPullStream(ipfsPath, [options])
ipfs.files.get(ipfsPath, [options], [callback])
ipfs.files.getReadableStream(ipfsPath, [options])
ipfs.files.getPullStream(ipfsPath, [options])
-
ipfs.object.new([template][, callback])
ipfs.object.put(obj, [options, callback])
ipfs.object.get(multihash, [options, callback])
ipfs.object.data(multihash, [options, callback])
ipfs.object.links(multihash, [options, callback])
ipfs.object.stat(multihash, [options, callback])
ipfs.object.patch.addLink(multihash, DAGLink, [options, callback])
ipfs.object.patch.rmLink(multihash, DAGLink, [options, callback])
ipfs.object.patch.appendData(multihash, data, [options, callback])
ipfs.object.patch.setData(multihash, data, [options, callback])
- key
ipfs.key.export(name, password, [callback])
ipfs.key.gen(name, options, [callback])
ipfs.key.import(name, pem, password, [callback])
ipfs.key.list([callback])
ipfs.key.rename(oldName, newName, [callback])
ipfs.key.rm(name, [callback])
- crypto (not yet implemented)
-
ipfs.bootstrap.list
ipfs.bootstrap.add
ipfs.bootstrap.rm
-
ipfs.bitswap.wantlist()
ipfs.bitswap.stat()
ipfs.bitswap.unwant()
-
libp2p. Every IPFS instance also exposes the libp2p SPEC at
ipfs.libp2p
. The formal interface for this SPEC hasn't been defined by you can find documentation at its implementations:
-
ipfs.id([callback])
ipfs.version([callback])
ipfs.ping()
ipfs.init([options], callback)
ipfs.start([callback])
ipfs.stop([callback])
ipfs.isOnline()
-
ipfs.repo.init
ipfs.repo.stat([options, callback])
ipfs.repo.version([callback])
ipfs.repo.gc([options, callback])
(not implemented, yet!)
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.
ipfs.types.Buffer
ipfs.types.PeerId
ipfs.types.PeerInfo
ipfs.types.multiaddr
ipfs.types.multibase
ipfs.types.multihash
ipfs.types.CID
ipfs.types.dagPB
ipfs.types.dagCBOR
A set of utils are exposed directly from the IPFS instance under ipfs.util
. That way you're not required to import/require the following:
To add a WebRTC transport to your js-ipfs node, you must add a WebRTC multiaddr. To do that, simple override the config.Addresses.Swarm array which contains all the multiaddrs which the IPFS node will use. See below:
const node = new IPFS({
config: {
Addresses: {
Swarm: [
'/dns4/wrtc-star.discovery.libp2p.io/tcp/443/wss/p2p-webrtc-star'
]
}
}
})
node.on('ready', () => {
// your instance with WebRTC is ready
})
Important: This transport usage is kind of unstable and several users have experienced crashes. Track development of a solution at ipfs#1088.
Yes, however, bare in mind that there isn't a 100% stable solution to use WebRTC in Node.js, use it at your own risk. The most tested options are:
- wrtc - Follow the install instructions.
- electron-webrtc
To add WebRTC support in a IPFS node instance, do:
const wrtc = require('wrtc') // or require('electron-webrtc')()
const WStar = require('libp2p-webrtc-star')
const wstar = new WStar({ wrtc: wrtc })
const node = new IPFS({
repo: 'your-repo-path',
// start: false,
config: {
Addresses: {
Swarm: [
"/ip4/0.0.0.0/tcp/4002",
"/ip4/127.0.0.1/tcp/4003/ws",
"/dns4/wrtc-star.discovery.libp2p.io/tcp/443/wss/p2p-webrtc-star"
]
}
},
libp2p: {
modules: {
transport: [wstar],
discovery: [wstar.discovery]
}
}
})
node.on('ready', () => {
// your instance with WebRTC is ready
})
To add WebRTC support to the IPFS daemon, you only need to install one of the WebRTC modules globally:
npm install wrtc --global
# or
npm install electron-webrtc --global
Then, update your IPFS Daemon config to include the multiaddr for this new transport on the Addresses.Swarm
array. Add: "/dns4/wrtc-star.discovery.libp2p.io/wss/p2p-webrtc-star"
You'll need to execute a compatible signaling server
(libp2p-webrtc-star works) and include the correct configuration param for your IPFS node:
- provide the
multiaddr
for thesignaling server
const node = new IPFS({
repo: 'your-repo-path',
config: {
Addresses: {
Swarm: [
'/ip4/127.0.0.1/tcp/9090/ws/p2p-webrtc-star'
]
}
}
})
The code above assumes you are running a local signaling server
on port 9090
. Provide the correct values accordingly.
Yes, websocket-star! A WebSockets based transport that uses a Relay to route the messages. To enable it, just do:
const node = new IPFS({
config: {
Addresses: {
Swarm: [
'/dns4/ws-star.discovery.libp2p.io/tcp/443/wss/p2p-websocket-star'
]
}
}
})
node.on('ready', () => {
// your instance with websocket-star is ready
})
Yes, unfortunately, due to Chrome aggressive resource throttling policy, it cuts freezes the execution of any background tab, turning an IPFS node that was running on that webpage into a vegetable state.
A way to mitigate this in Chrome, is to run your IPFS node inside a Service Worker, so that the IPFS instance runs in a background process. You can learn how to install an IPFS node as a service worker in here the repo ipfs-service-worker
Yes you can and in many ways. Read ipfs/notes#256 for the multiple options.
If your electron-rebuild step is failing, all you need to do is:
# Electron's version.
export npm_config_target=2.0.0
# The architecture of Electron, can be ia32 or x64.
export npm_config_arch=x64
export npm_config_target_arch=x64
# Download headers for Electron.
export npm_config_disturl=https://atom.io/download/electron
# Tell node-pre-gyp that we are building for Electron.
export npm_config_runtime=electron
# Tell node-pre-gyp to build module from source code.
export npm_config_build_from_source=true
# Install all dependencies, and store cache to ~/.electron-gyp.
HOME=~/.electron-gyp npm install
If you find any other issue, please check the Electron Support
issue.
Ask for help in our forum at https://discuss.ipfs.io or in IRC (#ipfs on Freenode).
We have automatic Docker builds setup with Docker Hub: https://hub.docker.com/r/ipfs/js-ipfs/
All branches in the Github repository maps to a tag in Docker Hub, except master
Git branch which is mapped to latest
Docker tag.
You can run js-ipfs like this:
$ docker run -it -p 4002:4002 -p 4003:4003 -p 5002:5002 -p 9090:9090 ipfs/js-ipfs:latest
initializing ipfs node at /root/.jsipfs
generating 2048-bit RSA keypair...done
peer identity: Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
to get started, enter:
jsipfs files cat /ipfs/QmfGBRT6BbWJd7yUc2uYdaUZJBbnEFvTqehPFoSMQ6wgdr/readme
Initializing daemon...
Using wrtc for webrtc support
Swarm listening on /ip4/127.0.0.1/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
Swarm listening on /ip4/172.17.0.2/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
Swarm listening on /ip4/127.0.0.1/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
Swarm listening on /ip4/172.17.0.2/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS
API is listening on: /ip4/0.0.0.0/tcp/5002
Gateway (readonly) is listening on: /ip4/0.0.0.0/tcp/9090
Daemon is ready
$ curl --silent localhost:5002/api/v0/id | jq .ID
"Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS"
Package | Version | Deps | DevDeps | Travis | Circle | AppVeyor | Coverage |
---|---|---|---|---|---|---|---|
API Specs | |||||||
interface-ipfs-core |
|||||||
http-api-spec |
|||||||
cli spec |
|||||||
Repo | |||||||
ipfs-repo |
|||||||
DAG | |||||||
ipld-resolver |
|||||||
ipld-dag-pb |
|||||||
ipld-dag-cbor |
|||||||
Files | |||||||
ipfs-unixfs-engine |
|||||||
Exchange | |||||||
ipfs-block-service |
|||||||
ipfs-bitswap |
|||||||
Swarm/libp2p | |||||||
js-libp2p |
|||||||
js-libp2p-circuit |
|||||||
js-libp2p-floodsub |
|||||||
js-libp2p-kad-dht |
|||||||
js-libp2p-mdns |
|||||||
js-libp2p-multiplex |
|||||||
js-libp2p-railing |
|||||||
js-libp2p-secio |
|||||||
js-libp2p-tcp |
|||||||
js-libp2p-webrtc-star |
|||||||
js-libp2p-websocket-star |
|||||||
js-libp2p-websockets |
|||||||
Data Types | |||||||
ipfs-block |
|||||||
ipfs-unixfs |
|||||||
peer-id |
|||||||
peer-info |
|||||||
multiaddr |
|||||||
multihashes |
|||||||
Generics/Utils | |||||||
ipfs-api |
|||||||
ipfs-multipart |
|||||||
is-ipfs |
|||||||
multihashing |
|||||||
mafmt |
|||||||
Crypto | |||||||
libp2p-crypto |
|||||||
libp2p-keychain |
> git clone https://github.com/ipfs/js-ipfs.git
> cd js-ipfs
> npm install
# run all the unit tsts
> npm test
# run just IPFS tests in Node.js
> npm run test:node:core
# run just IPFS core tests
> npm run test:node:core
# run just IPFS HTTP-API tests
> npm run test:node:http
# run just IPFS CLI tests
> npm run test:node:cli
# run just IPFS core tests in the Browser (Chrome)
> npm run test:browser
Run the interop tests with https://github.com/ipfs/interop
# run all the benchmark tests
> npm run benchmark
# run just IPFS benchmarks in Node.js
> npm run benchmark:node
# run just IPFS benchmarks in Node.js for an IPFS instance
> npm run benchmark:node:core
# run just IPFS benchmarks in Node.js for an IPFS daemon
> npm run benchmark:node:http
# run just IPFS benchmarks in the browser (Chrome)
> npm run benchmark:browser
Conforming to linting rules is a prerequisite to commit to js-ipfs.
> npm run lint
> npm run build
> 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
│ └── ...
└── ...
The HTTP API exposed with js-ipfs can also be used for exposing metrics about the running js-ipfs node and other Node.js metrics.
To enable it, you need to set the environment variable IPFS_MONITORING
(any value)
Once the environment variable is set and the js-ipfs daemon is running, you can get the metrics (in prometheus format) by making a GET request to the following endpoint:
http://localhost:5002/debug/metrics/prometheus
What does this image explain?
- IPFS uses
ipfs-repo
which picksfs
orindexeddb
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, to use the DHT, for discovery mechanisms, and more. libp2p-ipfs-nodejs is used when running in Node.js and libp2p-ipfs-browser is used when running in the browser.
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. 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.