feat: v21 (#413)

BREAKING CHANGE: package is now ESM

README.md

@@ -28,14 +28,19 @@ Node
 Install with <code>npm install @octokit/rest</code>
 
 ```js
-const { Octokit } = require("@octokit/rest");
-// or: import { Octokit } from "@octokit/rest";
+import { Octokit } from "@octokit/rest";
 ```
 
 </td></tr>
 </tbody>
 </table>
 
+> [!IMPORTANT]
+> As we use [conditional exports](https://nodejs.org/api/packages.html#conditional-exports), you will need to adapt your `tsconfig.json` by setting `"moduleResolution": "node16", "module": "node16"`.
+>
+> See the TypeScript docs on [package.json "exports"](https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-exports).<br>
+> See this [helpful guide on transitioning to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) from [@sindresorhus](https://github.com/sindresorhus)
+
 ```js
 const octokit = new Octokit();
 
@@ -52,6 +57,12 @@ octokit.rest.repos
 
 See https://octokit.github.io/rest.js for full documentation.
 
+> [!IMPORTANT]
+> As we use [conditional exports](https://nodejs.org/api/packages.html#conditional-exports), you will need to adapt your `tsconfig.json` by setting `"moduleResolution": "node16", "module": "node16"`.
+>
+> See the TypeScript docs on [package.json "exports"](https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-exports).<br>
+> See this [helpful guide on transitioning to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) from [@sindresorhus](https://github.com/sindresorhus)
+
 ## Contributing
 
 We would love you to contribute to `@octokit/rest`, pull requests are very welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information.

docs/src/pages/api/00_usage.md

@@ -24,15 +24,14 @@ Load <code>@octokit/rest</code> directly from <a href="https://esm.sh">esm.sh</a
 Install with <code>npm install @octokit/rest</code>
 
 ```js
-const { Octokit } = require("@octokit/rest");
-// or: import { Octokit } from "@octokit/rest";
+import { Octokit } from "@octokit/rest";
 ```
 
 </div>
 <hr />
 
 ```js
-const { Octokit } = require("@octokit/rest");
+import { Octokit } from "@octokit/rest";
 ```
 
 Now instantiate your octokit API. All options are optional, but authentication is strongly encouraged.

docs/src/pages/api/01_authentication.md

@@ -16,7 +16,7 @@ Learn more about all official and community [authentication strategies](https://
 By default, `@octokit/rest` authenticates using the [token authentication strategy](https://github.com/octokit/auth-token.js). Pass in a token using `options.auth`. It can be a personal access token, an OAuth token, an installation access token or a JSON Web Token for GitHub App authentication. The `Authorization` request header will be set according to the type of token.
 
 ```js
-const { Octokit } = require("@octokit/rest");
+import { Octokit } from "@octokit/rest";
 
 const octokit = new Octokit({
   auth: "mypersonalaccesstoken123",
@@ -30,8 +30,8 @@ To use a different authentication strategy, set `options.authStrategy`.
 Here is an example for GitHub App authentication
 
 ```js
-const { Octokit } = require("@octokit/rest");
-const { createAppAuth } = require("@octokit/auth-app");
+import { Octokit } from "@octokit/rest";
+import { createAppAuth } from "@octokit/auth-app";
 
 const appOctokit = new Octokit({
   authStrategy: createAppAuth,

docs/src/pages/api/03_request_formats.md

@@ -17,7 +17,7 @@ const { data: prDiff } = await octokit.rest.pulls.get({
 });
 ```
 
-The [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) interface can be used to abort one or more requests as and when desired. When the request is initiated, an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance can be passed as an option inside the request's options object. For usage in Node, the [`abort-controller`](https://github.com/mysticatea/abort-controller) package can be used.
+The [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) interface can be used to abort one or more requests as and when desired. When the request is initiated, an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance can be passed as an option inside the request's options object.
 
 ```js
 const controller = new AbortController();

docs/src/pages/api/07_custom_endpoints.md

@@ -2,71 +2,29 @@
 title: "Custom endpoint methods"
 ---
 
-**Note**: `octokit.registerEndpoints()` has been deprecated.
-
-Instead of
+You can register custom endpoint methods such as `octokit.rest.repos.get()` by extending the octokit object
 
 ```js
-await octokit.registerEndpoints({
-  misc: {
-    getRoot: {
-      method: "GET",
-      url: "/",
+Object.assign(octokit.foo, {
+  bar: {
+    method: "PATCH",
+    url: "/repos/{owner}/{repo}/foo",
+    headers: {
+      accept: "application/vnd.github.foo-bar-preview+json",
     },
-  },
-});
-```
-
-do
-
-```js
-Object.assign(octokit.misc, {
-  getRoot: octokit.request.defaults({
-    method: "GET",
-    url: "/",
-  }),
-});
-```
-
-If you use `octokit.registerEndpoints()` in a plugin, return an object instead:
-
-```js
-function myPlugin(octokit, options) {
-  return {
-    misc: {
-      octokit.request.defaults({ method: "GET", url: "/" })
-    }
-  }
-}
-```
-
----
-
-You can register custom endpoint methods such as `octokit.rest.repos.get()` using the `octokit.registerEndpoints(routes)` method
-
-```js
-octokit.registerEndpoints({
-  foo: {
-    bar: {
-      method: "PATCH",
-      url: "/repos/{owner}/{repo}/foo",
-      headers: {
-        accept: "application/vnd.github.foo-bar-preview+json",
+    params: {
+      owner: {
+        required: true,
+        type: "string",
+      },
+      repo: {
+        required: true,
+        type: "string",
       },
-      params: {
-        owner: {
-          required: true,
-          type: "string",
-        },
-        repo: {
-          required: true,
-          type: "string",
-        },
-        baz: {
-          required: true,
-          type: "string",
-          enum: ["qux", "quux", "quuz"],
-        },
+      baz: {
+        required: true,
+        type: "string",
+        enum: ["qux", "quux", "quuz"],
       },
     },
   },

docs/src/pages/api/08_plugins.md

@@ -6,14 +6,14 @@ You can customize and extend Octokit’s functionality using plugins
 
 ```js
 // index.js
-const { Octokit } = require("@octokit/rest");
-const MyOctokit = Octokit.plugin(
-  require("./lib/my-plugin"),
-  require("octokit-plugin-example"),
-);
+import { Octokit } from "@octokit/rest";
+import myPlugin from "./lib/my-plugin.js";
+import octokitPluginExample from "octokit-plugin-example";
+
+const MyOctokit = Octokit.plugin(myPlugin, octokitPluginExample);
 
 // lib/my-plugin.js
-module.exports = (octokit, options = { greeting: "Hello" }) => {
+const plugin = (octokit, options = { greeting: "Hello" }) => {
   // hook into the request lifecycle
   octokit.hook.wrap("request", async (request, options) => {
     const time = Date.now();
@@ -31,6 +31,7 @@ module.exports = (octokit, options = { greeting: "Hello" }) => {
     helloWorld: () => console.log(`${options.greeting}, world!`),
   };
 };
+export default plugin;
 ```
 
 `.plugin` accepts a function or an array of functions.

docs/src/pages/api/09_throttling.md

@@ -11,8 +11,8 @@ The `throttle.onSecondaryRateLimit` and `throttle.onRateLimit` options are requi
 Return `true` from these functions to automatically retry the request after `retryAfter` seconds. Return `false` or `undefined` to skip retry and throw the error. For rate limit errors, `retryAfter` defaults to seconds until `X-RateLimit-Reset`. For abuse errors, `retryAfter` defaults to the `retry-after` header but is a minimum of five seconds.
 
 ```js
-const { Octokit } = require("@octokit/rest");
-const { throttling } = require("@octokit/plugin-throttling");
+import { Octokit } from "@octokit/rest";
+import { throttling } from "@octokit/plugin-throttling";
 const MyOctokit = Octokit.plugin(throttling);
 
 const octokit = new MyOctokit({

docs/src/pages/api/10_retries.md

@@ -5,8 +5,8 @@ title: "Automatic retries"
 Many common request errors can be easily remediated by retrying the request. We recommend installing the [`@octokit/plugin-retry` plugin](https://github.com/octokit/plugin-retry.js) for Automatic retries in these cases
 
 ```js
-const { Octokit } = require("@octokit/rest");
-const { retry } = require("@octokit/plugin-retry");
+import { Octokit } from "@octokit/rest";
+import { retry } from "@octokit/plugin-retry";
 const MyOctokit = Octokit.plugin(retry);
 
 const octokit = new MyOctokit();

docs/src/pages/api/12_debug.md

@@ -5,7 +5,8 @@ title: "Debug"
 The simplest way to receive debug information is to set the `log` client option to `console`.
 
 ```js
-const octokit = require("@octokit/rest")({
+import { Octokit } from "@octokit/rest";
+const octokit = new Octokit({
   log: console,
 });
 
@@ -29,8 +30,10 @@ GET / - 200 in 514ms
 If you like to support a configurable log level, we recommend using the [console-log-level](https://github.com/watson/console-log-level) module
 
 ```js
-const octokit = require("@octokit/rest")({
-  log: require("console-log-level")({ level: "info" }),
+import { Octokit } from "@octokit/rest";
+import consoleLogLevel from "console-log-level";
+const octokit = new Octokit({
+  log: consoleLogLevel({ level: "info" }),
 });
 
 octokit.request("/");