slackapi · lukegalbraithrussell · May 21, 2026 · May 21, 2026 · May 21, 2026 · May 21, 2026
@@ -16,12 +16,61 @@
   {
     "type": "category",
     "label": "Migration",
+    "link": {
+      "type": "doc",
+      "id": "tools/node-slack-sdk/migration/migration"
+    },
     "items": [
-      "tools/node-slack-sdk/migration/migrating-to-v4",
-      "tools/node-slack-sdk/migration/migrating-to-v5",
-      "tools/node-slack-sdk/migration/migrating-to-v6",
-      "tools/node-slack-sdk/migration/migrating-socket-mode-package-to-v2",
-      "tools/node-slack-sdk/migration/migrating-web-api-package-to-v7"
+      "tools/node-slack-sdk/migration/migration",
+      {
+        "type": "category",
+        "label": "Socket Mode",
+        "link": {
+          "type": "doc",
+          "id": "tools/node-slack-sdk/migration/socket-mode/migrating-socket-mode-package-to-v3"
+        },
+        "items": [
+          "tools/node-slack-sdk/migration/socket-mode/migrating-socket-mode-package-to-v3",
+          "tools/node-slack-sdk/migration/socket-mode/migrating-socket-mode-package-to-v2"
+
+        ]
+      },
+      {
+        "type": "category",
+        "label": "Web API",
+        "link": {
+          "type": "doc",
+          "id": "tools/node-slack-sdk/migration/web-api/migrating-web-api-package-to-v8"
+        },
+        "items": [
+          "tools/node-slack-sdk/migration/web-api/migrating-web-api-package-to-v8",
+          "tools/node-slack-sdk/migration/web-api/migrating-web-api-package-to-v7"
+        ]
+      },
+      {
+        "type": "category",
+        "label": "Webhook",
+        "link": {
+          "type": "doc",
+          "id": "tools/node-slack-sdk/migration/webhook/migrating-webhook-package-to-v8"
+        },
+        "items": [
+          "tools/node-slack-sdk/migration/webhook/migrating-webhook-package-to-v8"
+        ]
+      },
+      {
+        "type": "category",
+        "label": "Legacy",
+        "link": {
+          "type": "doc",
+          "id": "tools/node-slack-sdk/migration/legacy/migrating-to-v6"
+        },
+        "items": [
+          "tools/node-slack-sdk/migration/legacy/migrating-to-v6",
+          "tools/node-slack-sdk/migration/legacy/migrating-to-v5",
+          "tools/node-slack-sdk/migration/legacy/migrating-to-v4"
+        ]
+      }
     ]
   },
   {

@@ -0,0 +1,13 @@
+# Migrating packages
+
+The Node Slack SDK exists as a single repo containing a confederation of independent packages (`@slack/web-api`, `@slack/webhook`, `@slack/socket-mode`, etc.). Each package can be upgraded independently on its own schedule.
+
+:::tip[For info on how long each Node version is supported, see the [support schedule](/tools/node-slack-sdk/support-schedule).]
+:::
+
+## Legacy migration guides
+
+The **Legacy** section contains migration guides for old major versions of the Node Slack SDK. These guides reflect an outdated approach where all packages in the SDK were released together as a coordinated release. Today, each package evolves independently. For example, the `@slack/web-api` package may be at v8 while `@slack/socket-mode` may be at v3.
+
+If you're upgrading from very old versions, the legacy guides provide historical context, but you'll likely want to follow the package-specific guides below for current migrations.
+
@@ -1,4 +1,8 @@
-# Migrating the `socket‐mode` package to v2.x
+---
+sidebar_label: Migrating to v2
+---
+
+# Migrating the `socket‐mode` package from v1 to v2
 
 This migration guide helps you transition an application written using the `v1.x` series of the `@slack/socket-mode` package to the `v2.x` series. This guide focuses specifically on the breaking changes to help get your existing projects up and running as quickly as possible.
 

@@ -0,0 +1,257 @@
+---
+sidebar_label: Migrating to v3
+---
+
+# Migrating the `socket-mode` package from v2 to v3
+
+_Minimum Node.js version: 20_
+
+This major release switches from the [`ws`](https://www.npmjs.com/package/ws) library to the [`undici`](https://undici.nodejs.org/) library's [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) implementation. 
+
+If you're not using a proxy or custom TLS, we hope no action is needed beyond bumping the version number.
+
+The main thing you'll notice: `httpAgent` is gone. You'll use a `dispatcher` option instead, which handles both WebSocket connections and HTTP API calls in one place. Or, if you're on a recent Node.js version, you can set an environment variable and skip manual proxy config entirely.
+
+
+## Installation
+
+```
+npm i @slack/socket-mode
+```
+
+## Breaking changes
+
+### We've removed the `httpAgent` option
+
+**Before (v2):**
+
+```typescript
+import { SocketModeClient } from '@slack/socket-mode';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+
+const agent = new HttpsProxyAgent('http://corporate.proxy:8080');
+
+const client = new SocketModeClient({
+  appToken: process.env.SLACK_APP_TOKEN,
+  httpAgent: agent,
+});
+```
+
+#### Preferred: Built-in proxy support
+
+Node.js can read your proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) and route traffic automatically via [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv). Both WebSocket and HTTP traffic respect this.
+
+##### Option A: programmatically call once at startup
+
+```typescript
+import http from 'node:http';
+import { SocketModeClient } from '@slack/socket-mode';
+
+http.setGlobalProxyFromEnv();
+
+// Both WebSocket and HTTP API calls route through the proxy automatically
+const client = new SocketModeClient({
+  appToken: process.env.SLACK_APP_TOKEN,
+});
+```
+
+##### Option B: use an environment variable
+
+```bash
+NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://corporate.proxy:8080 node app.js
+```
+
+```typescript
+import { SocketModeClient } from '@slack/socket-mode';
+
+// No proxy configuration needed — both WebSocket and HTTP use the proxy
+const client = new SocketModeClient({
+  appToken: process.env.SLACK_APP_TOKEN,
+});
+```
+
+#### Alternative: use the undici `dispatcher`
+
+If you need per-client proxy configuration or separate WebSocket vs HTTP proxy routing, use the `dispatcher` option with an undici `Dispatcher` (like `ProxyAgent` or `Agent`).
+
+The `dispatcher` is used for both WebSocket connections and HTTP API calls (via the internal `WebClient`):
+
+```typescript
+import { SocketModeClient } from '@slack/socket-mode';
+import { ProxyAgent } from 'undici';
+
+const dispatcher = new ProxyAgent('http://corporate.proxy:8080');
+
+const client = new SocketModeClient({
+  appToken: process.env.SLACK_APP_TOKEN,
+  dispatcher,
+});
+```
+
+
+---
+
+### We've updated the dependency on `@slack/web-api@^8`
+
+This package now uses `@slack/web-api@^8` internally. If you're passing `clientOptions`, the web-api breaking changes apply there too. Check the [web-api v8 migration guide](./web-api-v8-migration.md) for details.
+
+```diff
+ const client = new SocketModeClient({
+   appToken: process.env.SLACK_APP_TOKEN,
+   clientOptions: {
+-    agent: myAgent,
+-    tls: { cert, key },
++    fetch: (url, init) => fetch(url, { ...init, dispatcher }),
+   },
+ });
+```
+
+---
+
+### We've removed the `ws` library and added the `undici@^7` library.
+
+Learn more about the `undici` library [here](https://www.npmjs.com/package/undici).
+
+---
+
+### We've raised the minimum Node.js version to 20
+
+We've dropped support for Node.js 18. Node.js 20 or later is required.
+
+---
+
+### We've overhauled error handling
+
+Errors are now proper `Error` subclasses instead of interfaces. This means `instanceof` checks work, TypeScript narrows types correctly, and error names are descriptive.
+
+**Your existing `error.code` checks still work.** The `ErrorCode` enum values are unchanged. But `instanceof` is now the recommended pattern.
+
+#### New error classes
+
+| Class | When it's thrown |
+| --- | --- |
+| `SMWebsocketError` | WebSocket connection or protocol failure |
+| `SMPlatformError` | Slack API returned an error (e.g., `apps.connections.open` failed) |
+| `SMNoReplyReceivedError` | Server didn't acknowledge a message in time |
+| `SMSendWhileDisconnectedError` | Attempted to send while the WebSocket is disconnected |
+| `SMSendWhileNotReadyError` | Attempted to send before the client is fully ready |
+
+#### How `instanceof` checks work
+
+**Before (v2):**
+
+```typescript
+import { SocketModeClient, ErrorCode } from '@slack/socket-mode';
+
+const client = new SocketModeClient({ appToken: process.env.SLACK_APP_TOKEN });
+
+client.on('error', (error) => {
+  if (error.code === ErrorCode.SendWhileDisconnectedError) {
+    console.log('Not connected, will retry...');
+  } else if (error.code === ErrorCode.WebsocketError) {
+    console.log('WebSocket issue:', error.message);
+  }
+});
+```
+
+**After (v3):**
+
+```typescript
+import {
+  SocketModeClient,
+  SMSendWhileDisconnectedError,
+  SMWebsocketError,
+} from '@slack/socket-mode';
+
+const client = new SocketModeClient({ appToken: process.env.SLACK_APP_TOKEN });
+
+client.on('error', (error) => {
+  if (error instanceof SMSendWhileDisconnectedError) {
+    console.log('Not connected, will retry...');
+  } else if (error instanceof SMWebsocketError) {
+    console.log('WebSocket issue:', error.cause);
+  }
+});
+```
+
+The `error.code` pattern still works if you prefer not to change your error handling:
+
+```typescript
+import { SocketModeClient, ErrorCode } from '@slack/socket-mode';
+
+const client = new SocketModeClient({ appToken: process.env.SLACK_APP_TOKEN });
+
+client.on('error', (error) => {
+  if (error.code === ErrorCode.SendWhileDisconnectedError) {
+    console.log('Not connected, will retry...');
+  }
+});
+```
+
+#### `error.name` values changed
+
+| Error class | v2 `error.name` | v3 `error.name` |
+| --- | --- | --- |
+| `SMWebsocketError` | `'Error'` | `'SMWebsocketError'` |
+| `SMPlatformError` | `'Error'` | `'SMPlatformError'` |
+| `SMNoReplyReceivedError` | `'Error'` | `'SMNoReplyReceivedError'` |
+| `SMSendWhileDisconnectedError` | `'Error'` | `'SMSendWhileDisconnectedError'` |
+| `SMSendWhileNotReadyError` | `'Error'` | `'SMSendWhileNotReadyError'` |
+
+If your logging or error monitoring tools filter on `error.name`, update those filters.
+
+---
+
+## New features
+
+### `dispatcher` option for unified proxy/TLS configuration
+
+:::tip[You can skip manual dispatcher configuration entirely by using `http.setGlobalProxyFromEnv()` or `NODE_USE_ENV_PROXY=1`]
+See [the `httpAgent` option removed section](#we-removed-the-httpagent-option) above for more detail.
+:::
+
+Pass any undici `Dispatcher` and it'll handle both WebSocket and HTTP traffic:
+
+```typescript
+import { SocketModeClient, LogLevel } from '@slack/socket-mode';
+import { ProxyAgent } from 'undici';
+
+const dispatcher = new ProxyAgent('http://corporate.proxy:8080');
+
+const client = new SocketModeClient({
+  appToken: process.env.SLACK_APP_TOKEN,
+  logLevel: LogLevel.DEBUG,
+  dispatcher,
+});
+
+client.on('message', async ({ event, ack }) => {
+  await ack();
+  console.log(event);
+});
+
+await client.start();
+```
+
+### Separate dispatchers for WebSocket and HTTP traffic
+
+For advanced cases where WebSocket and HTTP traffic need different proxy configurations:
+
+```typescript
+import { SocketModeClient } from '@slack/socket-mode';
+import { fetch, ProxyAgent } from 'undici';
+
+const wsProxy = new ProxyAgent('http://ws-proxy:8080');
+const httpProxy = new ProxyAgent('http://http-proxy:9090');
+
+const client = new SocketModeClient({
+  appToken: process.env.SLACK_APP_TOKEN,
+  // WebSocket connections use this dispatcher
+  dispatcher: wsProxy,
+  clientOptions: {
+    // HTTP API calls use a separate custom fetch
+    fetch: (url, init) => fetch(url, { ...init, dispatcher: httpProxy }),
+  },
+});
+```
+
+When you provide `clientOptions.fetch`, the `dispatcher` only handles WebSocket connections; HTTP calls go through your custom fetch instead.
@@ -1,8 +1,10 @@
-# Migrating the `web-api` package to v7.x
+---
+sidebar_label: Migrating to v7
+---
 
-This migration guide helps you transition an application written using the `v6.x` series of the `@slack/web-api` package to the `v7.x`
-series. This guide focuses specifically on the breaking changes to help get your existing app up and running as
-quickly as possible.
+# Migrating the `web-api` package from v6 to v7
+
+This migration guide helps you transition an application written using the `v6.x` series of the `@slack/web-api` package to the `v7.x` series. This guide focuses specifically on the breaking changes to help get your existing app up and running as quickly as possible.
 
 ## Installation