Xmader / js-ipfs

IPFS implementation in JavaScript

The JavaScript implementation of the IPFS protocol.

Upgrading from <=0.40 to 0.41? See the release notes for the list of API changes and the migration guide.

Project status - Alpha

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.

🚨 Please read this 🚨 The DHT, a fundamental piece for automatic content and peer discovery is not yet complete. There are multiple applications that can be built without this service but nevertheless it is fundamental to getting that magic IPFS experience. The current status is that implementation is done and merged and we're working on performance issues. Expect the DHT to be available in a release very soon.

Weekly Core Implementations Call

Tech Lead

David Dias

Lead Maintainer

Alan Shaw

Table of Contents

• Structure
• Development
  • Clone and install dependencies
  • Run tests
  • Lint
  • Build a dist version
  • Publishing new versions
  • Using prerelease versions
• Contribute
  • Want to hack on IPFS?
• License

Structure

This project is broken into several modules, their purposes are:

• /packages/ipfs The core implementation
• /packages/ipfs-http-client A client for the RPC-over-HTTP API presented by both js-ipfs and go-ipfs
• /packages/interface-ipfs-core Tests to ensure adherance of an implementation to the spec
• /packages/ipfs-utils Helpers and utilities common to core and the HTTP RPC API client
• /packages/ipfs-mfs The mfs implementation
• /packages/ipfs-multipart A module that handles adding files via multipart HTTP requests for core and the mfs

Development

Clone and install dependencies

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

This will install lerna and bootstrap the various packages, dedpuing and hoisting dependencies into the root folder.

If later you add new dependencies to submodules or just wish to remove all the node_modules/dist folders and start again, run npm run reset && npm install from the root.

See the scripts section of the root package.json for more commands.

Run tests

# run all the unit tests
> npm test

# run just IPFS tests in Node.js
> npm run test:node

# run just IPFS tests in a browser
> npm run test:browser

# run just IPFS tests in a webworker
> npm run test:webworker

More granular test suites can be run from each submodule.

Please see the package.json in each submodule for available commands.

Lint

Please run the linter before submitting a PR, the build will not pass if it fails:

> npm run lint

Build a dist version

> npm run build

Publishing new versions

1. Ensure you have a GH_TOKEN env var containing a GitHub Personal Access Token with public_repo permissions
2. From the root of this repo run npm run release and follow the on screen prompts. It will use conventional commits to work out the new package version

Using prerelease versions

Any changed packages from each successful build of master are published to npm as canary builds under the npm tag next.

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. 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.

Want to hack on IPFS?

Check out ipfs/community/CONTRIBUTING_JS.md for details on coding standards, commit messages and other project conventions

License