Description

Bolt's current TypeScript implementation serves to slow down rather than speed up the developer experience. There is little useful documentation to help developers who wish to write Slack apps in TypeScript.

What type of issue is this? (place an x in one of the [ ])

• bug
• enhancement (feature request)
• question
• documentation related
• example code related
• testing related
• discussion

Requirements (place an x in each of the [ ])

• I've read and understood the Contributing guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.
• I've searched for any related issues and avoided creating a duplicate issue.

Discussion

Currently, Bolt SDK typings are optimized for SDK developers and contributors. They are not naively applicable to end users of the Bolt SDK, which can make writing Bolt apps in TypeScript today prohibitively difficult.

Here are a few recent examples:

• MessageEvent type definition does not match event data when subtype is 'message_changed' #311
• using the typescript definitions in an app #588
• ack(options) does not compile in TypeScript #720
• feat: Expose a subtype message pattern filter for message handlers #796

I have seen a few answers from @seratch, who does an admirable job of providing workarounds and specialized solutions. 🙏 However, these recommendations often feel like increased complexity, and they are not intuitive to SDK end users. TypeScript is not at fault here; the Bolt type system implementation does not support even naive supersets of the JavaScript SDK. For example:

// This will not compile in TypeScript, and produces a type error
app.message(':wave:', async ({ message, say }) => {
  await say(`Hello, <@${message.user}>`);
});

TypeScript is intended to extend JavaScript by adding types to the language, and speed up the development experience by catching errors and providing fixes.

Writing Slack apps in with Bolt in TypeScript today actually slows down the developer experience, and feels more like an exercise in reverse engineering the SDK than it does in creating awesome new Slack apps.

Questions:

1. Is the intent to officially support Bolt developers using TypeScript?
2. Do the maintainers agree that Slack app developers should be able to implement core Bolt concepts in TypeScript without requiring substantial modification / refactoring of the examples?
3. Is there appetite for improving Jekyll documentation for getting started with TypeScript?
4. How can I help? 🙂

Reproducible in:

package version: @slack/bolt >= 2.5.0
typescript version: typescript >= 4.1.0

Steps to reproduce:

1. Install Bolt and enable TypeScript
2. Attempt to implement the very first example in the official Bolt documentation
3. Run the app

import { App } from '@slack/bolt';

const app = new App({
  token: process.env.BOT_TOKEN,
  socketMode: true,
  appToken: process.env.APP_TOKEN,
});

// This will match any message that contains 👋
app.message(':wave:', async ({ message, say }) => {
  await say(`Hello, <@${message.user}>`);
});

(async () => {
  await app.start();
  console.log('⚡️ Bolt app started');
})();

Expected result:

Slack app to naively transpile and start successfully:

⚡️ Bolt app started

Actual result:

Typing errors plague the developer experience.

slack-quickstart/node_modules/ts-node/src/index.ts:513
    return new TSError(diagnosticText, diagnosticCodes)
           ^
TSError: ⨯ Unable to compile TypeScript:
src/app.ts:16:35 - error TS2339: Property 'user' does not exist on type 'KnownEventFromType<"message">'.
  Property 'user' does not exist on type 'MessageChangedEvent'.

16     await say(`Hello, <@${message.user}>`);
                                     ~~~~

    at createTSError (slack-quickstart/node_modules/ts-node/src/index.ts:513:12)
    at reportTSError (slack-quickstart/node_modules/ts-node/src/index.ts:517:19)

Attachments:

Here's a sample project, for reference:
https://github.com/byrondover/slack-bolt-quickstart-typescript