Examples repo/infra setup

[achingbrain]

js-ipfs has a comprehensive example suite at https://github.com/ipfs-examples/js-ipfs-examples - it would be amazing for helia to have something similar.

The example suite is a monorepo with all examples in the examples directory. Each example is a self-contained module that showcases one feature of js-ipfs or how to integrate it with a build tool, and they all contain tests to prevent regressions.

Each example is copied into it's own repo in the ipfs-examples org by the fork & go github action to aid discoverability yet make the maintenance of these examples manageable.

Syncing changes

Changes to the monorepo are pulled into the split-out repos, any changes that have been made to the split-out repos are discarded. This is done by a sync job copied from the fork & go template.

An improvement for helia would be to switch this around and have the monorepo push changes out to the split-out repos, the reason being the sync job runs on a timer and GitHub disables the timer if no changes are observed for a month or so, which means a maintainer has to manually go through and re-enable the timer for every split-out repo periodically - see ipfs-examples/js-ipfs-examples#44

Where to start

Create a repo in the ipfs-examples org called helia-examples.

Start with just one example, perhaps bundling with esbuild (easy since aegir already builds helia with esbuild for browser tests so there shouldn't be any extra config required) - port the example, the docs and the tests.

The sync job should be run from the helia-examples repo instead of from the split-out repos.

Prequisites

After #17 is merged helia should be installable with npm i helia@next. An automated PR will also be created that sets up a gated release of v1 of helia - when that is merged dependabot should take care of upgrading all the example deps.

[achingbrain]

This is taking shape over at https://github.com/ipfs-examples/helia-examples

So far there are examples for:

• helia-101
• bundling with webpack
• Use from CJS modules 🆕

There are instructions on how to add new examples in the readme.

It's set up to push any changes from the monorepo to the individual example repos, they just need to be create from the example template and given the same name as their folder under examples in the helia-examples monorepo.

There are plenty of other js-ipfs examples that need porting:

• Frontend frameworks (create-react-app, vue, angular)
• Bundlers/frameworks (esbuild, nextjs, lit, vite)
• Functionality (transfer files, pubsub, ipns, dht, etc)

These can largely be ported from the existing js-ipfs examples.

[BigLep]

@achingbrain : this is great. I would like to make it clearer that this is an issue where someone can pick off examples to learn the ball forward and move us forward.

Thoughts on how to achieve this:

1. Maybe we close this issue? We could rename this isuee to "Setup examples template/infra". It seems like we have that.

• The one area I'm wondering about is testing. Is there a way to automatically have Helia run against all tests unless someone explicitly opts out? (I want to minimize the effort for getting tests to run.).
• Lets also make sure helia-examples reports on the test coverage and the test results with a badge.

2. Have a specific checklist of open issues to port. That way folks can see how many are done and how many remain. Ideally put these in priority order. That should either be at the top of this issue (or in the new issue)

[BigLep]

@achingbrain : please list what's remaining for closing this issue out.

For tracking the porting of examples over, I created #43

[achingbrain]

Nothing I think, #43 covers it.