This repository has been archived by the owner on Feb 12, 2024. It is now read-only.
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add upgrade guide for ESM release (#4098)
Adds upgrade guide and updates core-api docs with API changes
- Loading branch information
1 parent
74aee8b
commit 7165bf7
Showing
16 changed files
with
157 additions
and
33 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| <!--Specify versions for migration below--> | ||
| # Migrating to ipfs@0.63 and ipfs-core@0.15 <!-- omit in toc --> | ||
|
|
||
| > A migration guide for refactoring your application code from `ipfs@0.63.x` to `ipfs@0.64.x` | ||
| ## Table of Contents <!-- omit in toc --> | ||
|
|
||
| - [ESM](#esm) | ||
| - [libp2p@0.37.x](#libp2p037x) | ||
| - [PeerIds](#peerids) | ||
| - [multiaddrs](#multiaddrs) | ||
|
|
||
| ## ESM | ||
|
|
||
| The biggest change to `ipfs@0.63.x` is that the module is now [ESM-only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). | ||
|
|
||
| ESM is the module system for JavaScript, it allows us to structure our code in separate files without polluting a global namespace. | ||
|
|
||
| Other systems have tried to fill this gap, notably CommonJS, AMD, RequireJS and others, but ESM is [the official standard format](https://tc39.es/ecma262/#sec-modules) to package JavaScript code for reuse. | ||
|
|
||
| If you see errors similar to `Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in node_modules/ipfs/package.json` you are likely trying to load ESM code from a CJS environment via `require`. This is not possible, instead it must be loaded using `import`. | ||
|
|
||
| If your application is not yet ESM or you are not ready to port it to ESM, you can use the [dynamic `import` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) to load `ipfs` at runtime from a CJS module: | ||
|
|
||
| ```js | ||
| async function loadIpfs () { | ||
| const { create } = await import('ipfs-core') | ||
|
|
||
| const node = await create({ | ||
| // ... config here | ||
| }) | ||
|
|
||
| return node | ||
| } | ||
| ``` | ||
|
|
||
| ## libp2p@0.37.x | ||
|
|
||
| `ipfs@0.63.x` upgrades to `libp2p@0.37.x`. This is a significant refactor that ports the entire stack to TypeScript and publishes all modules as ESM-only code. | ||
|
|
||
| Please see the [libp2p 0.37.x` upgrade guide](https://github.com/libp2p/js-libp2p/blob/master/doc/migrations/v0.36-v.037.md) for how this may affect your application. | ||
|
|
||
| ## PeerIds | ||
|
|
||
| The core `libp2p` module and all supporting modules have now been ported to TypeScript in a complete ground-up rewrite. We took this opportunity to solve a few long-standing problems with some of the data types, particularly in how they relate to use in the browser. | ||
|
|
||
| One problem we have solved is that the `PeerId` objects used internally expose some cryptographic operations that require heavyweight libraries to be included in browser bundles due to there being no native web-crypto implementation of the algorithms used in those operations. | ||
|
|
||
| With `libp2p@0.37.x` those operations have been encapsulated in the `@libp2p/crypto` module which means `PeerId` objects become a lot more lightweight and can now be exposed/accepted as core-api types so we can use them to differentiate between different data types instead of having to treat everything as strings. | ||
|
|
||
| The affected methods are: | ||
|
|
||
| ```js | ||
| // `peerId` must now be a `PeerId`, previously it was a `string` | ||
| ipfs.bitswap.wantlistForPeer(peerId, options) | ||
|
|
||
| // Bitswp peers are now returned as `PeerId[]` instead of `string[]` | ||
| ipfs.bitswap.stat(options) | ||
|
|
||
| // `peerId` must now be a `PeerId` | ||
| ipfs.dht.findPeer(peerId, options) | ||
|
|
||
| // `peerIdOrCid` must now be a `PeerId` or a `CID`, previously it was a `string` or a `CID` | ||
| ipfs.dht.query(peerIdOrCid, options) | ||
|
|
||
| // the following DHT events have their `from` field as `PeerId`, previously it was a `string` | ||
| PeerResponseEvent | ||
| ValueEvent | ||
| DialingPeerEvent | ||
|
|
||
| // the following DHT events have had their `from` property removed because it is not exposed by go-ipfs so causes incompatibilities | ||
| QueryErrorEvent | ||
| FinalPeerEvent | ||
|
|
||
| // the folloing DHT events have had their `to` property removed because it is not exposed by go-ipfs so causes incompatibilities | ||
| SendingQueryEvent | ||
|
|
||
| // the `providers` and `closer` properties (where applicable) of the following events have the `peerId` property specified as a `PeerId`, previously it was a `string` | ||
| PeerResponseEvent | ||
| PeerResponseEvent | ||
|
|
||
| // `value` can now be a string or a `PeerId`. If a string is passed it will be interpreted as a DNS address. | ||
| ipfs.name.resolve(value, options) | ||
|
|
||
| // The return type of this method is now `Promise<PeerId[]>`, previously it was a `Promise<string[]>` | ||
| ipfs.pubsub.peers(topic, options) | ||
|
|
||
| // `peerId` must now be a `PeerId`, previously it was a `string` | ||
| ipfs.ping(peerId, options) | ||
|
|
||
| // the `peer` property of `options` must now be a `PeerId` when specified, previously it was a `string` | ||
| ipfs.stats.bw(options) | ||
|
|
||
| // `multiaddrOrPeerId` must be a `Multiaddr` or `PeerId`, previously it was a `Multiaddr` or `string` | ||
| ipfs.swarm.connect(multiaddrOrPeerId, options) | ||
|
|
||
| // `multiaddrOrPeerId` must be a `Multiaddr` or `PeerId`, previously it was a `Multiaddr` or `string` | ||
| ipfs.swarm.disconnect(multiaddrOrPeerId, options) | ||
| ``` | ||
|
|
||
| `PeerId`s can be created from strings using the `@libp2p/peer-id` module: | ||
|
|
||
| ```js | ||
| import { peerIdFromString } from '@libp2p/peer-id' | ||
|
|
||
| const peerId = peerIdFromString('Qmfoo') | ||
| ``` | ||
|
|
||
| They can also be created using the `@libp2p/peer-id-factory` module: | ||
|
|
||
| ```js | ||
| import { createEd25519PeerId } from '@libp2p/peer-id-factory' | ||
|
|
||
| const peerId = await createEd25519PeerId() | ||
| ``` | ||
|
|
||
| ## multiaddrs | ||
|
|
||
| The `multiaddr` module has been ported to Typescript and is now published as ESM-only. | ||
|
|
||
| It has been renamed to `@multiformats/multiaddr` so please update your dependencies and replace usage in your code. | ||
|
|
||
| The API otherwise is compatible. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters