Skip to content

Bolt v3 ‐ v4 Migration Guide

Jump to bottom
Fil Maj edited this page Oct 9, 2024 · 15 revisions

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.0-rc.4

🚨 @slack/bolt v4 breaking changes

FYI

  • ⬆️ Support for node v14 and v16 have been officially dropped, as these node versions have been EOL'ed.
  • 🚳 A variety of types, methods and constants related to Steps from Apps have been deprecated. These have been gently deposited into their final resting place 🥀. If you are still using these, you should now get a warning in your IDE about that, and expect them to be removed in v5 of bolt-js.

Overview

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!

@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.

@slack/socket-mode v2 upgrade

While the breaking changes from this upgrade should be shielded from bolt-js users, if you are using the SocketModeReceiver or setting socketMode: true, and attach custom code to how the SocketModeReceiver operates, we suggest you read through the @slack/socket-mode v1 -> v2 migration guide, just in case.

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/types exported as a named types export

We are slowly moving more core Slack domain object types and interfaces into the utility package @slack/types. For example, recently we shuffled Slack Events API payloads from bolt-js over to @slack/types. Similar moves will continue as we improve bolt-js. Ideally, we'd like for everyone - ourselves as Slack employees but of course you as well, dear developer - to leverage these types when modeling Slack domain objects.

Anyways, previously we simply export * from '@slack/types'; in bolt-js. We've tweaked this somewhat, it is now: export * as types from '@slack/types';. So if you are using @slack/types when packaged within bolt-js, please update your references to something like:

import { App, type types } from '@slack/bolt';

// Now you can get references to e.g. `types.BotMessageEvent`

SocketModeFunctions class disassembled

If you previously imported the SocketModeFunctions class, you likely only did so to get a reference to the single static method available on this class: defaultProcessEventErrorHandler. Instead, you can now directly import the named defaultProcessEventErrorHandler export instead.

Built-in middleware changes

Two built-in middlewares, ignoreSelf and directMention, previously needed to be invoked as a function in order to return a middleware. These two built-in middlewares were not parameterized in the sense that they should just be used directly; as a result, you no longer should invoke them and instead pass them directly.

As an example, previously you may have leveraged directMention like this:

app.message(directMention(), async (args) => {
  // my handler here
});

Instead, you should now use it like so:

app.message(directMention, async (args) => {
  // my handler here
});

AwsEvent interface changes

For users of the AwsLambdaReceiver and TypeScript, we modeled, rather simplistically, the AWS event payloads: liberal use of any and in certain cases, incorrect property types altogether. We've now improved these to be more accurate and to take into account the two versions of API Gateway payloads that AWS supports (v1 and v2). Details for these changes are available in #2277.

As for userland changes that may be required, this depends on your use of the AwsEvent interface. The major change here is that it is a union type of V1 and V2 payload structures. Check out the source code and changes in #2277 for details on what each payload version structure looks like and how to adapt your application code to account for these differences.

Removed deprecations

  • The deprecated type KnownKeys was removed. Admittedly, it wasn't very useful: export type KnownKeys<_T> = never;
  • The deprecated types VerifyOptions and OptionsRequest were removed.
  • The deprecated methods extractRetryNum, extractRetryReason, defaultRenderHtmlForInstallPath, renderHtmlForInstallPathandverify` were removed.
Clone this wiki locally