You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/BROWSERS.md
+14-12
Original file line number
Diff line number
Diff line change
@@ -8,28 +8,29 @@
8
8
-[Code Examples](#code-examples)
9
9
10
10
JS IPFS is the implementation of IPFS protocol in JavaScript. It can run on any
11
-
evergreen browser, inside a service or web worker, browser extensions, Electron and in Node.js.
11
+
evergreen browser, inside a service or web worker, browser extensions, Electron, and in Node.js.
12
12
13
13
**This document provides key information about running JS IPFS in the browser.
14
14
Save time and get familiar with common caveats and limitations of the browser context.**
15
15
16
16
## Limitations of the Browser Context
17
17
18
-
- Transport options are limited to [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) and [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API).
18
+
- Transport options are currently limited to [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) and [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API).
19
19
20
20
This means JS IPFS running in the browser is limited to Web APIs available on a web page.
21
-
There is no access to raw TCP sockets nor lowlevel UDP, only WebSockets and WebRTC.
21
+
There is no access to raw TCP sockets nor low-level UDP, only WebSockets, and WebRTC.
22
22
23
23
- Key [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) require or are restricted by [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) policies.
24
24
25
25
This means JS IPFS needs to run within Secure Context (HTTPS or localhost).
26
-
JS IPFS running on HTTPS website requires Secure WebSockets (TLS) and won't work with unencrypted one.
26
+
JS IPFS running on HTTPS website requires Secure WebSockets (TLS) and won't work with unencrypted ones.
27
27
[Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) not being available at all.
28
28
29
-
-[DHT](https://en.wikipedia.org/wiki/Distributed_hash_table) is not available in JS IPFS yet.
29
+
-JS IPFS comes with limited support for the [DHT](https://docs.ipfs.tech/concepts/dht/) in client mode which delegates content discovery requests to other DHT nodes.
30
30
31
-
[We are working on it](https://github.com/ipfs/js-ipfs/pull/1994). For now, the discovery and connectivity to other peers is achieved with a mix of rendezvous and
32
-
relay servers, delegated peer/content routing and preload servers.
31
+
However, it's worth noting that even though you'll get results from DHT queries, most nodes in the network are not dialable from browsers because they only support TCP and/or QUIC transports.
32
+
33
+
For now, the content discovery and connectivity to other peers are achieved with a mix of DHT client requests, rendezvous and relay servers, delegated peer/content routing, and preload servers.
33
34
34
35
35
36
## Addressing Limitations
@@ -40,23 +41,24 @@ We provide a few additional components useful for running JS IPFS in the browser
40
41
-[libp2p-webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) - incorporates both a transport and a discovery service that is facilitated by the custom rendezvous server available in the repo
41
42
- Instructions on enabling `webrtc-star` in js-ipfs config can be found [here](https://github.com/ipfs/js-ipfs/blob/master/docs/FAQ.md#how-to-enable-webrtc-support-for-js-ipfs-in-the-browser).
42
43
- Make sure to [run your own rendezvous server](https://github.com/libp2p/js-libp2p-webrtc-star#rendezvous-server-aka-signalling-server).
43
-
-[libp2p-webrtc-direct](https://github.com/libp2p/js-libp2p-webrtc-direct) - a WebRTC transport that doesn't require the set up a signalling server.
44
+
-[libp2p-webrtc-direct](https://github.com/libp2p/js-libp2p-webrtc-direct) - a WebRTC transport that doesn't require the set up a signaling server.
44
45
- Caveat: you can only establish Browser to Node.js and Node.js to Node.js connections.
45
46
46
-
**Note:** those are semi-centralized solutions. We are working towards replacing `*-star` with and ambient relays and [libp2p-rendezvous](https://github.com/libp2p/js-libp2p-rendezvous). Details and progress can be found [here](https://github.com/libp2p/js-libp2p/issues/385).
47
+
**Note:** those are semi-centralized solutions. We are working towards replacing `*-star` with ambient relays and [libp2p-rendezvous](https://github.com/libp2p/js-libp2p-rendezvous). Details and progress can be found [here](https://github.com/libp2p/js-libp2p/issues/385).
47
48
48
49
You can find detailed information about running js-ipfs [here](https://github.com/ipfs/js-ipfs#table-of-contents).
49
50
50
51
## Best Practices
51
52
52
-
- Configure nodes for using self-hosted `*-star` signalling and transport service. When in doubt, use WebSockets ones.
53
+
- Configure nodes for using self-hosted `*-star` signalling and transport service. When in doubt, use WebSockets ones.
53
54
- Run your own instance of `*-star` signalling service.
54
55
The default ones are under high load and should be used only for tests and development.
55
-
- Make sure content added to js-ipfs running in the browser is persisted/cached somewhere on regular IPFS daemon
56
+
- Make sure content added to js-ipfs running in the browser is persisted/cached somewhere on a regular long-running IPFS daemon, e.g. [kubo](https://github.com/ipfs/kubo/)
56
57
- Manually `pin` or preload CIDs of interest with `refs -r` beforehand.
57
58
- Preload content on the fly using [preload](https://github.com/ipfs/js-ipfs/blob/master/docs/MODULE.md#optionspreload) feature and/or
- Avoid public instances in production environment. Make sure preload and delegate nodes used in config are self-hosted and under your control (expose a subset of go-ipfs APIs via reverse proxy such as Nginx).
60
+
- Avoid public instances in production environments. Make sure preload and delegate nodes used in config are self-hosted and under your control (expose a subset of [kubo](https://github.com/ipfs/kubo/) (formerly go-ipfs) APIs via reverse proxy such as Nginx).
61
+
- If your main goal is to provide content and files to the IPFS network from a browser and you would like to avoid running infrastructure, consider using a pinning service like [Web3.storage](https://web3.storage/).
Copy file name to clipboardexpand all lines: docs/MODULE.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -102,7 +102,7 @@ Instead of a boolean, you may provide an object with custom initialization optio
102
102
-`privateKey` (string/PeerId) A pre-generated private key to use. Can be either a base64 string or a [PeerId](https://github.com/libp2p/js-peer-id) instance. **NOTE: This overrides `bits`.**
Copy file name to clipboardexpand all lines: docs/core-api/README.md
+3-3
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,11 @@
1
1
# IPFS Core API
2
2
3
-
This directory contains the description of the core JS IPFS API. In order to be considered "valid", a JS IPFS core implementation must expose the API described here.
3
+
This directory contains the description of the core JS IPFS API. In order to be considered "valid", a JS IPFS core implementation must expose the API described here.
4
4
This abstraction allows for different implementations including:
5
5
1. Full JavaScript native implementation
6
6
2. Delgate implementation that invokes another IPFS implementation (e.g., Kubo)
7
7
8
-
You can use this loose spec as documentation for consuming the core APIs.
8
+
You can use this loose spec as documentation for consuming the core APIs.
9
9
10
10
It is broken up into the following sections:
11
11
@@ -19,7 +19,7 @@ It is broken up into the following sections:
19
19
*[KEY.md](KEY.md)
20
20
*[MISCELLANEOUS.md](MISCELLANEOUS.md)
21
21
*[NAME.md](NAME.md)
22
-
*[OBJECT.md](OBJECT.md)
22
+
*[OBJECT.md](OBJECT.md) ([deprecated](https://github.com/ipfs/go-ipfs/issues/7936), use the [DAG API](DAG.md) instead)
Copy file name to clipboardexpand all lines: docs/upgrading/v0.62-v0.63.md
+46-3
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,13 @@
1
1
<!--Specify versions for migration below-->
2
2
# Migrating to ipfs@0.63 and ipfs-core@0.15 <!-- omit in toc -->
3
3
4
-
> A migration guide for refactoring your application code from `ipfs@0.63.x` to `ipfs@0.64.x`
4
+
> A migration guide for refactoring your application code from `ipfs@0.62.x` to `ipfs@0.63.x`
5
5
6
6
## Table of Contents <!-- omit in toc -->
7
7
8
8
-[ESM](#esm)
9
-
-[libp2p@0.37.x](#libp2p037x)
9
+
-[TypeScript and ESM](#typescript-and-esm)
10
+
-[`libp2p@0.37.x`](#libp2p037x)
10
11
-[PeerIds](#peerids)
11
12
-[multiaddrs](#multiaddrs)
12
13
@@ -34,11 +35,53 @@ async function loadIpfs () {
34
35
}
35
36
```
36
37
38
+
### TypeScript and ESM
39
+
40
+
When authoring typescript it can often look like you are writing ESM:
41
+
42
+
```ts
43
+
import { create } from'ipfs-core'
44
+
45
+
create()
46
+
```
47
+
48
+
When this is transpiled to JavaScript the default settings will emit CJS which will fail at runtime:
49
+
50
+
```js
51
+
"use strict";
52
+
exports.__esModule=true;
53
+
var ipfs_core_1 =require("ipfs-core");
54
+
(0, ipfs_core_1.create)();
55
+
```
56
+
57
+
You may also see errors about private identifiers:
58
+
59
+
```console
60
+
node_modules/@libp2p/interfaces/dist/src/events.d.ts:19:5 - error TS18028: Private identifiers are only available when targeting ECMAScript 2015 and higher.
61
+
62
+
19 #private;
63
+
~~~~~~~~
64
+
```
65
+
66
+
To build correctly with ESM as a target, update your `tsconfig.json` to include the following:
67
+
68
+
```js
69
+
{
70
+
"module":"es2020", // ensures output is ESM
71
+
"target":"es2020", // support modern features like private identifiers
72
+
// other settings
73
+
}
74
+
```
75
+
76
+
They must both be set to `es2020` at least, more recent versions will also work.
77
+
78
+
If in doubt, examine the JavaScript files `tsc` emits and ensure that any `ipfs` modules are being loaded with `import` and not `require`.
79
+
37
80
## `libp2p@0.37.x`
38
81
39
82
`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.
40
83
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.
84
+
Please see the [libp2p 0.37.x upgrade guide](https://github.com/libp2p/js-libp2p/blob/master/doc/migrations/v0.36-v0.37.md) for how this may affect your application.
# Migrating to ipfs@0.64 and ipfs-core@0.16 <!-- omit in toc -->
3
+
4
+
> A migration guide for refactoring your application code from `ipfs@0.63.x` to `ipfs@0.64.x`
5
+
6
+
## Table of Contents <!-- omit in toc -->
7
+
8
+
-[libp2p](#libp2p)
9
+
10
+
## libp2p
11
+
12
+
The upgrade to `ipfs@0.64.x` incorporates an update to `libp2p@0.38.x` but no API changes.
13
+
14
+
If your application uses only the default libp2p config there is nothing to do.
15
+
16
+
If you supply a custom `libp2p` instance to the `ipfs` factory function you should consult the [`libp2p@0.38.x` upgrade guide](https://github.com/libp2p/js-libp2p/blob/master/doc/migrations/v0.37-v0.38.md) for any changes you need to make.
0 commit comments