IPFS JavaScript implementation.
This repo contains the JavaScript implementation of the IPFS protocol, with feature parity to the Go implementation.
Consult the Roadmap for a complete state description of the project, or you can find in process updates in our Captain.log. A lot of components can be used currently, but it is a WIP, so beware of the Dragons 🐉.
This project is available through npm. To install:
$ npm install ipfs --saveRequires npm@3 and node >= 4, tested on OSX & Linux, expected to work on Windows.
To include this project programmatically:
var IPFS = require('ipfs')
var 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 --globalThe 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.
The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust the asset management process.
var ipfs = require('ipfs');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>The jsipfs CLI, available when js-ipfs is installed globably, 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
# ...
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 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>
// Create the IPFS node instance
const node = new IPFS(repo)
// We need to init our repo, in this case the repo was empty
// We are picking 2048 bits for the RSA key that will be our PeerId
node.init({ emptyRepo: true, bits: 2048 }, (err) => {
if (err) { throw err }
// Once the repo is initiated, we have to load it so that the IPFS
// instance has its config values. This is useful when you have
// previous created repos and you don't need to generate a new one
node.load((err) => {
if (err) { throw err }
// Last but not the least, we want our IPFS node to use its peer
// connections to fetch and serve blocks from.
node.goOnline((err) => {
if (err) { throw err }
// Here you should be good to go and call any IPFS function
})
})We are working on making this init process better, see ipfs#556 for the discussion.
If you have built an example, please share it with the community by submitting a Pull Request to this repo!.
A complete API definition is in the works. Meanwhile, you can learn how to you use js-ipfs through the standard interface at
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:
> git clone https://github.com/ipfs/js-ipfs.git
> cd js-ipfs> npm install> npm test
# 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 Browser tests
> npm run test:browserConforming to linting rules is a prerequisite to commit to js-ipfs.
> npm run lint> npm run build
| Package | Version | Dependencies | DevDependencies |
|---|---|---|---|
ipfs |
 |
|
 |
ipfs-api |
 |
 |
 |
ipfs-unixfs-engine |
 |
 |
 |
ipfs-repo |
 |
 |
 |
ipfs-unixfs |
 |
 |
 |
ipfs-block-service |
 |
 |
 |
ipfs-block |
 |
 |
 |
peer-id |
 |
 |
 |
peer-info |
 |
 |
 |
ipfs-merkle-dag |
 |
 |
 |
ipfs-multipart |
 |
 |
 |
multiaddr |
 |
 |
 |
multihashing |
 |
 |
 |
multihashes |
 |
 |
 |
mafmt |
 |
 |
 |
In addition there is the libp2p module family that makes up the network layer, the full list can be found here
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.
MIT.