feat: Node Slack SDK major version release candidate

[WilliamBergamin]

Summary

This is the major release of the Node Slack SDK. The headline changes: axios is gone, ws is gone, and the SDK now runs on web-standard APIs (fetch, WebSocket) that work across runtimes.

Why this release exists

• Eliminate the recurring axios CVE cycle: switching to globalThis.fetch, the SDK no longer carries a third-party HTTP client as an attack surface.
• Drop 6 dependencies:axios, form-data, is-electron, is-stream, ws, @types/ws. Smaller install, fewer supply-chain risks.
• Proper error classes: errors are real Error subclasses with instanceof support, not duck-typed interfaces with factory functions.
• Cross-runtime compatibility: the SDK works in Node.js, Deno, Bun, and Cloudflare Workers out of the box.

Minimum requirements

• Node.js 20 (native fetch, FormData, and WebSocket are stable)
• TypeScript compilation target raised from es2017 to es2022

---

Package Changes

@slack/web-api (v7 → v8)

The biggest change in the SDK. Replaces axios with globalThis.fetch.

Breaking changes

Change	Details
agent option removed	Use NODE_USE_ENV_PROXY=1 / http.setGlobalProxyFromEnv(), or pass a custom fetch with an undici dispatcher
tls option and TLSOptions export removed	Configure TLS via a custom fetch with an undici Agent dispatcher
requestInterceptor and RequestInterceptor type removed	Wrap the fetch function instead
adapter and AdapterConfig type removed	Provide a custom fetch function instead
RequestConfig type removed	Was an alias for InternalAxiosRequestConfig — no longer needed
attachOriginalToWebAPIRequestError option removed	The original error is now always attached
Deprecated API methods removed	files.upload, rtm.start, workflows.stepCompleted, workflows.stepFailed, workflows.updateStep
Error handling overhaul	Errors are now Error subclasses; instanceof works; error.name values are descriptive
WebAPIHTTPError.headers type changed	Now Record<string, string> instead of IncomingHttpHeaders
WebAPIRequestError uses Error.cause	Standard cause property populated alongside original for backward compat

New features

• fetch option: pass any function matching globalThis.fetch's signature for full transport control (proxies, TLS, instrumentation, testing)
• FetchFunction type export: TypeScript type for custom fetch implementations
• SlackError abstract base class: catch all SDK errors with a single instanceof SlackError check

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

Dependencies removed

• axios
• form-data
• is-electron
• is-stream

---

@slack/socket-mode (v2 → v3)

Replaces the ws library with undici's spec-compliant WebSocket implementation.

Breaking changes

Change	Details
httpAgent option removed	Use NODE_USE_ENV_PROXY=1 / http.setGlobalProxyFromEnv(), or use the new dispatcher option
Depends on @slack/web-api@^8	web-api v8 breaking changes apply to clientOptions
Error handling overhaul	Errors are now Error subclasses; instanceof works

New features

• dispatcher option: pass any undici Dispatcher (e.g. ProxyAgent) to handle both WebSocket and HTTP traffic in one place
• Separate dispatchers: use dispatcher for WebSocket + clientOptions.fetch for HTTP when you need different proxy routing
• Spec-compliant WebSocket: aligned with browser WebSocket APIs via undici
• SocketModeDispatcher interface: structural type for dispatcher compatibility across undici versions

Error classes

Class	When it's thrown
SMWebsocketError	WebSocket connection or protocol failure
SMPlatformError	Slack API returned an error
SMNoReplyReceivedError	Server didn't acknowledge a message in time
SMSendWhileDisconnectedError	Attempted to send while disconnected
SMSendWhileNotReadyError	Attempted to send before client is ready

Dependencies removed

• ws
• @types/ws

---

@slack/webhook (v7 → v8)

Drops axios in favor of globalThis.fetch. Minimal API surface, so the migration is straightforward.

Breaking changes

Change	Details
agent option removed	Use env-based proxy or a custom fetch with an undici dispatcher
Error classes restructured	IncomingWebhookHTTPError now has statusCode, statusMessage, body directly (no more error.original.response)
IncomingWebhookRequestError.original is now a standard Error	Was AxiosError in v7

New features

• fetch option: custom fetch for transport control
• FetchFunction type export
• SlackWebhookError abstract base class: catch all webhook errors with instanceof SlackWebhookError

Dependencies removed

• axios

---

@slack/oauth (v3 → v4)

Change	Details
Minimum Node.js 20	Raised from 18
Depends on @slack/web-api@^8 and @slack/logger@^5	Picks up the new web-api and logger versions

No functional API changes — this is a dependency-bump major version.

---

@slack/logger (v4 → v5)

Change	Details
Minimum Node.js 20	Raised from 18

No functional API changes — semver major for the engine constraint.

---

@slack/types (v2 → v3)

Change	Details
Minimum Node.js 20	Raised from 12

No functional API changes — semver major for the engine constraint.

---

@slack/cli-hooks (v1 → v2)

Change	Details
Minimum Node.js 20	Raised from 18

No functional API changes.

---

@slack/cli-test (v3 → v4)

Change	Details
Minimum Node.js 20	Raised from 18

No functional API changes.

---

Infrastructure changes

• CI: Removed Node.js 18 from the test matrix; testing on 20, 22, and 24
• TypeScript: Base tsconfig target raised from es2017 to es2022

---

Migration guides

Coming soon...

---

TL;DR for most users

If you're not using proxies, custom agents, or requestInterceptor:

npm install @slack/web-api@next @slack/socket-mode@next @slack/webhook@next

Your code likely works unchanged. The SDK now uses globalThis.fetch under the hood.

If you are using proxies, the simplest migration is:

NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://your.proxy:8080 node app.js

No code changes needed, Node.js routes all fetch/WebSocket traffic through the proxy automatically.

---

Related PRs

• chore: drop Node.js 18 support for relevant packages #2572 — Drop Node.js 18 support
• feat: migrate from axios to fetch #2591 — Migrate from axios to fetch
• feat(web-api): remove deprecated API methods #2592 — Remove deprecated API methods
• feat: replace error interfaces with proper Error subclasses #2593 — Replace web-api error interfaces with proper Error subclasses
• chore: bump package version for release candidate #2595 — Bump package versions for release candidate
• feat(socket-mode): replace error interfaces with proper Error subclasses #2596 — Replace socket-mode error interfaces with proper Error subclasses

[changeset-bot]

🦋 Changeset detected

Latest commit: e89c298

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 8 packages

Name	Type
@slack/cli-hooks	Major
@slack/cli-test	Major
@slack/logger	Major
@slack/oauth	Major
@slack/socket-mode	Major
@slack/types	Major
@slack/web-api	Major
@slack/webhook	Major

Not sure what this means? Click here to learn what changesets are.

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

[codecov]

Codecov Report

❌ Patch coverage is 94.64012% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.17%. Comparing base (c37b47e) to head (e89c298).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2603      +/-   ##
==========================================
+ Coverage   89.04%   89.17%   +0.12%     
==========================================
  Files          65       65              
  Lines       10436    10339      -97     
  Branches      468      474       +6     
==========================================
- Hits         9293     9220      -73     
+ Misses       1120     1091      -29     
- Partials       23       28       +5     

Flag	Coverage Δ
cli-hooks	89.17% <94.64%> (+0.12%)	⬆️
cli-test	89.17% <94.64%> (+0.12%)	⬆️
logger	89.17% <94.64%> (+0.12%)	⬆️
oauth	89.17% <94.64%> (+0.12%)	⬆️
socket-mode	89.17% <94.64%> (+0.12%)	⬆️
web-api	89.17% <94.64%> (+0.12%)	⬆️
webhook	89.17% <94.64%> (+0.12%)	⬆️

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.

[zimeg]

@WilliamBergamin LGTM! Huge thanks on getting this to the finish line 🏁

Lots of neat features arriving near!