Skip to content

Migration Guide for web‐api v7

Jump to bottom
Fil Maj edited this page Dec 12, 2023 · 20 revisions

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

  • (todo: link to release notes) Learn about all the new features in our v7.0.0 release notes.

@slack/web-api v7 Changes

This release focusses on the type safety of Slack HTTP API method arguments provided by @slack/web-api.

This release broadly is composed of three significant changes to the web-api codebase:

  1. 🚨 Breaking changes to API method arguments,
  2. 📝 Adding a ton of new hand-written JSDocs to provide useful method-specific context and descriptions directly in your IDE, and
  3. 🧑‍🔬 Type tests for method arguments, formalizing some of the co-dependencies and constraints unique to specific API methods

Let's dive into these three sets of changes and begin with the 🚨 Breaking Changes 🚨 to make sure we set you all up for success and an easy migration to v7.

🚨 Breaking Changes 🚨

🚨 All Web API methods no longer allow arbitrary arguments 🚨

Previously, the arguments provided to specific methods extended from a WebAPICallOptions TypeScript interface. This interface made all API arguments effectively type un-safe: you could place whatever properties you wanted on arguments, and the TypeScript compiler would be fine with it.

In v7, in an attempt to improve type safety, we have removed this argument. As a result, if you were using unknown or publicly undocumented API arguments, you will now see a TypeScript compiler error. If you really want to send unsupported arguments to our APIs, you will have to tell TypeScript "no, trust me, I really want to do this" using the // @ts-expect-error directive.

If you find an issue with any of our method arguments, please let us know by filing an issue in this project!

🚨 **Many Web API methods have new, sometimes quite-specific, type constraints

A full and detailed list follows, with migration steps where applicable.

This change ties into closely with the third change discussed above (3. 🧑‍🔬 Type tests for method arguments), as all of these constraints are exhaustively tested under test/types/methods. When in doubt, read these tests to understand exactly what combination of arguments are expected to raise a TypeScript error, and which ones are not.

  • TODO: document all the method changes 🤪

📝 Adding JSDoc to methods and method arguments 📝

🧑‍🔬 Type tests for method arguments 🧑‍🔬

Clone this wiki locally