Info for js-ipfs users affected by the deprecation

About

As shared back in 202310 in https://blog.ipfs.tech/state-of-ipfs-in-js/, the current maintainers of js-ipfs (Protocol Labs’ EngRes (Engineering & Research) group), have been active in developing Helia. Now that v1 of Helia has been released, the intent is to signpost from js-ipfs to Helia and ultimately archive the repo. The specific steps and timeline for this are below. This issue was originally created as a placeholder to start adding notes as things come up and cross-linking issues, and now it serves as the deprecation project tracker.

FAQ

Scope: what is being deprecated?

js-ipfs and all the modules that live in this monorepo.

Key dependencies of js-ipfs like js-libp2p and js-bitswap ARE NOT being deprecated - they are critical dependencies of Helia as well.

Why is js-ipfs being deprecated?

The current maintainers don't have bandwidth to maintain Helia and js-ipfs. Helis takes the lessons learned from the years developing and supporting js-ipfs and we believe provides a better user and maintainer experience.

More details are covered in:

• Hello Helia talk at IPFS Thing 2023
• The State of IPFS in JS 202210 blog entry
• Helia Manifest

How do I migrate to Helia from js-ipfs?

We have created a migration guide at https://github.com/ipfs/helia/wiki/Migrating-from-js-IPFS . If you have any questions or issues with it, please open a Helia issue.

How do I learn more about Helia?

Please see the README and other docs linked from the Helia repo. helia-examples are also a great way to see Helia in action.

How do I stay updated on this deprecation?

This is the deprecation tracking issue. As items are completed, we'll update the task lists here. We'll also post major updates as comments in the issue.

What is the expected timeline of this deprecation?

See the "Expected Completed Dates" (ECD) for the various task lists or tasks below. We are generally aiming to complete the bulk of this by mid-June. "Disruption" will start happening ~2023-05-24. Per below, we'll leave a time for users to reopen any issues or PRs that they feel were closed in error.

What if I have more comments on a closed issue or PR?

Per above, we are going to be archiving this repo which will prevent further updates to issues and PRs. That said, before then we'll give a week for someone to reopen any issue or PR that we close in case they have followup questions or concerns. We'll engage with any of these reopened issues before archiving the repo. We expect this will be during or shortly after this one-week response window, but this will be dependent on how many issues get reopened and how long it takes us to process them.

Can I volunteer to take over the maintainership of js-ipfs?

If someone doesn't want to move over to Helia and instead take over maintaining js-ipfs, they are welcome to fork this repo and notify in this issue. @ipfs/helia-dev can update the ipfs/js-ipfs repo readme to point to your fork. Note that npm modules will stay deprecated to prevent any security exposure for users.

The js-ipfs repo has a treasure trove of history and discussion about js-ipfs and IPFS in JS in general. Are there any critical takeaways from the deprecation process?

While not exhaustive, below are some issues that were particularly rich as we went through and closed the 300+ open issues:

• Let's understand who is using js-ipfs! #2359
• A viable alternative to go-ipfs? #1563
• Achieving Connectivity Magic #1459
• Embedded JS-IPFS in Brave (experiment) ipfs-companion#716
• Notes on building and manipulating large IPLD graphs in JavaScript and LevelDB. #1416

Info for js-ipfs maintainers executing this deprecation

Deprecation Tasks

Below are the set of tasks for completing this deprecation. They are broken into different lists.

• Preparation tasks are items that maintainers are doing to ensure our ducks are in a row before we start disrupting users with this change.
• Disruption tasks cause messages to be sent to users, issues to be closed, modules archived, etc.