|
| 1 | +<!--Specify versions for migration below--> |
| 2 | +# Migrating to [email protected] and [email protected] <!-- omit in toc --> |
| 3 | + |
| 4 | +> A migration guide for refactoring your application code from `[email protected]` to `[email protected]` |
| 5 | +
|
| 6 | +## Table of Contents <!-- omit in toc --> |
| 7 | + |
| 8 | +- [ESM](#esm) |
| 9 | +- [[email protected]](#libp2p037x) |
| 10 | +- [PeerIds](#peerids) |
| 11 | +- [multiaddrs](#multiaddrs) |
| 12 | + |
| 13 | +## ESM |
| 14 | + |
| 15 | +The biggest change to `[email protected]` is that the module is now [ESM-only ](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). |
| 16 | + |
| 17 | +ESM is the module system for JavaScript, it allows us to structure our code in separate files without polluting a global namespace. |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +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`. |
| 22 | + |
| 23 | +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: |
| 24 | + |
| 25 | +```js |
| 26 | +async function loadIpfs () { |
| 27 | + const { create } = await import('ipfs-core') |
| 28 | + |
| 29 | + const node = await create({ |
| 30 | + // ... config here |
| 31 | + }) |
| 32 | + |
| 33 | + return node |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | +`[email protected]` upgrades to `[email protected]`. This is a significant refactor that ports the entire stack to TypeScript and publishes all modules as ESM-only code. |
| 40 | + |
| 41 | +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. |
| 42 | + |
| 43 | +## PeerIds |
| 44 | + |
| 45 | +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. |
| 46 | + |
| 47 | +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. |
| 48 | + |
| 49 | +With `[email protected]` 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. |
| 50 | + |
| 51 | +The affected methods are: |
| 52 | + |
| 53 | +```js |
| 54 | +// `peerId` must now be a `PeerId`, previously it was a `string` |
| 55 | +ipfs.bitswap.wantlistForPeer(peerId, options) |
| 56 | + |
| 57 | +// Bitswp peers are now returned as `PeerId[]` instead of `string[]` |
| 58 | +ipfs.bitswap.stat(options) |
| 59 | + |
| 60 | +// `peerId` must now be a `PeerId` |
| 61 | +ipfs.dht.findPeer(peerId, options) |
| 62 | + |
| 63 | +// `peerIdOrCid` must now be a `PeerId` or a `CID`, previously it was a `string` or a `CID` |
| 64 | +ipfs.dht.query(peerIdOrCid, options) |
| 65 | + |
| 66 | +// the following DHT events have their `from` field as `PeerId`, previously it was a `string` |
| 67 | +PeerResponseEvent |
| 68 | +ValueEvent |
| 69 | +DialingPeerEvent |
| 70 | + |
| 71 | +// the following DHT events have had their `from` property removed because it is not exposed by go-ipfs so causes incompatibilities |
| 72 | +QueryErrorEvent |
| 73 | +FinalPeerEvent |
| 74 | + |
| 75 | +// the folloing DHT events have had their `to` property removed because it is not exposed by go-ipfs so causes incompatibilities |
| 76 | +SendingQueryEvent |
| 77 | + |
| 78 | +// the `providers` and `closer` properties (where applicable) of the following events have the `peerId` property specified as a `PeerId`, previously it was a `string` |
| 79 | +PeerResponseEvent |
| 80 | +PeerResponseEvent |
| 81 | + |
| 82 | +// `value` can now be a string or a `PeerId`. If a string is passed it will be interpreted as a DNS address. |
| 83 | +ipfs.name.resolve(value, options) |
| 84 | + |
| 85 | +// The return type of this method is now `Promise<PeerId[]>`, previously it was a `Promise<string[]>` |
| 86 | +ipfs.pubsub.peers(topic, options) |
| 87 | + |
| 88 | +// `peerId` must now be a `PeerId`, previously it was a `string` |
| 89 | +ipfs.ping(peerId, options) |
| 90 | + |
| 91 | +// the `peer` property of `options` must now be a `PeerId` when specified, previously it was a `string` |
| 92 | +ipfs.stats.bw(options) |
| 93 | + |
| 94 | +// `multiaddrOrPeerId` must be a `Multiaddr` or `PeerId`, previously it was a `Multiaddr` or `string` |
| 95 | +ipfs.swarm.connect(multiaddrOrPeerId, options) |
| 96 | + |
| 97 | +// `multiaddrOrPeerId` must be a `Multiaddr` or `PeerId`, previously it was a `Multiaddr` or `string` |
| 98 | +ipfs.swarm.disconnect(multiaddrOrPeerId, options) |
| 99 | +``` |
| 100 | + |
| 101 | +`PeerId`s can be created from strings using the `@libp2p/peer-id` module: |
| 102 | + |
| 103 | +```js |
| 104 | +import { peerIdFromString } from '@libp2p/peer-id' |
| 105 | + |
| 106 | +const peerId = peerIdFromString('Qmfoo') |
| 107 | +``` |
| 108 | + |
| 109 | +They can also be created using the `@libp2p/peer-id-factory` module: |
| 110 | + |
| 111 | +```js |
| 112 | +import { createEd25519PeerId } from '@libp2p/peer-id-factory' |
| 113 | + |
| 114 | +const peerId = await createEd25519PeerId() |
| 115 | +``` |
| 116 | + |
| 117 | +## multiaddrs |
| 118 | + |
| 119 | +The `multiaddr` module has been ported to Typescript and is now published as ESM-only. |
| 120 | + |
| 121 | +It has been renamed to `@multiformats/multiaddr` so please update your dependencies and replace usage in your code. |
| 122 | + |
| 123 | +The API otherwise is compatible. |
| 124 | + |
0 commit comments