Bolt-js: Developer experience building Slack apps with Bolt using TypeScript

[byrondover]

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
• [x] documentation related
• [x] example code related
• [ ] testing related
• [x] discussion

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

• [x] I've read and understood the Contributing guidelines and have done my best effort to follow them.
• [x] I've read and agree to the Code of Conduct.
• [x] 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:

• #311
• #588
• #720
• #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

[misscoded]

Hi @byrondover! Thanks for surfacing this issue and doing such a thorough job with providing support and reasoning behind it. The maintainers have unanimously agreed to prioritize this topic in our next meeting, so I'll circle back around with more details once we've had time to discuss it.

In the meantime, we hear you and agree that there's work to be done in order to better the experience here!

[msrivastav13]

Related to this, Can we get TypeDocs for this project so it's easier to use?

I have struggled a lot in the last couple of days figuring the types and way this works and it's been hard with the current state of docs!

[seratch]

The changes in https://github.com/slackapi/node-slack-sdk/pull/1188 are also related to this topic.

[seratch]

How can I help? 🙂

In the PR #832 , I've added a few TODO/FIXME comments in the type tests. If someone is interested in resolving them without breaking changes, it'd be greatly appreciated: https://github.com/slackapi/bolt-js/pull/832/files

[shaydewael]

@byrondover Like @misscoded said, thanks for starting this conversation! I think we knew that types support was lacking in Bolt, but you've comprehensively laid out the larger picture which gives us a starting point to begin making immediate improvements 🙇

EDIT: Apologies for how long that comment is—I need to work on shortening my replies 😅

Is the intent to officially support Bolt developers using TypeScript?

Yes 💯 TypeScript should add value and feel like the default Bolt developer experience. To get there, there are are quite a few areas to explore, some easier than others. It may be valuable to start with a few lower lift, short-term issues (most of which you've mentioned):

• Refine specific types (like messages)
• Go through new and old TypeScript issues and prioritize them (this is something we maintainers should already be doing) — @seratch has already done started some of this with his work above.
• Explore type generation more seriously (like @msrivastav13 mentioned)
• Create example code and guides

Longer term we could consider outlining what a larger refactor of Bolt types might look like, especially considering newer platform features and the deprecation of older ones. Hopefully clearly reworking, exposing, and documenting types would also make Bolt's more advanced features (like custom middleware and context objects) more approachable.

Is there appetite for improving Jekyll documentation for getting started with TypeScript?

Yes! I think you're right that we should write the Using TypeScript guide, and it could be a great opportunity to also show _why_ coding with TypeScript can (and should) be so beneficial long-term. I've created #850 to address this.

For other documentation, I think it would also be great to explore what a toggle may look like to include both TypeScript and plain JavaScript examples throughout the basic and advanced concepts. This will be a bit more work, but once we have more code examples it will become a lot easier.

How can I help? 🙂

Bringing this up is already helping! 😄 But of course we appreciate any contributions going forward. I'm going to try to do some work to open tickets and create some basic examples. When some basic pieces are in place, you could either help with those tickets or contribute code samples which are probably highest value for developers landing on Bolt for the first time.

---

🏁 I began work with #845, which includes a TypeScript version of the getting started guide. It's not perfect, but it's a starting point and exposes some easy improvements (like refining message types). In that PR, I've also included some of the basic section examples and will continue to add more over time.

When I have some free time I'd like to finish up those examples and then shift to making small but helpful type improvements and writing a draft of the Using TypeScript guide. When I have a draft of that, I'll tag you in the PR and if you have time I'd love your review (if not, that's completely fine and understandable). I'm familiar with TypeScript, but not an expert by any means.

👀 If you (or anyone else reading this) see any obvious gaps I'm missing to improve support please let me know so that it can guide our prioritization. And if you're interested in contributing to anything specifically I'm happy to work with you on it in any way that's helpful.

[memark]

I ran into this today also. Trying to use the official example from https://slack.dev/bolt-js/concepts

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

and immediately getting a ts compile error. This is not a great first-time experience. Not even sure how to get it working.

[seratch]

@memark We are sorry about the insufficient support for TypeScript as of today. I've confirmed the issue and created a new ticket for the problem you've reported. Thank you very much for reporting the issue.