Bolt v3 ‐ v4 Migration Guide

This migration guide helps you transition an application written using the v3.x series of the @slack/bolt package to the v4.x series. This guide focuses specifically on the breaking changes to help get your existing app up and running as quickly as possible.

Installation

At this time, bolt-js 4.0 is still in release candidacy:

npm install @slack/bolt@4.0.0rc

@slack/bolt v4 changes

Overview

• Support for node v14 and v16 have been officially dropped, as these node versions have been EOL'ed.
• *MiddlewareArgs interfaces, modeling middleware arguments for different kinds of Slack event payloads processed by bolt apps, have been improved.
• For those using the ExpressReceiver, express has been upgraded from v4 to v5.
• The Web API client, @slack/web-api, has been upgraded from v6 to v7.
• The type KnownKeys has been removed.
• The SocketModeFunctions class with a single static method instead now directly exports the single defaultProcessEventErrorHandler method from it.
• Some of the built-in middleware functions like ignoreSelf and directMention have had their APIs changed to create a consistent middleware style.
• The AwsEvent interface has changed.
• Deprecated methods, modules and properties in v3 were removed.

Detailed migrations

If any of the above changes affect you, please see the following sections for guidance on how to migrate to v4 as smoothly as possible.

Middleware argument types

Many middleware argument 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: 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 type of undefined. Those of us trying to build generic middleware utilities would have to deal with TypeScript 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. 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 in 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!

express v5 upgrade

For those building bolt-js apps using the ExpressReceiver, the packaged express version has been upgraded to v5. Best to check the list of breaking changes in express v5 and keep tabs on express#5944, which tracks the creation of an express v4 -> v5 migration guide.

@slack/web-api v7 upgrade

All bolt handlers are provided a convenience client argument. The bundled version of @slack/web-api, the package that powers this convenience client, has been upgraded from v6 to v7. More APIs! Better argument type safety! And a whole slew of other changes, too. Many of these changes won't affect JavaScript application builders, but if you are building a bolt app using TypeScript, you may see some compilation issues. Head over to the @slack/web-api v6 -> v7 migration guide to get the details on what changed and how to migrate to v7.

KnownKeys removed

SocketModeFunctions class disassembled

Built-in middleware changes

AwsEvent interface changes

Removed deprecations