Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Developer experience building Slack apps with Bolt using TypeScript #826

Closed
6 of 10 tasks
byrondover opened this issue Mar 10, 2021 · 9 comments
Closed
6 of 10 tasks
Labels
auto-triage-stale discussion M-T: An issue where more input is needed to reach a decision enhancement M-T: A feature request for new functionality TypeScript-specific

Comments

@byrondover
Copy link
Contributor

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:

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

@gitwave gitwave bot added the untriaged label Mar 10, 2021
@misscoded misscoded added enhancement M-T: A feature request for new functionality and removed untriaged labels Mar 10, 2021
@misscoded
Copy link
Contributor

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
Copy link

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 seratch added the discussion M-T: An issue where more input is needed to reach a decision label Mar 15, 2021
@seratch
Copy link
Member

seratch commented Mar 15, 2021

The changes in slackapi/node-slack-sdk#1188 are also related to this topic.

@seratch
Copy link
Member

seratch commented Mar 22, 2021

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
Copy link
Contributor

shaydewael commented Mar 23, 2021

@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
Copy link

memark commented May 1, 2021

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
Copy link
Member

seratch commented May 1, 2021

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

@github-actions
Copy link

👋 It looks like this issue has been open for 30 days with no activity. We'll mark this as stale for now, and wait 10 days for an update or for further comment before closing this issue out.

@seratch
Copy link
Member

seratch commented Nov 29, 2021

As we are tracking the progress of this issue at #904, let us close this one. Thanks again for taking the time to report this!

@seratch seratch closed this as completed Nov 29, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
auto-triage-stale discussion M-T: An issue where more input is needed to reach a decision enhancement M-T: A feature request for new functionality TypeScript-specific
Projects
None yet
Development

No branches or pull requests

6 participants