feat: release @slack/bolt@5.0.0

[WilliamBergamin]

Summary

Bolt v5 completes the Node Slack SDK's transition from axios to the native Fetch API, removes the long-deprecated Workflow Steps feature, improves error handling with proper Error subclasses, and raises the minimum Node.js version to 20.

Release candidate: @slack/bolt@5.0.0-rc.2

npm install @slack/bolt@5.0.0-rc.2

---

Why a new major?

Reason	Impact
axios removed from the dependency tree	agent, clientTls options no longer exist; respond() returns native Response
Workflow Steps retired by Slack (Sept 2024)	WorkflowStep, app.step(), and all related types deleted
Node.js 18 reached EOL (2025-04-30)	Runtime requirement raised to Node.js ≥20
@slack/* dependencies bumped to next majors	Inherited breaking changes from web-api v8, socket-mode v3, oauth v4, logger v5, types v3

---

Breaking Changes

1. Minimum Node.js version → 20

 "engines": {
-  "node": ">=18",
-  "npm": ">=8.6.0"
+  "node": ">=20",
+  "npm": ">=9.6.4"
 }

Action: Upgrade your runtime to Node.js 20+ (and npm 9.6.4+) before upgrading Bolt.

---

2. agent and clientTls options removed from AppOptions

These axios-era options no longer exist. For proxy/TLS configuration:

• Zero-code (recommended): Set NODE_USE_ENV_PROXY=1 and HTTPS_PROXY env vars, or call http.setGlobalProxyFromEnv() at startup
• Per-client control: Pass a custom fetch via clientOptions.fetch

Example: undici ProxyAgent

import { App } from '@slack/bolt';
import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent('http://corporate.proxy:8080');

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
  clientOptions: {
    fetch: (url, init) => fetch(url, { ...init, dispatcher }),
  },
});

---

3. SocketModeReceiver:dispatcher replaces proxy agents

Socket Mode now accepts a dispatcher option for unified proxy/TLS on both the WebSocket connection and HTTP API calls.

Example: Socket Mode with proxy

import { App, SocketModeReceiver } from '@slack/bolt';
import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent('http://corporate.proxy:8080');

const receiver = new SocketModeReceiver({
  appToken: process.env.SLACK_APP_TOKEN,
  dispatcher,
});

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  receiver,
  clientOptions: {
    fetch: (url, init) => fetch(url, { ...init, dispatcher }),
  },
});

---

4. WorkflowStep removed entirely

WorkflowStep, app.step(), WorkflowStepEdit, and all related types/error codes have been deleted. Slack retired Steps from Apps in September 2024. Use app.function() with custom functions instead.

---

5. respond() returns native Response

respond() now returns Promise<Response> (Fetch API) instead of Promise<AxiosResponse>. If you inspect the return value:

 const result = await respond('Done!');
-console.log(result.data);         // AxiosResponse.data
+console.log(await result.text()); // Fetch Response body

respond() also now throws a RespondError (importable from @slack/bolt, with a statusCode property) when the response_url request returns a non-2xx status — restoring the throw-on-failure behavior axios provided. If you previously wrapped respond() in a try/catch, you'll now catch a RespondError instead of an AxiosError.

If you only call await respond(...) without reading the return value (the common case), no changes needed.

---

6. Upgraded @slack/* dependencies

Package	v4 range	v5 range
@slack/web-api	^7	^8
@slack/socket-mode	^2	^3
@slack/oauth	^3	^4
@slack/logger	^4	^5
@slack/types	^2	^3

Key inherited changes:

• @slack/web-api v8 removes agent, tls, requestInterceptor, adapter from WebClientOptions
• @slack/web-api v8 errors are proper Error subclasses with instanceof support
• @slack/socket-mode v3 replaces the ws library with undici's native WebSocket

---

Improvements (non-breaking)

Improved error handling

Errors thrown by the internal WebClient are now proper Error subclasses. instanceof checks work correctly and TypeScript narrows types:

import { WebAPIPlatformError, WebAPIRequestError } from '@slack/web-api';

app.error(async ({ error }) => {
  if (error instanceof WebAPIPlatformError) {
    console.log(error.data.error); // e.g. 'channel_not_found'
  }
});

This change is backward-compatible: the web-api error classes still expose .code, so existing error.code === 'slack_webapi_platform_error' string checks continue to work. Switching to instanceof is recommended but optional. (This ships as a minor changeset.)

---

Migration Checklist

For most apps that don't use proxy configuration, Workflow Steps, or inspect respond() return values, this upgrade is a version bump and done:

1. Upgrade Node.js to 20 or later (and npm to 9.6.4 or later)
2. Update your dependency: npm install @slack/bolt@5.0.0-rc.2
3. Remove agent/clientTls from App constructor if present — replace with clientOptions.fetch or env-based proxy
4. Delete WorkflowStep code if any — migrate to app.function() with custom functions
5. Update respond() return handling if you read result.data or result.headers — use Fetch Response methods instead; also note respond() now throws RespondError on non-2xx responses
6. (Optional) Update error handling — you may replace error.code === 'slack_webapi_platform_error' string checks with instanceof checks; the string checks still work
7. Check direct @slack/* imports — if you import from @slack/web-api or @slack/socket-mode directly, review their respective migration guides

---

Included PRs

• chore: drop support for node 18 #2927 — chore: drop support for node 18
• chore: remove deprecated workflow steps references #2928 — chore: remove deprecated workflow steps references
• feat: remove references to axios in favor of fetch #2929 — feat: remove references to axios in favor of fetch
• feat: improve error handling #2930 — feat: improve error handling
• chore: update biome configurations and applied settings #2932 — chore: update biome configurations and applied settings

[changeset-bot]

🦋 Changeset detected

Latest commit: 889d6b4

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

This PR includes changesets to release 1 package

Name	Type
@slack/bolt	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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.33%. Comparing base (602b744) to head (889d6b4).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2940      +/-   ##
==========================================
- Coverage   94.48%   94.33%   -0.15%     
==========================================
  Files          45       43       -2     
  Lines        7900     7360     -540     
  Branches      708      679      -29     
==========================================
- Hits         7464     6943     -521     
+ Misses        428      409      -19     
  Partials        8        8              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mwbrooks]

✅ Huge to see axios removed! 🎉

✏️ @WilliamBergamin I updated the title to feat: release @slack/bolt@5.0.0

🧠 I think we should update the descriptions install command to use the 5.0.0 release instead of the rc release candidate.