IPFS Lite (js-ipfs-lite)

A lightweight, extensible IPFS peer for Nodejs and the browser.

IPFS Lite runs the minimal setup required to get and put data on the IPFS network.

NOTE For now, this is a highly experimental library. Use with caution. Ask for help on https://slack.textile.io. We are hoping to dedicate additional development time soon, but cannot guarantee support at this time.

Background
Install
Usage
API
Maintainers
Contributing
License

Background

The goal of IPFS Lite is to run the bare minimal functionality for any application to interact with the IPFS network (by getting and putting IPLD blocks). This saves having to deal with the complexities of using a full IPFS peer, while maintaining the ability to share the underlying libp2p host and DAG service with other components. It is also extremely lightweight, highly extensible, and easy to work with in both Nodejs and the browser. It supports async/await by default, and the library comes with additional tools to help bootstrap a default IPFS Lite instance with minimal configuration. It is a port of the Go IPFS Lite library, and as such, has most of the same requirements.

IPFS-lite Libraries

The following includes information about support for ipfs-lite.

Name	Build	Target	Description
`ipfs-lite`			The reference implementation of ipfs-lite, written in Go.
`js-ipfs-lite`			The Javascript version of ipfs-lite available for web and nodejs.

Why?

Because 99% of the time, a browser or mobile (d)App only needs to be able to add and get small bits of data over the IPFS network. This library provides that, in a much smaller package (currently less than 1/2 the size of js-ipfs without much optimization -- we will continue to optimize further). It is also highly extensible, so developers need only include the features they need, keeping load times fast, and (d)Apps feeling snappy. Additionally, Textile needed a Typescript-based IPFS solution, and we think others will find the type safety useful as well. Feel free to use the Typescript declarations in your own projects.

What?

Our goal is to provide a highly extensible IPFS "implementation" that supports and small subset of the core IPFS APIs. If you have opinions about what should and should not be included, please let us know.

Install

Note: js-ipfs-lite includes TypeScript type definitions.

npm i @textile/ipfs-lite

Browser

For now, you'll have to bundle your own browser builds, but default builds are coming soon!

Usage

Only import what you need, keeping your bundles small and your load times faster. You can grab a full-featured IPFS Lite peer from the top-level library, or grab specific sub-modules as needed:

// Grab a fully-loaded Peer
import { Peer, BlockStore } from '@textile/ipfs-lite'
import { setupLibP2PHost, MemoryDatastore } = from '@textile/ipfs-lite/dist/setup'

Typescript

import { Peer, BlockStore } from '@textile/ipfs-lite'
// Use any interface-datastore compliant store
import { MemoryDatastore } from 'interface-datastore'
import Libp2p from 'libp2p'

const store = new BlockStore(new MemoryDatastore())

;(async function() {
    // Bring your own libp2p host....
    const host = new Libp2p({ ...libp2Options })
    // ...or, use a full-featured default host
    // const host = await setupLibP2PHost()
    const lite = new Peer(store, host)

    await lite.start()

    const cid = 'QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'
    const data = await lite.getFile(cid)
    console.log(data.toString())
    // Hello World
    await lite.stop()
}

Nodejs

let { Peer, BlockStore } = require('@textile/ipfs-lite')
let { setupLibP2PHost } = require('@textile/ipfs-lite/dist/setup')
let { MemoryDatastore } = require('interface-datastore')

let store = new BlockStore(new MemoryDatastore())

;(async function() {
  let host = await setupLibP2PHost()
  let lite = new Peer(store, host)
  await lite.start()

  let cid = 'QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'
  let data = await lite.getFile(cid)
  console.log(data.toString())
  // Hello World
  await lite.stop()
})()

There are also several useful examples included in the tests of this repo, with tools for creating a default libp2p host exported by default. We've also thrown in some useful interfaces to use when building on IPFS Lite, as well as the Buffer API for use in the browser.

API

See https://textileio.github.io/js-ipfs-lite

Maintainers

Carson Farmer

Contributing

See our code of conduct!

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

Gozala/js-dag-service