Explore the docs
·
View Demo
·
Report Bug
·
Request Feature/Example
- Table of Contents
- About The Project
- Getting Started
- Usage
- Documentation
- Contributing
- Want to hack on IPFS?
- Read the docs
- Look into other examples to learn how to spawn a Helia node in Node.js and in the Browser
- Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it
- Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs
- Check out https://docs.ipfs.io for tips, how-tos and more
- See https://blog.ipfs.io for news and more
- Need help? Please ask 'How do I?' questions on https://discuss.ipfs.io
Make sure you have installed all of the following prerequisites on your development machine:
- Git - Download & Install Git. OSX and Linux machines typically have this already installed.
- Node.js - Download & Install Node.js and the npm package manager.
> npm install> npm run 101-basics
> npm run 102-unixfs-dirs
> npm run 103-glob-unixfs
> npm run 201-storage
> npm run 202-persistent-peer
> npm run 301-networking
> npm run 302-mdns
> npm run 303-metrics
> npm run 304-pnet
> npm run 401-pinning
> npm run 402-providing
> npm run 403-block-brokersIn this tutorial, we go through spawning a Helia node and interacting with UnixFS, adding bytes, directories, and files to the node and retrieving them.
It is split into multiple parts, each part builds on the previous one - basics of interaction with UnixFS, storage, networking, and finally providing, garbage collection and pinning.
For this tutorial, you need to install all dependencies in the package.json using npm install.
The first example goes into the the basics of interacting with UnixFS, adding bytes, directories, and files to the node and retrieving them.
To run it, use the following command:
> npm run 101-basicsThe second example goes into the basics of working with directories with UnixFS.
To run it, use the following command:
> npm run 102-unixfs-dirsThe third example goes into using [globSource] to merkelize files and directories from your local file system into UnixFS and exporting the UnixFS DAG as a CAR file.
To run it, use the following command:
> npm run 103-glob-unixfsTake a look at 201-storage.js where we explore how to configure different types of persistent storage for your Helia node.
To run it, use the following command:
> npm run 201-storageIf you run the example twice: you may notice that the second time the file is found in the blockstore without being added again.
At it's heart IPFS is about blocks of data addressed by a CID. When you add a file to your local Helia node, it is split up into a number of blocks, all of which are stored in a blockstore.
Each block has a CID, an identifier that is unique to that block and can be used to request it from other nodes in the network.
A blockstore is a key/value store where the keys are CIDs and the values are Uint8Arrays.
By default we're going to use an in-memory blockstore, though later you may wish to use one that stores blocks on a filesystem.
import { MemoryBlockstore } from 'blockstore-core'
const blockstore = new MemoryBlockstore()There are many blockstore implementations available. Some common ones are:
- blockstore-fs - store blocks in a directory on the filesystem using Node.js
- blockstore-idb - store blocks in IndexedDB in the browser
- blockstore-s3 - store blocks in an AWS S3 bucket
The datastore stores Helia and libp2p state, such as IPNS names, MFS root CID, pin metadata, kad-dht routing table, and peer store data including WebRTC certificates.
Similar to the blockstore, a datastore is a key/value store where the keys are strings and the values are Uint8Arrays.
import { MemoryDatastore } from 'datastore-core'
const datastore = new MemoryDatastore()Commonly used datastore implementations are:
- datastore-level - store key/value pairs in a LevelDB instance
- datastore-idb - store key/value pairs in IndexedDB in the browser
- datastore-s3 - store key/value pairs in an AWS S3 bucket
The 202-persistent-peer.js example demonstrates how to create a Helia node with a persistent peer ID using the FsDatastore.
This is useful when you want your node to maintain the same identity in the network, allowing other peers to recognize and trust your node consistently. To run it, use the following command:
> npm run 202-persistent-peerIf you run the example twice, you will see that the peer ID is the same.
The final example is 301-networking.js.
Adding blocks to your local blockstore is great but using your Helia node's libp2p instance allows you to unlock the full power of the distributed web.
With libp2p configured you can retrieve blocks from remote peers, and those peers can retrieve blocks from you.
libp2p is the networking layer that IPFS works on top of. It is a modular system, comprising of transports, connection encrypters, stream multiplexers, etc.
import { createLibp2p } from 'libp2p'
import { identifyService } from 'libp2p/identify'
import { noise } from '@chainsafe/libp2p-noise'
import { yamux } from '@chainsafe/libp2p-yamux'
import { webSockets } from '@libp2p/websockets'
import { bootstrap } from '@libp2p/bootstrap'
import { MemoryDatastore } from 'datastore-core'
const datastore = new MemoryDatastore()
const libp2p = await createLibp2p({
datastore,
transports: [
webSockets()
],
connectionEncrypters: [
noise()
],
streamMuxers: [
yamux()
],
peerDiscovery: [
bootstrap({
list: [
"/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb",
"/dnsaddr/bootstrap.libp2p.io/p2p/QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt"
]
})
],
services: {
identify: identifyService()
}
})The 302-mdns.js example demonstrates how to use multicast DNS for local peer discovery.
This allows Helia nodes on the same local network to automatically discover each other without requiring bootstrap nodes or DHT lookups.
import { mdns } from '@libp2p/mdns'
// Configure libp2p with mDNS discovery
const libp2p = await createLibp2p({
// ... other configuration ...
peerDiscovery: [
mdns()
],
// ... rest of configuration ...
})
// Listen for peer discovery events
node.libp2p.addEventListener('peer:discovery', (evt) => {
console.log(`Discovered new peer (${evt.detail.id.toString()}) via MDNS`)
node.libp2p.dial(evt.detail.multiaddrs)
})To run this example, use the following command:
> npm run 302-mdnsThe 303-metrics.js example shows how to enable and expose Prometheus metrics for your Helia node, and how to expose the Prometheus HTTP metrics endpoint.
This is useful for monitoring the performance and behavior of your node in production environments.
import { prometheusMetrics } from '@libp2p/prometheus-metrics'
import { register } from 'prom-client'
const helia = await createHelia({
// ... other configuration ...
libp2p: {
metrics: prometheusMetrics(),
}
})
// Create a simple HTTP server to expose metrics
const metricsServer = createServer((req, res) => {
if (req.url === '/metrics' && req.method === 'GET') {
register.metrics()
.then((metrics) => {
res.writeHead(200, { 'Content-Type': 'text/plain' })
res.end(metrics)
})
}
})
metricsServer.listen(9999, '0.0.0.0')To run this example, use the following command:
> npm run 303-metricsjs-libp2p supports two other metrics implementations:
- @libp2p/devtools-metrics: for use in the browser with the js-libp2p DevTools browser extension
- @libp2p/opentelemetry: for use with OpenTelemetry for both metrics and tracing
The 304-pnet.js example demonstrates how to:
- Create a private IPFS network using pre-shared keys
- Connect nodes in a private swarm
- Share content between nodes in the private network
This is useful for creating isolated IPFS networks where only nodes with the correct pre-shared key can connect and share content.
To run this example, use the following command:
> npm run 304-pnetThe 401-pinning.js example demonstrates how to:
- Run garbage collection
- Pin blocks to prevent them from being garbage collected
- Add metadata to pins
To run it, use the following command:
> npm run 401-pinningThe 402-providing.js example shows how to:
- Provide content to the DHT (Distributed Hash Table)
- Make content discoverable by other nodes in the network
To run it, use the following command:
> npm run 402-providingThe 403-block-brokers.js example demonstrates how to:
- Configure different block brokers (Bitswap and Trustless Gateway)
- Set up routing options (libp2p and HTTP Gateway)
To run it, use the following command:
> npm run 403-block-brokersThe 501-ipns.js example demonstrates how to:
- Create and manage IPNS (InterPlanetary Name System) records
- Use DAG-CBOR for encoding data
- Set record lifetime and TTL
To run it, use the following command:
> npm run 501-ipnsContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the IPFS Project
- Create your Feature Branch (
git checkout -b feature/amazing-feature) - Commit your Changes (
git commit -a -m 'feat: add some amazing feature') - Push to the Branch (
git push origin feature/amazing-feature) - Open a Pull Request
The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out:
Read the Code of Conduct and JavaScript Contributing Guidelines.
- Check out existing issues The issue list has many that are marked as 'help wanted' or 'difficulty:easy' which make great starting points for development, many of which can be tackled with no prior IPFS knowledge
- Look at the Helia Roadmap This are the high priority items being worked on right now
- Perform code reviews More eyes will help a. speed the project along b. ensure quality, and c. reduce possible future bugs
- Add tests. There can never be enough tests