feat: Bolt version 5

[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

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

---

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",
+  "node": ">=20",
 }

Action: Upgrade your runtime to Node.js 20+ 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

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

---

7. 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'
  }
});

---

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
2. Update your dependency: npm install @slack/bolt@5.0.0
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
6. Update error handling — replace error.code === 'slack_webapi_platform_error' string checks with instanceof checks
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: 397b7d6

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

❌ Patch coverage is 98.21429% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 94.20%. Comparing base (ba4deb6) to head (397b7d6).

Files with missing lines	Patch %	Lines
src/App.ts	96.15%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2940      +/-   ##
==========================================
- Coverage   94.38%   94.20%   -0.19%     
==========================================
  Files          44       42       -2     
  Lines        7857     7295     -562     
  Branches      699      668      -31     
==========================================
- Hits         7416     6872     -544     
+ Misses        435      417      -18     
  Partials        6        6              

☔ View full report in Codecov by Sentry.
📢 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.