Docs: migration guides for new package versions by lukegalbraithrussell · Pull Request #2606 · slackapi/node-slack-sdk

lukegalbraithrussell · 2026-05-22T20:16:19Z

Summary

previews:

changelog entry (this is in the docs repo)
migration overview page
web-api migration guide
webhook migration guide
socket-mode migration guide

Requirements

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

changeset-bot · 2026-05-22T20:16:25Z

⚠️ No Changeset found

Latest commit: 9c2f52a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

codecov · 2026-05-22T20:18:12Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.86%. Comparing base (aeaf9f9) to head (9c2f52a).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2606      +/-   ##
==========================================
+ Coverage   87.50%   88.86%   +1.35%     
==========================================
  Files          62       62              
  Lines       10230    10230              
  Branches      418      450      +32     
==========================================
+ Hits         8952     9091     +139     
+ Misses       1256     1117     -139     
  Partials       22       22

Flag	Coverage Δ
cli-hooks	`88.86% <ø> (+1.35%)`	⬆️
cli-test	`88.86% <ø> (+1.35%)`	⬆️
logger	`88.86% <ø> (+1.35%)`	⬆️
oauth	`88.86% <ø> (+1.35%)`	⬆️
socket-mode	`88.86% <ø> (+1.35%)`	⬆️
web-api	`88.86% <ø> (+1.35%)`	⬆️
webhook	`88.86% <ø> (+1.35%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

WilliamBergamin

Nice work 🥇 left a few comments mainly about remove some stuff 🙏

Maybe we should merge this branch in the v8 instead of main that was we can merge everything at the same time 🤔 at the same time there might be a delay between merging and releasing

WilliamBergamin · 2026-05-25T14:08:23Z

+sidebar_label: Migrating to v2
+---
+
+# Migrating the `socket‐mode` package from v1 sto v2


Suggested change

# Migrating the `socket‐mode` package from v1 sto v2

# Migrating the `socket‐mode` package from v1 to v2

WilliamBergamin · 2026-05-25T14:09:59Z

+
+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, no action is needed beyond bumping the version number.


I'm not sure if there might be other complications needed in the transition specifically around typescript and testing 😅

Suggested change

If you're not using a proxy or custom TLS, no action is needed beyond bumping the version number.

If you're not using a proxy or custom TLS, we hope no action is needed beyond bumping the version number.

WilliamBergamin · 2026-05-25T14:13:04Z

+
+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.
+
+The `undici` library is a **peer dependency**.


Maybe we should remove this from the official docs 🤔 I want to try keeping it a peer dependency but if its an issue, we will make it a dependency 😅

WilliamBergamin · 2026-05-25T14:15:39Z

+##### Option A: use 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,
+});
+```
+
+##### Option B: programmatically call once at startup


Could we swap the order to of the options 🙏 I find option B to be more more explicit

WilliamBergamin · 2026-05-25T14:16:36Z

+});
+```
+
+No separate proxy setup needed as one dispatcher covers everything.


I don't think we need this line 🙏

WilliamBergamin · 2026-05-25T15:03:26Z

+
+### We've overhauled error handling
+
+Errors are now proper `Error` subclasses instead of interfaces with factory functions ([#2593](https://github.com/slackapi/node-slack-sdk/pull/2593)). This means `instanceof` checks work, TypeScript narrows types correctly, and error names are descriptive.


Suggested change

Errors are now proper `Error` subclasses instead of interfaces with factory functions ([#2593](https://github.com/slackapi/node-slack-sdk/pull/2593)). This means `instanceof` checks work, TypeScript narrows types correctly, and error names are descriptive.

Errors are now proper `Error` subclasses instead of interfaces. This means `instanceof` checks work, TypeScript narrows types correctly, and error names are descriptive.

WilliamBergamin · 2026-05-25T15:04:42Z

+#### New error class hierarchy
+
+```
+SlackError (abstract)
+├── WebAPIPlatformError    — Slack API returned ok: false
+├── WebAPIHTTPError        — non-200 HTTP status
+├── WebAPIRequestError     — network/fetch failure
+├── WebAPIRateLimitedError — 429 rate limited
+└── WebAPIFileUploadReadFileDataError — file read failure during upload
+```


I don't think we need this section 🤔

Suggested change

#### New error class hierarchy

```

SlackError (abstract)

├── WebAPIPlatformError — Slack API returned ok: false

├── WebAPIHTTPError — non-200 HTTP status

├── WebAPIRequestError — network/fetch failure

├── WebAPIRateLimitedError — 429 rate limited

└── WebAPIFileUploadReadFileDataError — file read failure during upload

```

WilliamBergamin · 2026-05-25T15:07:11Z

+### We've added exported `fetch` types
+
+You can now use these new types for implementing custom fetch functions with full TypeScript support:
+
+- `FetchFunction` — the function signature
+- `FetchResponse` — response interface
+- `FetchRequestInit` — request options interface
+- `FetchHeaders` — headers interface


Not sure we need to call this out here 🤔

WilliamBergamin · 2026-05-25T15:07:45Z

+**Option A — environment variable:**
+
+```bash
+NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://corporate.proxy:8080 node app.js
+```
+
+```typescript
+import { IncomingWebhook } from '@slack/webhook';
+
+// No proxy configuration needed — globalThis.fetch respects the environment
+const webhook = new IncomingWebhook(webhookUrl);
+```
+
+**Option B — programmatic (call once at startup):**


Here also swapping the option order 🙏

WilliamBergamin · 2026-05-25T15:08:18Z

+
+This major release drops the [axios](https://www.npmjs.com/package/axios) library and uses the native [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (`globalThis.fetch`) instead.
+
+The `agent` option is replaced by a `fetch` option. Pass in your own fetch function to configure proxies or TLS. If you're not using proxies or custom agents, no action is needed beyond bumping the version number.


Suggested change

The `agent` option is replaced by a `fetch` option. Pass in your own fetch function to configure proxies or TLS. If you're not using proxies or custom agents, no action is needed beyond bumping the version number.

The `agent` option is replaced by a `fetch` option. Pass in your own fetch function to configure proxies or TLS. If you're not using proxies or custom agents, we hope no action is needed beyond bumping the version number.

lukegalbraithrussell added 7 commits May 21, 2026 09:54

go

bbb5d76

go

83ca6ee

go

8357991

go

3a5486a

go

ce3fbda

go

308e662

sidebar

9c2f52a

lukegalbraithrussell requested a review from a team as a code owner May 22, 2026 20:16

lukegalbraithrussell requested a review from WilliamBergamin May 22, 2026 20:17

WilliamBergamin requested changes May 25, 2026

View reviewed changes

	# Migrating the `socket‐mode` package from v1 sto v2
	# Migrating the `socket‐mode` package from v1 to v2


		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, 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.

		The `undici` library is a peer dependency.


		### We've overhauled error handling

		Errors are now proper `Error` subclasses instead of interfaces with factory functions ([#2593](https://github.com/slackapi/node-slack-sdk/pull/2593)). This means `instanceof` checks work, TypeScript narrows types correctly, and error names are descriptive.


		This major release drops the [axios](https://www.npmjs.com/package/axios) library and uses the native [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (`globalThis.fetch`) instead.

		The `agent` option is replaced by a `fetch` option. Pass in your own fetch function to configure proxies or TLS. If you're not using proxies or custom agents, no action is needed beyond bumping the version number.

Conversation

lukegalbraithrussell commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Requirements

Uh oh!

changeset-bot Bot commented May 22, 2026

⚠️ No Changeset found

Uh oh!

codecov Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lukegalbraithrussell commented May 22, 2026 •

edited

Loading

codecov Bot commented May 22, 2026 •

edited

Loading