Skip to content
This repository has been archived by the owner on Jan 12, 2024. It is now read-only.

ipfs-examples/js-ipfs-examples

Repository files navigation

IPFS in JavaScript logo

JS IPFS Examples

Collection of js-ipfs examples


Explore the docs · Report Bug · Request Feature/Example

Table of Contents

About The Project

Getting Started

Prerequisites

Make sure you have installed all of the following prerequisites on your development machine:

Installation

  1. Install yarn globally (needed to resolve dependencies correctly when working in a monorepo)
    npm install -g yarn
  2. Install NPM packages
    yarn install
  3. Run all the examples
    yarn run test

Structure

This project is broken into 2 modules, their purposes are:

IPFS Tutorials at ProtoSchool

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

Documentation

ipfs or ipfs-core?

The JavaScript implementation of IPFS is available as two packages, ipfs-core and ipfs.

ipfs-core contains the core api and is intended to be used to run an IPFS node as part of your application without the need to start external processes or manage API ports and servers.

ipfs is built on ipfs-core but also includes the CLI, an HTTP RPC API server and other tools to run ipfs as a background process so is a larger install with more dependencies.

If you are writing an application that needs to access the IPFS network, use ipfs-core. If you wish to use js-IPFS in a terminal window or run it as a server for use by multiple otherwise unrelated processes, use ipfs.

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/js-ipfs-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

Guidelines

  • Follow the example-template

    • This repository serves as template to create new examples to guarantee consistency between examples. It contains all the necessary files to create a new example
  • Follow the example-template-fork-&-go

    • This repository serves as template to be used as a reference of how to implement the CI in order to sync the example with a standalone repo (correspondent to each example)
  • Examples must:

    • Live inside the /examples/ folder
    • Have tests and should make use of test-util-ipfs-example library
      • If possible use playwright as test framework
    • 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
  • README 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
  • Extend the test-util-ipfs-example library if needed to reuse code in other examples

Steps to follow after adding a new example

Create a repo

Repo Details

  • Disable Releases/Environments/Packages

Repo Settings

  • Follow the instruction inside the README

Update js-ipfs to run tests against the repo

Open a PR to the ipfs/js-ipfs project that edits the .github/workflows/test.yml in order to make sure a js-ipfs 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/js-ipfs-my-super-fun-new-example.git
  deps: ipfs-core@$PWD/packages/ipfs-core/dist,ipfs-http-client@$PWD/packages/ipfs-http-client/dist

The value of the deps key will vary depending on which modules from js-ipfs your example uses. Above we override the ipfs-core and ipfs-http-client modules, 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 IPFS 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.
  • Join the Weekly Core Implementations Call it's where everyone discusses what's going on with IPFS and what's next