releases.shpreview
SlackSlack/Bolt JS

@slack/bolt@4.0.0

October 17, 2024Bolt JSView original ↗

Bolt v4

What's Changed

New Features

Support for Agents & Assistants is now available!

Bolt now offers a simple and intuitive way to create an Agent/Assistant using the new Assistant class. Simply include the required callbacks and add the assistant to your App instance. Get up and running even quicker with a working, out-of-the-box example that utilizes OpenAI here.

Breaking Changes

We have prepared a migration guide to help BoltJS consumers migrate their Bolt v3 apps to v4.

While a few breaking changes were introduced, we don't expect a majority of bolt v3 users to require changing their apps to upgrade to v4. More complex apps may need a few tweaks. TL;DR is: if your bolt v3 app is built with TypeScript, or uses the ExpressReceiver or the AwsLambdaReceiver, or your app used previously-deprecated types or functions, best to read the migration guide.

Middleware Type Changes

In bolt we have a set of Slack*MiddlewareArgs types: for events, shortcuts, commands, and so on. They 'wrap' the underlying event payloads with additional middleware-relevant bits like a next() method, a context object for devs to augment, and so on.

Many of these types, for example the SlackEventMiddlewareArgs type, previously used a conditional to sometimes define particular additional helper utilities on the middleware arguments. For example, the say utility, or tacking on a convenience message property for message-event-related payloads. This was problematic in practice in TypeScript situations, not just internally (this change fixes https://github.com/slackapi/bolt-js/issues/2135) within the bolt codebase but for developers as well: when the payload was not of a type that required the extra utility, these properties would be required to exist on the middleware arguments but have a value of undefined. Those of us trying to build generic middleware utilities would have to deal with TS compilation errors and needing to liberally type-cast to avoid these conditional mismatches with undefined.

Instead, these MiddlewareArgs types now conditionally create a type intersection when appropriate in order to provide this conditional-utility-extension mechanism. In practice that looks something like:

type SomeMiddlewareArgs<EventType extends string = string> = {
  // some type in here
} & (EventType extends 'message'
  // If this is a message event, add a `message` property
  ? { message: EventFromType<EventType> }
  : unknown
)

With the above, now when a message payload is wrapped up into middleware arguments, it will contain an appropriate message property, whereas a non-message payload will be intersected with unknown - effectively a type "noop." No more e.g. say: undefined or message: undefined to deal with!

Other Breaking Changes

  • drops node v14 and v16 (are now EOL'ed)
  • express to v4->v5; ExpressReceiver users will be exposed to express v4 -> v5 breaking changes - fixes #2242
  • upgrades to @slack/socket-mode v2; SocketModeReceiver users who have attached custom event listeners to the public socketModeClient directly should read the v1 -> v2 migration guide in case the major upgrade could affect them - fixes #2225
  • upgrades @slack/web-api v7; all users should read the web-api v6->v7 migration guide to see what the scope of breaking changes the client within listeners is affected by
  • removed exported type: KnownKeys
  • @slack/types now exist under a named export types.
  • removed the SocketModeFunctions class that had a single static method on it and instead directly exposed the defaultProcessEventErrorHandler method from it.
  • the built-in middleware functions ignoreSelf and directMention now no longer must be invoked as a method in order to return middleware; instead they are middleware to be used directly. this lines up the API for these built-in middlewares to match the other builtins.
  • AWSReceiver's AwsEvent interface now models event payloads a bit differently; we now properly model AWS API Gateway v1 and v2 payloads separately - fixes #2272
  • remove deprecated methods/modules/properties:
    • OptionsRequest interface
    • authed_users and authed_teams from event payload envelope
    • render-html-for-install-path module
    • verify and VerifyOptions from the verify-request module
    • src/receivers/http-utils.ts module

Non-breaking Changes

  • expose the bundled @slack/web-api dependency under the webApi named export
  • fixed an issue in AwsLambdaReceiver where apps with no registered handlers that processed an incoming event would still log out an error related to not acknowledging the request in time - fixes #2284
  • dependency updates:
    • upgrades raw-body to v3
    • upgrades @slack/oauth to v3
    • removes promise.allsettled since that is natively supported in node since v14
    • moves @types/tsscmp to dev dependencies since that is not exposed to developers

Changelog

Full Changelog: https://github.com/slackapi/bolt-js/compare/@slack/bolt@3.22.0...@slack/bolt@4.0.0

Fetched April 3, 2026