From 6bf176df789d9f5253f222b5dbafef041499488a Mon Sep 17 00:00:00 2001 From: Oliverio Sousa <47525443+oliveriosousa@users.noreply.github.com> Date: Tue, 17 Aug 2021 22:28:49 +0100 Subject: [PATCH] fix: update docs linking to new repo --- README.md | 8 +-- docs/IPLD.md | 8 ++- docs/MODULE.md | 94 ++++++++++++++------------- package.json | 6 +- packages/ipfs-core/src/types.d.ts | 4 +- packages/ipfs-http-client/README.md | 16 ++--- scripts/update-example-deps.js | 98 ----------------------------- 7 files changed, 72 insertions(+), 162 deletions(-) delete mode 100644 scripts/update-example-deps.js diff --git a/README.md b/README.md index 3822b55ba2..716536eb81 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ We've come a long way, but this project is still in Alpha, lots of development i ## Getting started * Read the [docs](https://github.com/ipfs/js-ipfs/tree/master/docs) -* Look into the [examples](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser +* Look into the [examples](https://github.com/ipfs-examples/js-ipfs-examples/tree/master) to learn how to spawn an IPFS node in Node.js and in the Browser * Consult the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node * Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it * Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs @@ -98,7 +98,7 @@ console.info(cid) * [Concepts](https://docs.ipfs.io/concepts/) * [Config](./docs/CONFIG.md) * [Core API](./docs/core-api) -* [Examples](./examples) +* [Examples](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples) * [Development](./docs/DEVELOPMENT.md) ## Structure @@ -113,7 +113,7 @@ This project is broken into several modules, their purposes are: * [`/packages/ipfs-core-utils`](./packages/ipfs-core-utils) Helpers and utilities common to core and the HTTP RPC API client * [`/packages/ipfs-daemon`](./packages/ipfs-daemon) Run js-IPFS as a background daemon * [`/packages/ipfs-grpc-client`](./packages/ipfs-grpc-client) A gRPC client for js-IPFS -* [`/packages/ipfs-grpc-protocol`](./packages/ipfs-grpc-protocol]) Shared module between the gRPC client and server +* [`/packages/ipfs-grpc-protocol`](./packages/ipfs-grpc-protocol) Shared module between the gRPC client and server * [`/packages/ipfs-grpc-server`](./packages/ipfs-grpc-server) A gRPC-over-websockets server for js-IPFS * [`/packages/ipfs-http-client`](./packages/ipfs-http-client) A client for the RPC-over-HTTP API presented by both js-ipfs and go-ipfs * [`/packages/ipfs-http-gateway`](./packages/ipfs-http-gateway) JS implementation of the [IPFS HTTP Gateway](https://docs.ipfs.io/concepts/ipfs-gateway/) @@ -175,7 +175,7 @@ List of the main packages that make up the IPFS ecosystem. [![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) -The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out: +The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out: Read the [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md) and [JavaScript Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md). diff --git a/docs/IPLD.md b/docs/IPLD.md index 7b262567ef..0398fabf6e 100644 --- a/docs/IPLD.md +++ b/docs/IPLD.md @@ -47,6 +47,7 @@ Additional bases can be configured using the `bases` config property. If your application requires support for extra codecs, you can configure them as follows: 1. Configure the [IPLD layer](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs/docs/MODULE.md#optionsipld) of your IPFS daemon to support the codec. This step is necessary so the node knows how to prepare data received over HTTP to be passed to IPLD for serialization: + ```javascript const ipfs = require('ipfs') @@ -83,7 +84,10 @@ If your application requires support for extra codecs, you can configure them as } } }) + ``` + 2. Configure your IPFS HTTP API Client to support the codec. This is necessary so that the client can send the data to the IPFS node over HTTP: + ```javascript const ipfsHttpClient = require('ipfs-http-client') @@ -125,8 +129,8 @@ If your application requires support for extra codecs, you can configure them as ## Next steps -* See [examples/custom-ipld-formats](https://github.com/ipfs/js-ipfs/tree/master/examples/custom-ipld-formats) for runnable code that demonstrates the above with in-process IPFS nodes, IPFS run as a daemon and also the http client -* Also [examples/traverse-ipld-graphs](https://github.com/ipfs/js-ipfs/tree/master/examples/traverse-ipld-graphs) which uses the [ipld-format-to-blockcodec](https://www.npmjs.com/package/ipld-format-to-blockcodec) module to use older [IPLD format][]s that have not been ported over to the new [BlockCodec][] interface, as well as additional [Multihash Hashers](https://www.npmjs.com/package/multiformats#multihash-hashers). +* See [examples/custom-ipld-formats](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/custom-ipld-formats) for runnable code that demonstrates the above with in-process IPFS nodes, IPFS run as a daemon and also the http client +* Also [examples/traverse-ipld-graphs](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/traverse-ipld-graphs) which uses the [ipld-format-to-blockcodec](https://www.npmjs.com/package/ipld-format-to-blockcodec) module to use older [IPLD format][]s that have not been ported over to the new [BlockCodec][] interface, as well as additional [Multihash Hashers](https://www.npmjs.com/package/multiformats#multihash-hashers). [cid]: https://docs.ipfs.io/concepts/content-addressing/ [blockcodec]: https://www.npmjs.com/package/multiformats#multicodec-encoders--decoders--codecs diff --git a/docs/MODULE.md b/docs/MODULE.md index 7fb4293306..803800449c 100644 --- a/docs/MODULE.md +++ b/docs/MODULE.md @@ -71,9 +71,9 @@ const node = await IPFS.create({ repo: '/var/ipfs/data' }) ### `options.repoAutoMigrate` -| Type | Default | -|------|---------| -| `boolean` | `true` | +| Type | Default | +| --------- | ------- | +| `boolean` | `true` | `js-ipfs` comes bundled with a tool that automatically migrates your IPFS repository when a new version is available. @@ -83,9 +83,9 @@ a case, you should provide a way to trigger migrations manually.** ### `options.init` -| Type | Default | -|------|---------| -| boolean or object | `true` | +| Type | Default | +| ----------------- | ------- | +| boolean or object | `true` | Perform repo initialization steps when creating the IPFS node. @@ -110,24 +110,24 @@ Instead of a boolean, you may provide an object with custom initialization optio ### `options.start` -| Type | Default | -|------|---------| -| `boolean` | `true` | +| Type | Default | +| --------- | ------- | +| `boolean` | `true` | - If `false`, do not automatically start the IPFS node. Instead, you’ll need to manually call [`node.start()`](#nodestart) yourself. +If `false`, do not automatically start the IPFS node. Instead, you’ll need to manually call [`node.start()`](#nodestart) yourself. ### `options.pass` -| Type | Default | -|------|---------| -| string | `null` | +| Type | Default | +| ------ | ------- | +| string | `null` | A passphrase to encrypt/decrypt your keys. ### `options.silent` -| Type | Default | -|------|---------| +| Type | Default | +| ------- | ------- | | Boolean | `false` | Prevents all logging output from the IPFS node. @@ -138,25 +138,25 @@ Prevents all logging output from the IPFS node. |------|---------| | object | `{ enabled: true, hop: { enabled: false, active: false } }` | -Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs/js-ipfs/tree/master/examples/circuit-relaying) to learn more). +Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examplescircuit-relaying) to learn more). - `enabled` (boolean): Enable circuit relay dialer and listener. (Default: `true`) - `hop` (object) - - `enabled` (boolean): Make this node a relay (other nodes can connect *through* it). (Default: `false`) - - `active` (boolean): Make this an *active* relay node. Active relay nodes will attempt to dial a destination peer even if that peer is not yet connected to the relay. (Default: `false`) + - `enabled` (boolean): Make this node a relay (other nodes can connect *through* it). (Default: `false`) + - `active` (boolean): Make this an *active* relay node. Active relay nodes will attempt to dial a destination peer even if that peer is not yet connected to the relay. (Default: `false`) ### `options.offline` -| Type | Default | -|------|---------| +| Type | Default | +| ------- | ------- | | Boolean | `false` | Run ipfs node offline. The node does not connect to the rest of the network but provides a local API. ### `options.preload` -| Type | Default | -|------|---------| +| Type | Default | +| ------ | ------------------------------------- | | object | `{ enabled: true, addresses: [...] }` | Configure remote preload nodes. The remote will preload content added on this node, and also attempt to preload objects requested by this node. @@ -166,8 +166,8 @@ Configure remote preload nodes. The remote will preload content added on this no ### `options.EXPERIMENTAL` -| Type | Default | -|------|---------| +| Type | Default | +| ------ | ---------------------------------------- | | object | `{ ipnsPubsub: false, sharding: false }` | Enable and configure experimental features. @@ -179,23 +179,23 @@ Enable and configure experimental features. | Type | Default | |------|---------| -| object | [`config-nodejs.js`](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs-core/src/runtime/config-nodejs.js) in Node.js, [`config-browser.js`](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs-core/src/runtime/config-browser.js) in browsers | +| object | [`config-nodejs.js`](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs-core/src/runtime/config-nodejs.js) in Node.js, [`config-browser.js`](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs-core/src/runtime/config-browser.js) in browsers | Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. The default config is documented in [the js-ipfs config file docs](./CONFIG.md). ### `options.ipld` - | Type | Default | +| Type | Default | |------|---------| -| object | [`ipld.js`](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs-core/src/runtime/ipld.js) | +| object | [`ipld.js`](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs-core/src/runtime/ipld.js) | - Modify the default IPLD config. This object will be *merged* with the default config; it will not replace it. Check IPLD [docs](https://github.com/ipld/js-ipld#ipld-constructor) for more information on the available options. +Modify the default IPLD config. This object will be *merged* with the default config; it will not replace it. Check IPLD [docs](https://github.com/ipld/js-ipld#ipld-constructor) for more information on the available options. - > Browser config does **NOT** include by default all the IPLD formats. Only `ipld-dag-pb`, `ipld-dag-cbor` and `ipld-raw` are included. +> Browser config does **NOT** include by default all the IPLD formats. Only `ipld-dag-pb`, `ipld-dag-cbor` and `ipld-raw` are included. - To add support for other formats we provide two options, one sync and another async. +To add support for other formats we provide two options, one sync and another async. - Examples for the sync option: +Examples for the sync option:
ESM Environments @@ -209,6 +209,7 @@ const node = await IPFS.create({ } }) ``` +
Commonjs Environments @@ -219,6 +220,7 @@ const node = await IPFS.create({ } }) ``` +
Using script tags @@ -227,19 +229,20 @@ const node = await IPFS.create({ ``` +
- Examples for the async option: +Examples for the async option:
ESM Environments @@ -256,11 +259,13 @@ const node = await IPFS.create({ } }) ``` + > For more information about dynamic imports please check [webpack docs](https://webpack.js.org/guides/code-splitting/#dynamic-imports) or search your bundler documention. Using dynamic imports will tell your bundler to create a separate file (normally called *chunk*) that will **only** be requested by the browser if it's really needed. This strategy will reduce your bundle size and load times without removing any functionality. With Webpack IPLD formats can even be grouped together using magic comments `import(/* webpackChunkName: "ipld-formats" */ 'ipld-git')` to produce a single file with all of them. +
Commonjs Environments @@ -278,6 +283,7 @@ const node = await IPFS.create({ } }) ``` +
Using Script tags @@ -309,19 +315,19 @@ const node = await self.IPFS.create({ }) ``` -
+ ### `options.libp2p` | Type | Default | |------|---------| -| object | [`libp2p-nodejs.js`](../src/core/runtime/libp2p-nodejs.js) in Node.js, [`libp2p-browser.js`](../src/core/runtime/libp2p-browser.js) in browsers | -| function | [`libp2p bundle`](https://github.com/ipfs/js-ipfs/tree/master/examples/custom-libp2p) | +| object | [`libp2p-nodejs.js`](../src/core/runtime/libp2p-nodejs.js) in Node.js, [`libp2p-browser.js`](../src/core/runtime/libp2p-browser.js) in browsers | +| function | [`libp2p bundle`](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/custom-libp2p) | The libp2p option allows you to build your libp2p node by configuration, or via a bundle function. If you are looking to just modify the below options, using the object format is the quickest way to get the default features of libp2p. If you need to create a more customized libp2p node, such as with custom transports or peer/content routers that need some of the ipfs data on startup, a custom bundle is a great way to achieve this. -You can see the bundle in action in the [custom libp2p example](https://github.com/ipfs/js-ipfs/tree/master/examples/custom-libp2p). +You can see the bundle in action in the [custom libp2p example](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/custom-libp2p). Please see [libp2p/docs/CONFIGURATION.md](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md) for the list of options libp2p supports. diff --git a/package.json b/package.json index cbb8f42a13..34e610ee9a 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "scripts": { "postinstall": "lerna bootstrap", "link": "lerna link", - "reset": "lerna run clean && rimraf packages/*/node_modules examples/*/node_modules node_modules", + "reset": "lerna run clean && rimraf packages/*/node_modules node_modules", "test": "lerna run test", "test:node": "lerna run test:node", "test:browser": "lerna run test:browser", @@ -26,9 +26,6 @@ "clean": "lerna run clean", "lint": "lerna run lint", "dep-check": "lerna run dep-check", - "configure-examples": "run-s configure-examples:* release:pre:reinstall release:pre:bundle", - "configure-examples:add-examples": "json -I -f ./lerna.json -e \"this.packages.push('examples/*'); this.packages = [...new Set(this.packages)]\"", - "configure-examples:add-hoisted-modules": "json -I -f ./lerna.json -e \"this.command.bootstrap.nohoist = ['ipfs-css', 'tachyons']; this.command.bootstrap.nohoist = [...new Set(this.command.bootstrap.nohoist)]\"", "release": "run-s release:pre:* release:publish docker:release release:post:*", "release:pre:non-dirty-repo": "git diff --quiet", "release:pre:update-contributors": "aegir release --lint=false --test=false --bump=false --build=false --changelog=false --commit=false --tag=false --push=false --ghrelease=false --docs=false --publish=false --types=false", @@ -41,7 +38,6 @@ "docker:release:tag-version": "docker tag js-ipfs:latest docker.io/ipfs/js-ipfs:v`npm show ipfs@latest version -q`", "docker:release:push-latest": "docker push ipfs/js-ipfs:latest", "docker:release:push-version": "docker push ipfs/js-ipfs:v`npm show ipfs@latest version -q`", - "release:post:update-example-dependencies": "node scripts/update-example-deps.js", "release:rc": "run-s release:pre:* release:canary", "release:canary": "lerna publish --canary --preid rc --dist-tag next --force-publish --yes", "docker:rc": "run-s docker:rc:*", diff --git a/packages/ipfs-core/src/types.d.ts b/packages/ipfs-core/src/types.d.ts index 3cba063718..b612c79382 100644 --- a/packages/ipfs-core/src/types.d.ts +++ b/packages/ipfs-core/src/types.d.ts @@ -38,7 +38,7 @@ export interface Options { pass?: string /** - * Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs/js-ipfs/tree/master/examples/circuit-relaying) + * Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/circuit-relaying) * to learn more) */ relay?: RelayOptions @@ -113,7 +113,7 @@ export interface Options { * more customized libp2p node, such as with custom transports or peer/content * routers that need some of the ipfs data on startup, a custom bundle is a * great way to achieve this. - * - You can see the bundle in action in the [custom libp2p example](https://github.com/ipfs/js-ipfs/tree/master/examples/custom-libp2p). + * - You can see the bundle in action in the [custom libp2p example](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examplescustom-libp2p). * - Please see [libp2p/docs/CONFIGURATION.md](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md) * for the list of options libp2p supports. * - Default: [`libp2p-nodejs.js`](../src/core/runtime/libp2p-nodejs.js) diff --git a/packages/ipfs-http-client/README.md b/packages/ipfs-http-client/README.md index 0ca627fd38..ec7df8b704 100644 --- a/packages/ipfs-http-client/README.md +++ b/packages/ipfs-http-client/README.md @@ -118,8 +118,8 @@ Alternatively it can be an object which may have the following keys: #### Returns | Type | Description | -| -------- | -------- | -| `Object` | An object that conforms to the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) | +| ---- | ----------- | +| `Object` | An object that conforms to the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) | #### Example @@ -284,11 +284,11 @@ const ipfs = create({ host: '1.1.1.1', port: '80', apiPath: '/ipfs/api/v0' }) Same as in Node.js, you just have to [browserify](http://browserify.org) the code before serving it. See the browserify repo for how to do that. -See the example in the [examples folder](/examples/http-client-browser-browserify) to get a boilerplate. +See the example in the [examples folder](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples) to get a boilerplate. **through webpack** -See the example in the [examples folder](/examples/http-client-bundle-webpack) to get an idea on how to use `js-ipfs-http-client` with webpack. +See the example in the [examples folder](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/http-client-bundle-webpack) to get an idea on how to use `js-ipfs-http-client` with webpack. **from CDN** @@ -310,9 +310,11 @@ For maximum security you may also decide to: Example: ```html - + ``` CDN-based IPFS API provides the `IpfsHttpClient` constructor as a method of the global `window` object. Example: diff --git a/scripts/update-example-deps.js b/scripts/update-example-deps.js deleted file mode 100644 index f09192adb5..0000000000 --- a/scripts/update-example-deps.js +++ /dev/null @@ -1,98 +0,0 @@ -'use strict' - -const path = require('path') -const fs = require('fs') -const execa = require('execa') - -// Where an example depends on `"ipfs": "^0.51.0"` and we've just released `ipfs@0.52.0`, -// go through all of the examples and update the version to `"ipfs": "^0.52.0"` - do -// that with every module under /packages - -const PACKAGES_DIR = path.resolve(__dirname, '../packages') -const EXAMPLES_DIR = path.resolve(__dirname, '../examples') -const DEP_TYPES = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'] - -async function main () { - const { - stdout: branch - } = await execa('git', ['rev-parse', '--abbrev-ref', 'HEAD']) - - if (branch !== 'master') { - console.info(`Not running on branch ${branch}`) - return - } - - if (process.env.CI) { - console.info('Not running in CI') - return - } - - console.info('Running on branch', branch) - - // list all of the package.json files we may have just updated - const potentiallyUpdatedProjects = [] - - for (const dir of fs.readdirSync(PACKAGES_DIR)) { - const projectPkgPath = path.resolve(PACKAGES_DIR, dir, 'package.json') - - if (!fs.existsSync(projectPkgPath)) { - continue - } - - potentiallyUpdatedProjects.push(projectPkgPath) - } - - // add the example test runner - potentiallyUpdatedProjects.push(path.resolve(EXAMPLES_DIR, 'test-ipfs-example', 'package.json')) - - for (const projectPkgPath of potentiallyUpdatedProjects) { - const projectPkg = JSON.parse(fs.readFileSync(projectPkgPath, { encoding: 'utf8' })) - const projectDepVersion = `^${projectPkg.version}` - - // look through all the example projects and update their deps - for (const dir of fs.readdirSync(EXAMPLES_DIR)) { - const examplePkgPath = path.resolve(EXAMPLES_DIR, dir, 'package.json') - - if (!fs.existsSync(examplePkgPath)) { - continue - } - - const examplePkg = JSON.parse(fs.readFileSync(examplePkgPath, { encoding: 'utf8' })) - let dirty = false - - for (const depType of DEP_TYPES) { - if (examplePkg[depType] && examplePkg[depType][projectPkg.name] && examplePkg[depType][projectPkg.name] !== projectDepVersion) { - console.info(`Updating ${examplePkg.name} ${projectPkg.name}: ${examplePkg[depType][projectPkg.name]} -> ${projectDepVersion}`) - examplePkg[depType][projectPkg.name] = projectDepVersion - dirty = true - } - } - - if (dirty) { - fs.writeFileSync(examplePkgPath, JSON.stringify(examplePkg, null, 2) + '\n', { encoding: 'utf8' }) - } - } - } - - await execa('git', ['add', 'examples']) - - const { - stdout: updated - } = await execa('git', ['status', '--porcelain']) - - console.info(updated) - - if (!updated.match(/^M\s+examples/g)) { - console.info('No examples were updated') - return - } - - console.info('Pushing updated dependencies') - await execa('git', ['commit', '-m', 'chore: updated example dependencies']) - await execa('git', ['push']) -} - -main().catch(err => { - console.error(err) - process.exit(1) -})