From ab9b7120c7a614c3acbbdbcafe226e458baffa69 Mon Sep 17 00:00:00 2001 From: Luke Russell Date: Wed, 27 May 2026 10:22:49 -0700 Subject: [PATCH 1/3] go --- docs/english/migration/migration-v5.md | 287 +++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 docs/english/migration/migration-v5.md diff --git a/docs/english/migration/migration-v5.md b/docs/english/migration/migration-v5.md new file mode 100644 index 000000000..24fd6f360 --- /dev/null +++ b/docs/english/migration/migration-v5.md @@ -0,0 +1,287 @@ +--- +sidebar_label: Migrating to v5 +--- + +# Migrating @slack/bolt from v4 to v5 + +_Minimum Node.js version: 20_ + +Bolt v5 follows the Node Slack SDK's shift from [axios](https://www.npmjs.com/package/axios) to the native [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). It also removes the deprecated Workflow Steps feature (retired by Slack in September 2024) and raises the minimum Node.js version to 20. + +All internal `@slack/*` dependencies have been bumped to their next major versions: `@slack/web-api` ^8, `@slack/socket-mode` ^3, `@slack/oauth` ^4, `@slack/logger` ^5, and `@slack/types` ^3. These bring proper error class hierarchies, native fetch transport, and undici-based WebSocket connections. + +If your app doesn't use proxy/TLS configuration, Workflow Steps, or inspect `respond()` return values, this upgrade is likely a version bump and done. + +--- + +## Breaking Changes + + +### 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 removed the `agent` and `clientTls` options from `AppOptions` + +You should configure transport via `clientOptions.fetch` or use the Node.js built-in proxy support. + +**Before (v4):** + +```typescript +import { App } from '@slack/bolt'; +import { HttpsProxyAgent } from 'https-proxy-agent'; +import fs from 'node:fs'; + +const app = new App({ + token: process.env.SLACK_BOT_TOKEN, + signingSecret: process.env.SLACK_SIGNING_SECRET, + agent: new HttpsProxyAgent('http://corporate.proxy:8080'), + clientTls: { + cert: fs.readFileSync('/path/to/client-cert.pem'), + key: fs.readFileSync('/path/to/client-key.pem'), + }, +}); +``` + +#### Preferred: Built-in proxy support + +Node.js can read proxy env vars natively via [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv). Call it once at startup and `globalThis.fetch` routes through your proxy automatically, no extra packages needed. + + +##### Option A: programmatically call once at startup + +```typescript +import http from 'node:http'; +import { App } from '@slack/bolt'; + +http.setGlobalProxyFromEnv(); + +const app = new App({ + token: process.env.SLACK_BOT_TOKEN, + signingSecret: process.env.SLACK_SIGNING_SECRET, +}); +``` + +##### Option B: use an environment variable + +```bash +NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://corporate.proxy:8080 node app.js +``` + +```typescript +import { App } from '@slack/bolt'; + +// No proxy configuration needed — globalThis.fetch respects the environment +const app = new App({ + token: process.env.SLACK_BOT_TOKEN, + signingSecret: process.env.SLACK_SIGNING_SECRET, +}); +``` + +#### Alternative: use an undici dispatcher for proxy + TLS + +If you need per-client configuration, use the `clientOptions.fetch` option with an [undici](https://undici.nodejs.org/) dispatcher: + +```typescript +import { App } from '@slack/bolt'; +import { fetch, ProxyAgent, Agent } from 'undici'; +import fs from 'node:fs'; + +// Proxy only +const proxyDispatcher = new ProxyAgent('http://corporate.proxy:8080'); + +// TLS only +const tlsDispatcher = new Agent({ + connect: { + cert: fs.readFileSync('/path/to/client-cert.pem'), + key: fs.readFileSync('/path/to/client-key.pem'), + ca: fs.readFileSync('/path/to/ca-cert.pem'), + }, +}); + +const app = new App({ + token: process.env.SLACK_BOT_TOKEN, + signingSecret: process.env.SLACK_SIGNING_SECRET, + clientOptions: { + fetch: (url, init) => fetch(url, { ...init, dispatcher: tlsDispatcher }), + }, +}); +``` + +--- + +### We've updated `SocketModeReceiver` to use `dispatcher` instead of proxy agents + +The `SocketModeReceiver` now accepts a `dispatcher` option (from `@slack/socket-mode` v3) for unified proxy and TLS configuration of both the WebSocket connection and HTTP API calls ([#2929](https://github.com/slackapi/bolt-js/pull/2929)). + +**Before (v4):** + +```typescript +import { App } from '@slack/bolt'; +import { HttpsProxyAgent } from 'https-proxy-agent'; + +const app = new App({ + token: process.env.SLACK_BOT_TOKEN, + appToken: process.env.SLACK_APP_TOKEN, + socketMode: true, + agent: new HttpsProxyAgent('http://corporate.proxy:8080'), +}); +``` + +#### Preferred: Built-in proxy support + +Node.js can read proxy env vars natively via [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv). Call it once at startup and both the WebSocket connection and API calls route through your proxy automatically. + +```typescript +import http from 'node:http'; +import { App } from '@slack/bolt'; + +http.setGlobalProxyFromEnv(); + +const app = new App({ + token: process.env.SLACK_BOT_TOKEN, + appToken: process.env.SLACK_APP_TOKEN, + socketMode: true, +}); +``` + +#### Alternative: undici dispatcher for proxy + TLS + +If you need per-client configuration, pass a `dispatcher` to both the `SocketModeReceiver` (for the WebSocket connection) and `clientOptions.fetch` (for the app's internal `WebClient` API calls): + +```typescript +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. Workflow Steps removed entirely + +The `WorkflowStep` class, `app.step()` method, and all related types have been deleted ([#2928](https://github.com/slackapi/bolt-js/pull/2928)). Slack retired the Steps from Apps feature in September 2024. Use `app.function()` with custom functions instead. + +Remove any imports of `WorkflowStep` or `WorkflowStepEdit` — they no longer exist. + +--- + +### 5. `respond()` returns native `Response` instead of axios response + +The `respond()` utility now uses native fetch internally ([#2929](https://github.com/slackapi/bolt-js/pull/2929)). If you inspect the return value, the shape has changed from an axios response to a standard Fetch [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response). + +**Before (v4):** + +```typescript +app.command('/ticket', async ({ command, ack, respond }) => { + await ack(); + const result = await respond(`Ticket created: ${command.text}`); + // result was an AxiosResponse + console.log(result.status); // 200 + console.log(result.data); // response body (pre-parsed) + console.log(result.headers); // AxiosHeaders object +}); +``` + +**After (v5):** + +```typescript +app.command('/ticket', async ({ command, ack, respond }) => { + await ack(); + const result = await respond(`Ticket created: ${command.text}`); + // result is a native Fetch Response + console.log(result.status); // 200 + console.log(await result.text()); // response body (call .text() or .json()) + console.log(result.headers); // Headers object +}); +``` + +If you're just calling `await respond(...)` without using the return value (the common case), no changes are needed. + +--- + +### 6. Upgraded `@slack/*` dependencies + +All internal `@slack/*` packages have been bumped to their next major versions ([#2929](https://github.com/slackapi/bolt-js/pull/2929)). If you import from these packages directly, check their respective migration guides: + +| Dependency | v4 range | v5 range | Migration guide | +| --- | --- | --- | --- | +| `@slack/web-api` | ^7 | ^8 | [web-api v8 migration](./web-api-v8-migration.md) | +| `@slack/socket-mode` | ^2 | ^3 | [socket-mode v3 migration](./socket-mode-v3-migration.md) | +| `@slack/oauth` | ^3 | ^4 | — | +| `@slack/logger` | ^4 | ^5 | — | +| `@slack/types` | ^2 | ^3 | — | + +Key inherited changes: + +- **`@slack/web-api` v8** removes `agent`, `tls`, `requestInterceptor`, and `adapter` options from `WebClientOptions`. If you pass any of these via `clientOptions` in your `App` constructor, they no longer exist — use `clientOptions.fetch` instead. +- **`@slack/web-api` v8** errors are now proper `Error` subclasses with `instanceof` support. See the [web-api v8 error handling section](./web-api-v8-migration.md#7-error-handling-overhaul). +- **`@slack/socket-mode` v3** replaces the `ws` library with undici's WebSocket implementation. See the [socket-mode v3 migration](./socket-mode-v3-migration.md). + +--- + +### 7. Error handling improvements + +Bolt v5 leverages the new error classes from `@slack/web-api` v8 ([#2930](https://github.com/slackapi/bolt-js/pull/2930)). Errors thrown by the internal `WebClient` are now proper `Error` subclasses — `instanceof` checks work and TypeScript narrows types correctly. + +**Before (v4):** + +```typescript +import { App } from '@slack/bolt'; + +const app = new App({ /* ... */ }); + +app.error(async ({ error }) => { + if ('code' in error && error.code === 'slack_webapi_platform_error') { + console.log((error as any).data?.error); + } +}); +``` + +**After (v5):** + +```typescript +import { App } from '@slack/bolt'; +import { WebAPIPlatformError, WebAPIRequestError } from '@slack/web-api'; + +const app = new App({ /* ... */ }); + +app.error(async ({ error }) => { + if (error instanceof WebAPIPlatformError) { + console.log(error.data.error); // e.g. 'channel_not_found' + } else if (error instanceof WebAPIRequestError) { + console.log(error.cause); // the underlying fetch/network error + } +}); +``` + +--- + +## New Features + +### `dispatcher` option on `SocketModeReceiver` + +Unified proxy and TLS configuration for both WebSocket connections and HTTP API calls. Pass any undici-compatible dispatcher. See [Breaking Change #3](#3-socketmodereceiver-uses-dispatcher-instead-of-proxy-agents). + +### Error classes with `instanceof` support + +Both Bolt's own errors (e.g., `AppInitializationError`, `AuthorizationError`) and the underlying `@slack/web-api` errors now properly extend `Error`. Use `instanceof` for type-safe error handling instead of string comparisons on `error.code`. + +### `app.function()` as the sole custom step mechanism + +While `app.function()` already existed in Bolt v4, it is now the only way to handle custom function executions (replacing the removed `app.step()` / `WorkflowStep`). It provides `complete()` and `fail()` callbacks for signaling outcomes, and `inputs` for accessing function parameters. \ No newline at end of file From eb4cddb667439ab5e30a0336e16739ab5e60624b Mon Sep 17 00:00:00 2001 From: Luke Russell Date: Wed, 27 May 2026 12:52:10 -0700 Subject: [PATCH 2/3] go --- docs/english/migration/migration-v5.md | 54 ++++++++++++-------------- 1 file changed, 25 insertions(+), 29 deletions(-) diff --git a/docs/english/migration/migration-v5.md b/docs/english/migration/migration-v5.md index 24fd6f360..09ae8f8dc 100644 --- a/docs/english/migration/migration-v5.md +++ b/docs/english/migration/migration-v5.md @@ -112,9 +112,9 @@ const app = new App({ --- -### We've updated `SocketModeReceiver` to use `dispatcher` instead of proxy agents +### We've updated the `SocketModeReceiver` class to accept a `dispatcher` option instead of proxy agents -The `SocketModeReceiver` now accepts a `dispatcher` option (from `@slack/socket-mode` v3) for unified proxy and TLS configuration of both the WebSocket connection and HTTP API calls ([#2929](https://github.com/slackapi/bolt-js/pull/2929)). +The `SocketModeReceiver` class now accepts a `dispatcher` option for unified proxy and TLS configuration of both the WebSocket connection and HTTP API calls. **Before (v4):** @@ -130,9 +130,9 @@ const app = new App({ }); ``` -#### Preferred: Built-in proxy support +#### Preferred: Use built-in proxy support -Node.js can read proxy env vars natively via [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv). Call it once at startup and both the WebSocket connection and API calls route through your proxy automatically. +Node.js can read proxy environment variables natively via [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv). Call it once at startup and both the WebSocket connection and API calls route through your proxy automatically. ```typescript import http from 'node:http'; @@ -147,7 +147,7 @@ const app = new App({ }); ``` -#### Alternative: undici dispatcher for proxy + TLS +#### Alternative: Use a undici dispatcher for proxy and TLS If you need per-client configuration, pass a `dispatcher` to both the `SocketModeReceiver` (for the WebSocket connection) and `clientOptions.fetch` (for the app's internal `WebClient` API calls): @@ -173,17 +173,18 @@ const app = new App({ --- -### 4. Workflow Steps removed entirely +### We've entirely removed Workflow Steps from Apps + +The Workflow Steps from Apps feature [was retired in September 2024](/changelog/2023-08-workflow-steps-from-apps-step-back/). The `WorkflowStep` class, `app.step()` method, and all related types have been deleted from Bolt for JS. You should remove any imports of `WorkflowStep` or `WorkflowStepEdit`. -The `WorkflowStep` class, `app.step()` method, and all related types have been deleted ([#2928](https://github.com/slackapi/bolt-js/pull/2928)). Slack retired the Steps from Apps feature in September 2024. Use `app.function()` with custom functions instead. +Use the `app.function()` method with custom functions instead. -Remove any imports of `WorkflowStep` or `WorkflowStepEdit` — they no longer exist. --- -### 5. `respond()` returns native `Response` instead of axios response +### The `respond()` utility returns native `Response` instead of axios response -The `respond()` utility now uses native fetch internally ([#2929](https://github.com/slackapi/bolt-js/pull/2929)). If you inspect the return value, the shape has changed from an axios response to a standard Fetch [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response). +The `respond()` utility now uses native fetch internally. If you inspect the return value, the shape has changed from an axios response to a standard Fetch [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response). **Before (v4):** @@ -215,29 +216,24 @@ If you're just calling `await respond(...)` without using the return value (the --- -### 6. Upgraded `@slack/*` dependencies +### We've upgraded the Node Slack SDK dependencies -All internal `@slack/*` packages have been bumped to their next major versions ([#2929](https://github.com/slackapi/bolt-js/pull/2929)). If you import from these packages directly, check their respective migration guides: +All Node Slack SDK packages have been bumped to their next major versions. -| Dependency | v4 range | v5 range | Migration guide | -| --- | --- | --- | --- | -| `@slack/web-api` | ^7 | ^8 | [web-api v8 migration](./web-api-v8-migration.md) | -| `@slack/socket-mode` | ^2 | ^3 | [socket-mode v3 migration](./socket-mode-v3-migration.md) | -| `@slack/oauth` | ^3 | ^4 | — | -| `@slack/logger` | ^4 | ^5 | — | -| `@slack/types` | ^2 | ^3 | — | +* The `logger` package has been updated to v5. +* The `oauth` package has been updated to v4. +* The `types` package has been updated to v3. -Key inherited changes: +Three packages have more substantial breaking changes: -- **`@slack/web-api` v8** removes `agent`, `tls`, `requestInterceptor`, and `adapter` options from `WebClientOptions`. If you pass any of these via `clientOptions` in your `App` constructor, they no longer exist — use `clientOptions.fetch` instead. -- **`@slack/web-api` v8** errors are now proper `Error` subclasses with `instanceof` support. See the [web-api v8 error handling section](./web-api-v8-migration.md#7-error-handling-overhaul). -- **`@slack/socket-mode` v3** replaces the `ws` library with undici's WebSocket implementation. See the [socket-mode v3 migration](./socket-mode-v3-migration.md). +* The `socket-mode` package has been updated to v3. See the guide on [migrating @slack/socket-mode from v2 to v3](/tools/node-slack-sdk/migration/socket-mode/migrating-socket-mode-package-to-v3) for handling breaking changes. +* The `web-api` package has been updated to v8. See the guide on [migrating @slack/web-api from v7 to v8](/tools/node-slack-sdk/migration/web-api/migrating-web-api-package-to-v8) for handling breaking changes. --- -### 7. Error handling improvements +### 7. We've improved error handling throughout -Bolt v5 leverages the new error classes from `@slack/web-api` v8 ([#2930](https://github.com/slackapi/bolt-js/pull/2930)). Errors thrown by the internal `WebClient` are now proper `Error` subclasses — `instanceof` checks work and TypeScript narrows types correctly. +This version of Bolt leverages the new error classes from v8 of the `@slack/web-api` Node Slack SDK package. Errors thrown by the internal `WebClient` are now proper `Error` subclasses. **Before (v4):** @@ -274,14 +270,14 @@ app.error(async ({ error }) => { ## New Features -### `dispatcher` option on `SocketModeReceiver` +### We've added a `dispatcher` option to the `SocketModeReceiver` class Unified proxy and TLS configuration for both WebSocket connections and HTTP API calls. Pass any undici-compatible dispatcher. See [Breaking Change #3](#3-socketmodereceiver-uses-dispatcher-instead-of-proxy-agents). -### Error classes with `instanceof` support +### We'ved added `instanceof` support to error classes -Both Bolt's own errors (e.g., `AppInitializationError`, `AuthorizationError`) and the underlying `@slack/web-api` errors now properly extend `Error`. Use `instanceof` for type-safe error handling instead of string comparisons on `error.code`. +Both Bolt's own errors (e.g., `AppInitializationError`, `AuthorizationError`) and the underlying `@slack/web-api` Node Slack SDK package errors now properly extend `Error`. Use `instanceof` for type-safe error handling instead of string comparisons on `error.code`. -### `app.function()` as the sole custom step mechanism +### We've made `app.function()` the sole custom step mechanism While `app.function()` already existed in Bolt v4, it is now the only way to handle custom function executions (replacing the removed `app.step()` / `WorkflowStep`). It provides `complete()` and `fail()` callbacks for signaling outcomes, and `inputs` for accessing function parameters. \ No newline at end of file From 1975fbdf9472e29ef88d572546f6865f0b7e391d Mon Sep 17 00:00:00 2001 From: Luke Russell Date: Wed, 27 May 2026 14:34:21 -0700 Subject: [PATCH 3/3] go --- docs/english/migration/migration-v5.md | 69 ++++++++++++-------------- 1 file changed, 33 insertions(+), 36 deletions(-) diff --git a/docs/english/migration/migration-v5.md b/docs/english/migration/migration-v5.md index 09ae8f8dc..007ab6830 100644 --- a/docs/english/migration/migration-v5.md +++ b/docs/english/migration/migration-v5.md @@ -6,26 +6,25 @@ sidebar_label: Migrating to v5 _Minimum Node.js version: 20_ -Bolt v5 follows the Node Slack SDK's shift from [axios](https://www.npmjs.com/package/axios) to the native [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). It also removes the deprecated Workflow Steps feature (retired by Slack in September 2024) and raises the minimum Node.js version to 20. +Bolt for JS v5 follows the Node Slack SDK's shift from axios to the native [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). It also removes the deprecated Workflow Steps feature (retired by Slack in September 2024) and raises the minimum Node.js version to 20. -All internal `@slack/*` dependencies have been bumped to their next major versions: `@slack/web-api` ^8, `@slack/socket-mode` ^3, `@slack/oauth` ^4, `@slack/logger` ^5, and `@slack/types` ^3. These bring proper error class hierarchies, native fetch transport, and undici-based WebSocket connections. +All internal `@slack/*` Node Slack SDK dependencies have been bumped to their next major versions. See the section below on [Upgrading the Node Slack SDK dependencies]({#node-slack-sdk-dependencies}) for information and migration instructions. -If your app doesn't use proxy/TLS configuration, Workflow Steps, or inspect `respond()` return values, this upgrade is likely a version bump and done. +If your app doesn't use proxy/TLS configuration or inspect `respond()` utility function return values, this upgrade is likely a version bump and done. --- -## Breaking Changes +## Breaking Changes {#breaking-changes} - -### We've raised the minimum Node.js version to 20 +### We've raised the minimum Node.js version to 20 {#minimum-node-version} We've dropped support for Node.js 18. Node.js 20 or later is required. --- -### We've removed the `agent` and `clientTls` options from `AppOptions` +### We've removed the `agent` and `clientTls` options from the `AppOptions` interface {#removed-agent-clienttls} -You should configure transport via `clientOptions.fetch` or use the Node.js built-in proxy support. +You should configure transport via the `clientOptions.fetch` option or use the Node.js built-in proxy support. **Before (v4):** @@ -45,12 +44,11 @@ const app = new App({ }); ``` -#### Preferred: Built-in proxy support - -Node.js can read proxy env vars natively via [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv). Call it once at startup and `globalThis.fetch` routes through your proxy automatically, no extra packages needed. +#### Preferred: Built-in proxy support {#built-in-proxy-support} +Node.js can read proxy environment variables natively via [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv). Call it once at startup and `globalThis.fetch` routes through your proxy automatically, no extra packages needed. -##### Option A: programmatically call once at startup +##### Option A: programmatically call once at startup {#programmatically-call-startup} ```typescript import http from 'node:http'; @@ -64,7 +62,7 @@ const app = new App({ }); ``` -##### Option B: use an environment variable +##### Option B: use an environment variable {#use-an-environment-variable} ```bash NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://corporate.proxy:8080 node app.js @@ -80,9 +78,9 @@ const app = new App({ }); ``` -#### Alternative: use an undici dispatcher for proxy + TLS +#### Alternative: use an undici `Dispatcher` instance for proxy and TLS {#undici-dispatcher-proxy-tls} -If you need per-client configuration, use the `clientOptions.fetch` option with an [undici](https://undici.nodejs.org/) dispatcher: +If you need per-client configuration, use the `clientOptions.fetch` option with an [undici](https://undici.nodejs.org/) `Dispatcher` instance: ```typescript import { App } from '@slack/bolt'; @@ -112,9 +110,9 @@ const app = new App({ --- -### We've updated the `SocketModeReceiver` class to accept a `dispatcher` option instead of proxy agents +### We've updated the `SocketModeReceiver` class to accept a `dispatcher` option instead of proxy agents {#socketmodereceiver-dispatcher} -The `SocketModeReceiver` class now accepts a `dispatcher` option for unified proxy and TLS configuration of both the WebSocket connection and HTTP API calls. +The `SocketModeReceiver` class now accepts a `dispatcher` option for unified proxy and TLS configuration of both the WebSocket connection and HTTP API calls. The `dispatcher` option accepts any undici-compatible `Dispatcher` instance. **Before (v4):** @@ -130,7 +128,7 @@ const app = new App({ }); ``` -#### Preferred: Use built-in proxy support +#### Preferred: Use built-in proxy support {#socketmode-built-in-proxy-support} Node.js can read proxy environment variables natively via [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv). Call it once at startup and both the WebSocket connection and API calls route through your proxy automatically. @@ -147,9 +145,9 @@ const app = new App({ }); ``` -#### Alternative: Use a undici dispatcher for proxy and TLS +#### Alternative: Use an undici `Dispatcher` instance for proxy and TLS {#socketmode-undici-dispatcher-proxy-tls} -If you need per-client configuration, pass a `dispatcher` to both the `SocketModeReceiver` (for the WebSocket connection) and `clientOptions.fetch` (for the app's internal `WebClient` API calls): +If you need per-client configuration, pass a `dispatcher` option to both the `SocketModeReceiver` class (for the WebSocket connection) and the `clientOptions.fetch` option (for the app's internal `WebClient` class API calls): ```typescript import { App, SocketModeReceiver } from '@slack/bolt'; @@ -173,18 +171,17 @@ const app = new App({ --- -### We've entirely removed Workflow Steps from Apps +### We've removed Workflow Steps from Apps {#removed-workflow-steps} -The Workflow Steps from Apps feature [was retired in September 2024](/changelog/2023-08-workflow-steps-from-apps-step-back/). The `WorkflowStep` class, `app.step()` method, and all related types have been deleted from Bolt for JS. You should remove any imports of `WorkflowStep` or `WorkflowStepEdit`. +The Workflow Steps from Apps feature [was retired in September 2024](/changelog/2023-08-workflow-steps-from-apps-step-back/). The `WorkflowStep` class, the `app.step()` method, and all related types have been deleted from Bolt for JS. You should remove any imports of the `WorkflowStep` class or the `WorkflowStepEdit` type. Use the `app.function()` method with custom functions instead. - --- -### The `respond()` utility returns native `Response` instead of axios response +### We've updated the `respond()` utility function to return a native `Response` object {#respond-returns-fetch-response} -The `respond()` utility now uses native fetch internally. If you inspect the return value, the shape has changed from an axios response to a standard Fetch [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response). +The `respond()` utility function now uses native fetch internally. If you inspect the return value, the shape has changed from an `AxiosResponse` object to a standard Fetch [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object. **Before (v4):** @@ -212,11 +209,11 @@ app.command('/ticket', async ({ command, ack, respond }) => { }); ``` -If you're just calling `await respond(...)` without using the return value (the common case), no changes are needed. +If you're only calling `await respond(...)` without using the return value (the common case), no changes are needed. --- -### We've upgraded the Node Slack SDK dependencies +### We've upgraded the Node Slack SDK dependencies {#node-slack-sdk-dependencies} All Node Slack SDK packages have been bumped to their next major versions. @@ -231,9 +228,9 @@ Three packages have more substantial breaking changes: --- -### 7. We've improved error handling throughout +### We've improved error handling throughout {#error-handling} -This version of Bolt leverages the new error classes from v8 of the `@slack/web-api` Node Slack SDK package. Errors thrown by the internal `WebClient` are now proper `Error` subclasses. +This version of Bolt leverages the new error classes from v8 of the `@slack/web-api` Node Slack SDK package. Errors thrown by the internal `WebClient` class are now proper `Error` subclasses. **Before (v4):** @@ -268,16 +265,16 @@ app.error(async ({ error }) => { --- -## New Features +## New Features {#new-features} -### We've added a `dispatcher` option to the `SocketModeReceiver` class +### We've added a `dispatcher` option to the `SocketModeReceiver` class {#new-dispatcher-option} -Unified proxy and TLS configuration for both WebSocket connections and HTTP API calls. Pass any undici-compatible dispatcher. See [Breaking Change #3](#3-socketmodereceiver-uses-dispatcher-instead-of-proxy-agents). +Unified proxy and TLS configuration for both WebSocket connections and HTTP API calls. Pass any undici-compatible `Dispatcher` instance. See the section above on [the updated `SocketModeReceiver` class](#socketmodereceiver-dispatcher). -### We'ved added `instanceof` support to error classes +### We've added `instanceof` operator support to error classes {#instanceof-errors} -Both Bolt's own errors (e.g., `AppInitializationError`, `AuthorizationError`) and the underlying `@slack/web-api` Node Slack SDK package errors now properly extend `Error`. Use `instanceof` for type-safe error handling instead of string comparisons on `error.code`. +Both Bolt's own error classes (e.g., `AppInitializationError`, `AuthorizationError`) and the underlying `@slack/web-api` Node Slack SDK package error classes (e.g., `WebAPIPlatformError`, `WebAPIRequestError`) now properly extend the `Error` class. Use the `instanceof` operator for type-safe error handling instead of string comparisons on the `error.code` property. -### We've made `app.function()` the sole custom step mechanism +### We've made the `app.function()` method the sole custom step mechanism {#app-function} -While `app.function()` already existed in Bolt v4, it is now the only way to handle custom function executions (replacing the removed `app.step()` / `WorkflowStep`). It provides `complete()` and `fail()` callbacks for signaling outcomes, and `inputs` for accessing function parameters. \ No newline at end of file +While the `app.function()` method already existed in Bolt v4, it is now the only way to handle custom function executions (replacing the removed `app.step()` method and `WorkflowStep` class). It provides `complete()` and `fail()` callback functions for signaling outcomes, and an `inputs` property for accessing function parameters.