helia-examples

helia-examples copied to clipboard

A collection of Helia examples

Explore the docs · View Demo · Report Bug · Request Feature/Example

Table of Contents

• Table of Contents
• About The Project
• Getting Started
  • Examples
    • Basics
    • Frameworks
    • Bundlers
    • Testing
    • Other tooling
  • Prerequisites
• IPFS Tutorials at ProtoSchool
• Documentation
• Contributing
  • How to add a new example
    • Examples must
    • Update helia to run tests against the repo
• Want to hack on IPFS?

About The Project

• 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

Getting Started

Examples

Feel free to jump directly into the examples, however going through the following sections will help build context and background knowledge.

Basics

• Helia-101: Spawn a Helia node, add a file and cat the file
• Helia CommonJS: Just like Helia-101, but with CommonJS instead of ESM
• Helia via CDNs: A simple proof-of-concept to distributing and using Helia using <script> tags
• Creating a CAR file with Helia: An example showing how to create a car file with Helia. CAR files are useful for making Filecoin deals.

Frameworks

• Helia with Electron: Create an Electron app with Helia
• Helia with Next.js: Create a Next.js app with Helia
• Helia with NestJS: Create a NestJS app with Helia
• Helia with Vue: Create a vue app with Helia
• Helia with Vite: Create a react+vite app with Helia

Bundlers

• Helia with esbuild: Bundle Helia with esbuild
• Helia with Webpack: Bundle Helia with webpack

Testing

• Helia with Jest: Test Helia with Jest
• Helia with Jest and TypeScript: Test Helia with Jest and TypeScript

Other tooling

• Helia with TypeScript: Building Helia with TypeScript
• Helia with ts-node: Run Helia using ts-node

Prerequisites

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.

IPFS Tutorials at ProtoSchool

Explore ProtoSchool's IPFS tutorials for interactive Helia coding challenges, deep dives into DWeb concepts like content addressing, and more.

Documentation

• IPFS Primer
• IPFS Docs
• Tutorials
• More examples
• API - Helia
• API - @helia/unixfs

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 Examples Project (https://github.com/ipfs-examples/helia-examples)
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

How to add a new example

1. Decide on a pithy folder name for your example, it should start with helia- and ideally be one or two words that describe what it's about - e.g. helia-transfer-files
2. Create a folder in this repo under examples, eg. ./examples/helia-transfer-files
3. Add the files and tests that make up the example
4. Add the folder name to the project-list lists in the examples and push-changes jobs in this repositories ./github/ci.yml
5. Open a PR with your changes
6. :warning: Maintainer required: Use the helia-example-fork-go-template to create a new repo in the ipfs-examples org for the new example to live in.
   • Give it the same name as the example folder, e.g. https://github.com/ipfs-examples/helia-transfer-files
   • Disable wikis, projects, and issues
7. :warning: Maintainer required: Review the example
   1. Does it show the example clearly and concisely?
   2. Does it have tests?
   3. Does it contain the .github folder?
   4. Has it been added to the project-list lists in the examples and push-changes jobs in the ./github/ci.yml file of this repo?
8. :warning: Maintainer required: Merge the example, after a successful build all files should be copied into the newly created repo.

Examples must

• Live inside the /examples/ folder
• Have tests and should make use of test-util-ipfs-example library
• Implement the following scripts:
• clean: used to clean all the unnecessary code (e.g.: files generated by bundlers and package managers)
• build: used to build the example
• start: used to start the example
• test: used to test the example
• The README.md must have (see example inside example-template):
  • Link to Codesandbox.com for one-click running demonstration
  • References for documentation/tutorials used to build the example
  • Optional: Screenshots, gifs, etc... under img/ folder
• Update the CI to run the tests of the new example as standalone
  • Edit github/workflows/ci.yml
  • Add the test name to project under matrix

Update helia to run tests against the repo

Open a PR to the ipfs/helia project that edits the .github/workflows/examples.yml in order to make sure a Helia release does not break your new example.

Search .github/workflows/test.yml for the test-examples section and add a block at the end of the example matrix key similar to:

- name: my super fun new example
  repo: https://github.com/ipfs-examples/helia-my-super-fun-new-example.git
  deps: helia@$PWD/packages/helia/dist

The value of the deps key will vary depending on which modules from Helia your example uses. Above we override the helia module, but your example may different deps.

Please see the existing setup in .github/workflows/test.yml for how to ensure you are overriding the correct modules.

Want to hack on IPFS?

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