{"id":18584476,"url":"https://github.com/ipfs-examples/helia-101","last_synced_at":"2025-05-16T05:33:11.146Z","repository":{"id":104999232,"uuid":"596970072","full_name":"ipfs-examples/helia-101","owner":"ipfs-examples","description":"Getting started with Helia","archived":false,"fork":false,"pushed_at":"2025-05-01T07:36:50.000Z","size":64,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-01T08:30:32.948Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-03T10:34:38.000Z","updated_at":"2025-05-01T07:36:53.000Z","dependencies_parsed_at":"2024-01-19T10:33:05.303Z","dependency_job_id":"9c1cd7f1-0bbe-4f11-b947-0349d6335b1e","html_url":"https://github.com/ipfs-examples/helia-101","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"ipfs-examples/example-fork-go-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-examples%2Fhelia-101","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-examples%2Fhelia-101/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-examples%2Fhelia-101/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-examples%2Fhelia-101/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs-examples","download_url":"https://codeload.github.com/ipfs-examples/helia-101/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254473838,"owners_count":22077184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T00:27:38.657Z","updated_at":"2025-05-16T05:33:11.139Z","avatar_url":"https://github.com/ipfs-examples.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ipfs/helia\" title=\"Helia\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/ipfs/helia/main/assets/helia.png\" alt=\"Helia logo\" width=\"300\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003e\u003cb\u003eGetting started with Helia\u003c/b\u003e\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/jlord/forkngo/gh-pages/badges/cobalt.png\" width=\"200\"\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://ipfs.github.io/helia/modules/helia.html\"\u003eExplore the docs\u003c/a\u003e\n  ·\n  \u003ca href=\"https://codesandbox.io/\"\u003eView Demo\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/ipfs-examples/helia-examples/issues\"\u003eReport Bug\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/ipfs-examples/helia-examples/issues\"\u003eRequest Feature/Example\u003c/a\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [About The Project](#about-the-project)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Running Examples](#running-examples)\n- [Usage](#usage)\n  - [101 - Basics](#101---basics)\n  - [201 - Storage](#201---storage)\n    - [Blockstore](#blockstore)\n    - [Datastore](#datastore)\n  - [301 - Networking](#301---networking)\n    - [libp2p](#libp2p)\n  - [Putting it all together](#putting-it-all-together)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [Want to hack on IPFS?](#want-to-hack-on-ipfs)\n\n## About The Project\n\n- Read the [docs](https://ipfs.github.io/helia/modules/helia.html)\n- 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\n- Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it\n- Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs\n- Check out https://docs.ipfs.io for tips, how-tos and more\n- See https://blog.ipfs.io for news and more\n- Need help? Please ask 'How do I?' questions on https://discuss.ipfs.io\n\n## Getting Started\n\n### Prerequisites\n\nMake sure you have installed all of the following prerequisites on your development machine:\n\n- Git - [Download \u0026 Install Git](https://git-scm.com/downloads). OSX and Linux machines typically have this already installed.\n- Node.js - [Download \u0026 Install Node.js](https://nodejs.org/en/download/) and the npm package manager.\n\n### Installation\n\n```console\n\u003e npm install\n```\n\n### Running Examples\n\n```console\n\u003e npm run 101-basics\n\u003e npm run 201-storage\n\u003e npm run 301-networking\n\u003e npm run 401-providing\n```\n\n## Usage\n\nIn 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.\n\nIt 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.\n\nFor this tutorial, you need to install all dependencies in the `package.json` using `npm install`.\n\n### 101 - Basics\n\nThe [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.\n\nTo run it, use the following command:\n\n```console\n\u003e npm run 101-basics\n```\n\n### 201 - Storage\n\nOut 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?\n\nTake a look at [201-storage.js](./201-storage.js) where we explore how to configure different types of persistent storage for your Helia node.\n\nTo run it, use the following command:\n\n```console\n\u003e npm run 201-storage\n```\n\nIf you run the example twice: you may notice that the second time the file is found in the blockstore without being added again.\n\n#### Blockstore\n\nAt 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).\n\nEach 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.\n\nA blockstore is a key/value store where the keys are [CID][]s and the values are [Uint8Array][]s.\n\nBy default we're going to use an in-memory blockstore, though later you may wish to use one that stores blocks on a filesystem.\n\n```js\nimport { MemoryBlockstore } from 'blockstore-core'\n\nconst blockstore = new MemoryBlockstore()\n```\n\nThere are many blockstore implementations available. Some common ones are:\n\n- [blockstore-fs](https://www.npmjs.com/package/blockstore-fs) - store blocks in a directory on the filesystem using Node.js\n- [blockstore-idb](https://www.npmjs.com/package/blockstore-idb) - store blocks in [IndexedDB][] in the browser\n- [blockstore-s3](https://www.npmjs.com/package/blockstore-s3) - store blocks in an AWS [S3][] bucket\n\n#### Datastore\n\nSome facility to store information is required, this needs a [datastore](https://www.npmjs.com/package/interface-datastore).\n\nSimilar to the blockstore, a datastore is a key/value store where the keys are strings and the values are [Uint8Array][]s.\n\n```js\nimport { MemoryDatastore } from 'datastore-core'\n\nconst datastore = new MemoryDatastore()\n```\n\nCommonly used datastore implementations are:\n\n- [datastore-level](https://www.npmjs.com/package/datastore-level) - store key/value pairs in a [LevelDB](https://github.com/google/leveldb) instance\n- [datastore-idb](https://www.npmjs.com/package/datastore-idb) - store key/value pairs in [IndexedDB][] in the browser\n- [datastore-s3](https://www.npmjs.com/package/datastore-s3) - store key/value pairs in an AWS [S3][] bucket\n\n### 301 - Networking\n\nThe final example is [301-networking.js](./301-networking.js).\n\nAdding 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.\n\nWith libp2p configured you can retrieve blocks from remote peers, and those peers can retrieve blocks from you.\n\n#### libp2p\n\n[libp2p][] is the networking layer that IPFS works on top of.  It is a modular system, comprising of transports, connection encrypters, stream multiplexers, etc.\n\n```js\nimport { createLibp2p } from 'libp2p'\nimport { identifyService } from 'libp2p/identify'\nimport { noise } from '@chainsafe/libp2p-noise'\nimport { yamux } from '@chainsafe/libp2p-yamux'\nimport { webSockets } from '@libp2p/websockets'\nimport { bootstrap } from '@libp2p/bootstrap'\nimport { MemoryDatastore } from 'datastore-core'\n\nconst datastore = new MemoryDatastore()\n\nconst libp2p = await createLibp2p({\n  datastore,\n  transports: [\n    webSockets()\n  ],\n  connectionEncrypters: [\n    noise()\n  ],\n  streamMuxers: [\n    yamux()\n  ],\n  peerDiscovery: [\n    bootstrap({\n      list: [\n        \"/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN\",\n        \"/dnsaddr/bootstrap.libp2p.io/p2p/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa\",\n        \"/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb\",\n        \"/dnsaddr/bootstrap.libp2p.io/p2p/QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt\"\n      ]\n    })\n  ],\n  services: {\n    identify: identifyService()\n  }\n})\n```\n\n### 401 - Providing\n\nThe final example is [401-providing.js](./401-providing.js).\n\nThis example shows:\n\n- How to run garbage collection,\n- Pin blocks to prevent them from being garbage collected\n- Add metadata to pins\n- Provide it to the DHT so that other nodes can find and retrieve it.\n\nTo run it, use the following command:\n\n```console\n\u003e npm run 401-providing\n```\n\n\n\n### Putting it all together\n\nSince 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!\n\n```bash\n\u003e npm run 301-networking\n\nAdded file: bafkreife2klsil6kaxqhvmhgldpsvk5yutzm4i5bgjoq6fydefwtihnesa\n# Copy that hash and load it on the gateway, here is a prefilled url:\n# https://ipfs.io/ipfs/bafkreife2klsil6kaxqhvmhgldpsvk5yutzm4i5bgjoq6fydefwtihnesa\n```\n\nThat's it! You just added and retrieved a file from IPFS!\n\n_For more examples, please refer to the [Documentation](#documentation)_\n\n## Documentation\n\n- [IPFS Primer](https://dweb-primer.ipfs.io/)\n- [IPFS Docs](https://docs.ipfs.io/)\n- [Tutorials](https://proto.school)\n- [More examples](https://github.com/ipfs-examples/helia-examples)\n- [API - Helia](https://ipfs.github.io/helia/modules/helia.html)\n- [API - @helia/unixfs](https://ipfs.github.io/helia-unixfs/modules/helia.html)\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\n1. Fork the IPFS Project\n2. Create your Feature Branch (`git checkout -b feature/amazing-feature`)\n3. Commit your Changes (`git commit -a -m 'feat: add some amazing feature'`)\n4. Push to the Branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Want to hack on IPFS?\n\n[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)\n\nThe IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out:\n\nRead 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).\n\n- **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\n- **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\n- **Perform code reviews** More eyes will help\n  a. speed the project along\n  b. ensure quality, and\n  c. reduce possible future bugs\n- **Add tests**. There can never be enough tests\n\n[cid]: https://docs.ipfs.tech/concepts/content-addressing  \"Content Identifier\"\n[Uint8Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array\n[libp2p]: https://libp2p.io\n[IndexedDB]: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API\n[S3]: https://aws.amazon.com/s3/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs-examples%2Fhelia-101","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs-examples%2Fhelia-101","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs-examples%2Fhelia-101/lists"}