https://github.com/ipfs-examples/helia-101
Getting started with Helia
https://github.com/ipfs-examples/helia-101
Last synced: about 1 year ago
JSON representation
Getting started with Helia
- Host: GitHub
- URL: https://github.com/ipfs-examples/helia-101
- Owner: ipfs-examples
- Created: 2023-02-03T10:34:38.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-05-01T07:36:50.000Z (about 1 year ago)
- Last Synced: 2025-05-01T08:30:32.948Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 62.5 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Getting started with Helia
Explore the docs
·
View Demo
·
Report Bug
·
Request Feature/Example
## Table of Contents
- [Table of Contents](#table-of-contents)
- [About The Project](#about-the-project)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running Examples](#running-examples)
- [Usage](#usage)
- [101 - Basics](#101---basics)
- [201 - Storage](#201---storage)
- [Blockstore](#blockstore)
- [Datastore](#datastore)
- [301 - Networking](#301---networking)
- [libp2p](#libp2p)
- [Putting it all together](#putting-it-all-together)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Want to hack on IPFS?](#want-to-hack-on-ipfs)
## About The Project
- Read the [docs](https://ipfs.github.io/helia/modules/helia.html)
- Look into other [examples](https://github.com/ipfs-examples/helia-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
## Getting Started
### Prerequisites
Make sure you have installed all of the following prerequisites on your development machine:
- Git - [Download & Install Git](https://git-scm.com/downloads). OSX and Linux machines typically have this already installed.
- Node.js - [Download & Install Node.js](https://nodejs.org/en/download/) and the npm package manager.
### Installation
```console
> npm install
```
### Running Examples
```console
> npm run 101-basics
> npm run 201-storage
> npm run 301-networking
> npm run 401-providing
```
## Usage
In this tutorial, we go through spawning a Helia node and interacting with [UnixFS](https://docs.ipfs.tech/concepts/glossary/#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`.
### 101 - Basics
The [first example](./101-basics.js) 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:
```console
> npm run 101-basics
```
### 201 - Storage
Out of the box Helia will store all data in-memory. This makes it easy to get started, and to create short-lived nodes that do not persist state between restarts, but what if you want to store large amounts of data for long amounts of time?
Take a look at [201-storage.js](./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:
```console
> npm run 201-storage
```
If you run the example twice: you may notice that the second time the file is found in the blockstore without being added again.
#### Blockstore
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](https://www.npmjs.com/package/interface-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 [CID][]s and the values are [Uint8Array][]s.
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.
```js
import { MemoryBlockstore } from 'blockstore-core'
const blockstore = new MemoryBlockstore()
```
There are many blockstore implementations available. Some common ones are:
- [blockstore-fs](https://www.npmjs.com/package/blockstore-fs) - store blocks in a directory on the filesystem using Node.js
- [blockstore-idb](https://www.npmjs.com/package/blockstore-idb) - store blocks in [IndexedDB][] in the browser
- [blockstore-s3](https://www.npmjs.com/package/blockstore-s3) - store blocks in an AWS [S3][] bucket
#### Datastore
Some facility to store information is required, this needs a [datastore](https://www.npmjs.com/package/interface-datastore).
Similar to the blockstore, a datastore is a key/value store where the keys are strings and the values are [Uint8Array][]s.
```js
import { MemoryDatastore } from 'datastore-core'
const datastore = new MemoryDatastore()
```
Commonly used datastore implementations are:
- [datastore-level](https://www.npmjs.com/package/datastore-level) - store key/value pairs in a [LevelDB](https://github.com/google/leveldb) instance
- [datastore-idb](https://www.npmjs.com/package/datastore-idb) - store key/value pairs in [IndexedDB][] in the browser
- [datastore-s3](https://www.npmjs.com/package/datastore-s3) - store key/value pairs in an AWS [S3][] bucket
### 301 - Networking
The final example is [301-networking.js](./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
[libp2p][] is the networking layer that IPFS works on top of. It is a modular system, comprising of transports, connection encrypters, stream multiplexers, etc.
```js
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()
}
})
```
### 401 - Providing
The final example is [401-providing.js](./401-providing.js).
This example shows:
- How to run garbage collection,
- Pin blocks to prevent them from being garbage collected
- Add metadata to pins
- Provide it to the DHT so that other nodes can find and retrieve it.
To run it, use the following command:
```console
> npm run 401-providing
```
### Putting it all together
Since your Helia node is configured with a libp2p node, you can go to an IPFS Gateway and load the printed hash. Go ahead and try it!
```bash
> npm run 301-networking
Added file: bafkreife2klsil6kaxqhvmhgldpsvk5yutzm4i5bgjoq6fydefwtihnesa
# Copy that hash and load it on the gateway, here is a prefilled url:
# https://ipfs.io/ipfs/bafkreife2klsil6kaxqhvmhgldpsvk5yutzm4i5bgjoq6fydefwtihnesa
```
That's it! You just added and retrieved a file from IPFS!
_For more examples, please refer to the [Documentation](#documentation)_
## Documentation
- [IPFS Primer](https://dweb-primer.ipfs.io/)
- [IPFS Docs](https://docs.ipfs.io/)
- [Tutorials](https://proto.school)
- [More examples](https://github.com/ipfs-examples/helia-examples)
- [API - Helia](https://ipfs.github.io/helia/modules/helia.html)
- [API - @helia/unixfs](https://ipfs.github.io/helia-unixfs/modules/helia.html)
## Contributing
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.
1. Fork the IPFS Project
2. Create your Feature Branch (`git checkout -b feature/amazing-feature`)
3. Commit your Changes (`git commit -a -m 'feat: add some amazing feature'`)
4. Push to the Branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Want to hack on IPFS?
[](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
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](https://github.com/ipfs/community/blob/master/code-of-conduct.md) and [JavaScript Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md).
- **Check out existing issues** The [issue list](https://github.com/ipfs/helia/issues) has many that are marked as ['help wanted'](https://github.com/ipfs/helia/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ['difficulty:easy'](https://github.com/ipfs/helia/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Adifficulty%3Aeasy) which make great starting points for development, many of which can be tackled with no prior IPFS knowledge
- **Look at the [Helia Roadmap](https://github.com/ipfs/helia/blob/main/ROADMAP.md)** 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
[cid]: https://docs.ipfs.tech/concepts/content-addressing "Content Identifier"
[Uint8Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
[libp2p]: https://libp2p.io
[IndexedDB]: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
[S3]: https://aws.amazon.com/s3/