From b83536dc52f3a64b9f126ad3dd0f320191960dfa Mon Sep 17 00:00:00 2001 From: Shane DeWael Date: Wed, 11 Mar 2020 11:30:45 -0700 Subject: [PATCH] Change Bolt to Bolt to JavaScript --- README.md | 8 ++-- docs/_advanced/conversation_store.md | 2 +- docs/_advanced/logging.md | 2 +- docs/_advanced/receiver.md | 10 ++--- docs/_tutorials/getting_started.md | 10 ++--- docs/_tutorials/hubot_migration.md | 56 ++++++++++++++-------------- 6 files changed, 44 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 24134744f..7c192ece8 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# Slack ⚡️ Bolt +# Slack ⚡️ Bolt for JavaScript [![Build Status](https://travis-ci.org/slackapi/bolt.svg?branch=master)](https://travis-ci.org/slackapi/bolt) [![codecov](https://codecov.io/gh/slackapi/bolt/branch/master/graph/badge.svg)](https://codecov.io/gh/slackapi/bolt) -A framework to build Slack apps, _fast_. +A JavaScript framework to build Slack apps _in a flash_. ## Initialization @@ -153,7 +153,7 @@ Depending on the type of incoming event a listener is meant for, `ack()` should to to update the message with a simple message, or an `object` to replace it with a complex message. Replacing the message to remove the interactive elements is a best practice for any action that should only be performed once. -If an app does not call `ack()` within the time limit, Bolt will generate an error. See [handling +If an app does not call `ack()` within the time limit, Bolt for JavaScript will generate an error. See [handling errors](#handling-errors) for more details. The following is an example of acknowledging a dialog submission: @@ -300,7 +300,7 @@ app.message(noBotMessages, ({ message }) => console.log( )); ``` -Message subtype matching is common, so Bolt ships with a builtin listener middleware that filters all messages that +Message subtype matching is common, so Bolt for JavaScript ships with a builtin listener middleware that filters all messages that match a given subtype. The following is an example of the opposite of the one above - the listener only sees messages that _are_ `bot_message`s. diff --git a/docs/_advanced/conversation_store.md b/docs/_advanced/conversation_store.md index 33ef819b0..147d0e21e 100644 --- a/docs/_advanced/conversation_store.md +++ b/docs/_advanced/conversation_store.md @@ -6,7 +6,7 @@ order: 3 ---
-Bolt includes support for a store, which sets and retrieves state related to a conversation. Conversation stores have two methods: +Bolt for JavaScript includes support for a store, which sets and retrieves state related to a conversation. Conversation stores have two methods: * `set()` modifies conversation state. `set()` requires a `conversationId` of type string, `value` of any type, and an optional `expiresAt` of type number. `set()` returns a `Promise`. * `get()` fetches conversation state from the store. `get()` requires a `conversationId` of type string and returns a Promise with the conversation’s state. diff --git a/docs/_advanced/logging.md b/docs/_advanced/logging.md index ea67a7a45..84204e293 100644 --- a/docs/_advanced/logging.md +++ b/docs/_advanced/logging.md @@ -6,7 +6,7 @@ order: 7 ---
-By default, Bolt will log information from your app to the console. You can customize how much logging occurs by passing a `logLevel` in the constructor. The available log levels in order of most to least logs are `DEBUG`, `INFO`, `WARN`, and `ERROR`. +By default, Bolt for JavaScript will log information from your app to the console. You can customize how much logging occurs by passing a `logLevel` in the constructor. The available log levels in order of most to least logs are `DEBUG`, `INFO`, `WARN`, and `ERROR`.
```javascript diff --git a/docs/_advanced/receiver.md b/docs/_advanced/receiver.md index 4363b400b..8788ab730 100644 --- a/docs/_advanced/receiver.md +++ b/docs/_advanced/receiver.md @@ -6,7 +6,7 @@ order: 8 ---
-A receiver is responsible for handling and parsing any incoming events from Slack, then emitting the event so the Bolt app can add context and pass it to your app’s listeners. Receivers must conform to the Receiver interface: +A receiver is responsible for handling and parsing any incoming events from Slack, then emitting the event so the Bolt for JavaScript app can add context and pass it to your app’s listeners. Receivers must conform to the Receiver interface: | Method | Parameters | Return type | |--------------|----------------------------------|-------------| @@ -14,11 +14,11 @@ A receiver is responsible for handling and parsing any incoming events from Slac | `start()` | None | `Promise` | | `stop()` | None | `Promise` | -`on()` is called two times in the Bolt app: -* `Receiver.on('message', listener)` should route all incoming requests that have been parsed to `onIncomingEvent()`. It’s called in the Bolt app as `this.receiver.on('message', message => this.onIncomingEvent(message))`. -* `Receiver.on('error', listener)` should route errors to the global error handler. It’s called in the Bolt app as `this.receiver.on('error', error => this.onGlobalError(error))`. +`on()` is called two times in a Bolt for JavaScript app: +* `Receiver.on('message', listener)` should route all incoming requests that have been parsed to `onIncomingEvent()`. It’s called in the Bolt for JavaScript app as `this.receiver.on('message', message => this.onIncomingEvent(message))`. +* `Receiver.on('error', listener)` should route errors to the global error handler. It’s called in the Bolt for JavaScript app as `this.receiver.on('error', error => this.onGlobalError(error))`. -To use a custom receiver, you can pass it into the constructor when initializing your Bolt app. Here is what a basic custom receiver might look like. +To use a custom receiver, you can pass it into the constructor when initializing your Bolt for JavaScript app. Here is what a basic custom receiver might look like. For a more in-depth look at a receiver, [read the source code for the built-in Express receiver](https://github.com/slackapi/bolt/blob/master/src/ExpressReceiver.ts)
diff --git a/docs/_tutorials/getting_started.md b/docs/_tutorials/getting_started.md index 6594ba567..e3001e163 100644 --- a/docs/_tutorials/getting_started.md +++ b/docs/_tutorials/getting_started.md @@ -8,10 +8,10 @@ permalink: /tutorial/getting-started redirect_from: - /getting-started --- -# Getting started with Bolt +# Getting started with Bolt for JavaScript
-This guide is meant to walk you through getting up and running with a Slack app using Bolt. Along the way, we’ll create a new Slack app, set up your local environment, and develop an app that listens and responds to messages from a Slack workspace. +This guide is meant to walk you through getting up and running with a Slack app using Bolt for JavaScript. Along the way, we’ll create a new Slack app, set up your local environment, and develop an app that listens and responds to messages from a Slack workspace.
--- @@ -63,7 +63,7 @@ npm init You’ll be prompted with a series of questions to describe your new project (you can accept the defaults by hitting Enter on each prompt if you aren’t picky). After you’re done, you’ll have a new `package.json` file in your directory. -Before we install the Bolt package to your new project, let's save the bot token and signing secret that was generated when you configured your app. These should be stored as environment variables and should *not* be saved in version control. +Before we install the Bolt for JavaScript package to your new project, let's save the bot token and signing secret that was generated when you configured your app. These should be stored as environment variables and should *not* be saved in version control. 1. **Copy your Signing Secret from the Basic Information page** and then store it in a new environment variable. The following example works on Linux and MacOS; but [similar commands are available on Windows](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153). @@ -303,9 +303,9 @@ You can see that we used the `action_id` to add a listener for our button action --- ### Next steps -You just built your first Bolt app! 🎉 +You just built your first Bolt for JavaScript app! 🎉 -Now that you have a basic app up and running, you can start exploring the parts of Bolt that will make your app stand out. Here are some ideas about where to look next: +Now that you have a basic app up and running, you can start exploring how to make your Bolt app stand out. Here are some ideas about what to explore next: * Read through the [Basic concepts](https://slack.dev/bolt#basic) to learn about the different methods and features your Bolt app has access to. diff --git a/docs/_tutorials/hubot_migration.md b/docs/_tutorials/hubot_migration.md index c372adbbb..8d9081099 100644 --- a/docs/_tutorials/hubot_migration.md +++ b/docs/_tutorials/hubot_migration.md @@ -8,24 +8,24 @@ permalink: /tutorial/hubot-migration redirect_from: - /hubot-migration --- -# Migrating apps from Hubot to Bolt +# Migrating apps from Hubot to Bolt for JavaScript
-Bolt was created to reduce the time and complexity it takes to build Slack apps. It provides Slack developers a single interface to build using modern features and best practices. This guide is meant to step you through the process of migrating your app from using [Hubot](https://hubot.github.com/docs/) to Bolt. +Bolt was created to reduce the time and complexity it takes to build Slack apps. It provides Slack developers a single interface to build using modern features and best practices. This guide is meant to step you through the process of migrating your app from using [Hubot](https://hubot.github.com/docs/) to Bolt for JavaScript. -If you already have an [app with a bot user](https://api.slack.com/bot-users#getting-started) or if you’re looking for code samples that translate Hubot code to Bolt code, you may find it valuable to start by reading through the [example script in the Bolt repository](https://github.com/slackapi/bolt/blob/master/examples/hubot-example/script.js). +If you already have an [app with a bot user](https://api.slack.com/bot-users#getting-started) or if you’re looking for code samples that translate Hubot code to Bolt for JavaScript code, you may find it valuable to start by reading through the [example script in the Bolt for JavaScript repository](https://github.com/slackapi/bolt/blob/master/examples/hubot-example/script.js).
--- ### Setting the stage -When translating a Hubot app to Bolt, it’s good to know how each are working behind the scenes. Slack’s Hubot adapter is built to interface with the [RTM API](https://api.slack.com/rtm), which uses a WebSocket-based connection that sends a stream of workspace events to your Hubot app. The RTM API is not recommended for most use cases since it doesn’t include support for newer platform features and it can become very resource-intensive, particularly if the app is installed on multiple or large Slack teams. +When translating a Hubot app to Bolt for JavaScript, it’s good to know how each are working behind the scenes. Slack’s Hubot adapter is built to interface with the [RTM API](https://api.slack.com/rtm), which uses a WebSocket-based connection that sends a stream of workspace events to your Hubot app. The RTM API is not recommended for most use cases since it doesn’t include support for newer platform features and it can become very resource-intensive, particularly if the app is installed on multiple or large Slack teams. -The default Bolt receiver is built to support the [Events API](https://api.slack.com/events-api), which uses HTTP-based event subscriptions to send JSON payloads to your Bolt app. The Events API includes newer events that aren’t on RTM and is more granular and scalable. It’s recommended for most use cases, though one reason your app may be stuck using the RTM API could be that the server you’re hosting your app from has a firewall that only allows outgoing requests and not incoming ones. +The default Bolt for JavaScript receiver is built to support the [Events API](https://api.slack.com/events-api), which uses HTTP-based event subscriptions to send JSON payloads to your Bolt app. The Events API includes newer events that aren’t on RTM and is more granular and scalable. It’s recommended for most use cases, though one reason your app may be stuck using the RTM API could be that the server you’re hosting your app from has a firewall that only allows outgoing requests and not incoming ones. -There are a few other differences you may want to consider before creating a Bolt app: -- The minimum version of Node for Bolt is `v10.0.0`. If the server you’re hosting your app from cannot support `v10`, it’s not possible to migrate your app to Bolt at the moment. -- Bolt doesn’t have support for external scripts. If your Hubot app uses external scripts that are necessary to your app’s functionality or deployment, you probably want to stay with Hubot for now. If you aren’t sure whether your app has any external scripts, you can check the `external-scripts.json` file. As we continue to invest in Bolt, we are thinking about the future and how to make development and deployment of Slack apps easier. If there’s a valuable external script that your app uses, we’d love to hear what it is [in the dedicated Github issue](https://github.com/slackapi/bolt/issues/119). +There are a few other differences you may want to consider before creating a Bolt for JavaScript app: +- The minimum version of Node for Bolt for JavaScript is `v10.0.0`. If the server you’re hosting your app from cannot support `v10`, it’s not possible to migrate your app to Bolt for JavaScript at the moment. +- Bolt for JavaScript doesn’t have support for external scripts. If your Hubot app uses external scripts that are necessary to your app’s functionality or deployment, you probably want to stay with Hubot for now. If you aren’t sure whether your app has any external scripts, you can check the `external-scripts.json` file. As we continue to invest in Bolt for JavaScript, we are thinking about the future and how to make development and deployment of Slack apps easier. If there’s a valuable external script that your app uses, we’d love to hear what it is [in the dedicated Github issue](https://github.com/slackapi/bolt/issues/119). - Hubot apps are written in Coffeescript, which transpiles into Javascript. We decided to write Bolt in Typescript to give access to rich type information. Bolt apps can be developed using Typescript or Javascript. The [example script](https://github.com/slackapi/bolt/blob/master/examples/hubot-example/script.js) shows you how your Coffeescript may translate to Javascript. If your app is more than a few simple scripts, it may be worth looking into projects like [Decaffeinate](https://github.com/decaffeinate/decaffeinate) to convert your CoffeeScript to Javascript. --- @@ -53,7 +53,7 @@ To add a bot user to your new app, click **Bot Users** on the left sidebar and t ### Configure what your bot will hear The [Events API](https://api.slack.com/bot-users#app-mentions-response) is a bot's equivalent of eyes and ears. It gives a bot a way to react to posted messages, changes to channels, and other activities that happen in Slack. -> ⚠️Before you configure your bot’s events, you’ll need a public URL. If you’ve never created a Bolt app or never used the Events API, it’d be helpful to go through [setting up your local Bolt project](https://slack.dev/bolt/tutorial/getting-started#setting-up-your-local-project) and [setting up events](https://slack.dev/bolt/tutorial/getting-started#setting-up-events) in the Getting Started guide. +> ⚠️Before you configure your bot’s events, you’ll need a public URL. If you’ve never created a Bolt for JavaScript app or never used the Events API, it’d be helpful to go through [setting up your local Bolt project](https://slack.dev/bolt/tutorial/getting-started#setting-up-your-local-project) and [setting up events](https://slack.dev/bolt/tutorial/getting-started#setting-up-events) in the Getting Started guide. #### Listening for messages All Hubot apps can listen to messages by default, so we need to configure your bot user to do the same. @@ -75,14 +75,14 @@ Your Hubot app may have responded to other events depending on what functionalit After you added events that correspond to your app’s functionality, click **Save Changes**. ### Changes to script interfaces -Bolt’s interface was designed to conform to the Slack API language as much as possible, while Hubot was designed with more generalized language to abstract multiple services. While the interfaces are similar, converting a Hubot script to a Bolt one still requires some code changes. +Bolt’s interface was designed to conform to the Slack API language as much as possible, while Hubot was designed with more generalized language to abstract multiple services. While the interfaces are similar, converting a Hubot script to a Bolt for JavaScript one still requires some code changes. -Bolt doesn’t use `res` or expose the raw request from Slack. Instead, you can use the payload body from `payload`, or common functionality like sending a message using `say()`. +Bolt for JavaScript doesn’t use `res` or expose the raw request from Slack. Instead, you can use the payload body from `payload`, or common functionality like sending a message using `say()`. -> ⚙️To make it easier, we’ve created a sample script on Github that [showcases Hubot’s core functionality using equivalent functionality written for Bolt](https://github.com/slackapi/bolt/blob/master/examples/hubot-example/script.js). +> ⚙️To make it easier, we’ve created a sample script on Github that [showcases Hubot’s core functionality using equivalent functionality written with Bolt for JavaScript](https://github.com/slackapi/bolt/blob/master/examples/hubot-example/script.js). #### Listening to patterns using `message()` -Hubot scripts use `hear()` listen to messages with a matching pattern. Bolt instead uses `message()` and accepts a `string` or `RegExp` for the pattern. +Hubot scripts use `hear()` listen to messages with a matching pattern. Bolt for JavaScript instead uses `message()` and accepts a `string` or `RegExp` for the pattern. > 👨‍💻👩‍💻Anywhere where you use `hear()` in your code, change it to use `message()` @@ -91,9 +91,9 @@ Hubot scripts use `hear()` listen to messages with a matching pattern. Bolt inst #### Responding with a message using `say()` and `respond()` Hubot scripts use `send()` to send a message to the same conversation and `reply()` to send a message to the same conversation with an @-mention to the user that sent the original message. -Bolt uses `say()` in place of `send()`, or `respond()` to use the `response_url` to send a reply. To add an @-mention to the beginning of your reply, you can use the user ID found in the `context` object. For example, for a message event you could use `say('<@${message.user}> Hello :wave:')` +Bolt for JavaScript uses `say()` in place of `send()`, or `respond()` to use the `response_url` to send a reply. To add an @-mention to the beginning of your reply, you can use the user ID found in the `context` object. For example, for a message event you could use `say('<@${message.user}> Hello :wave:')` -The arguments for Hubot’s `send()` and Bolt’s `say()` are mostly the same, although `say()` allows you to send messages with [interactive components like buttons, select menus, and datepickers](https://api.slack.com/messaging/interactivity#interaction). +The arguments for Hubot’s `send()` and Bolt for JavaScript's `say()` are mostly the same, although `say()` allows you to send messages with [interactive components like buttons, select menus, and datepickers](https://api.slack.com/messaging/interactivity#interaction). > 👨‍💻👩‍💻Anywhere where you use `send()` in your code, change it to use `say()` @@ -103,14 +103,14 @@ The arguments for Hubot’s `send()` and Bolt’s `say()` are mostly the same, a In the previous section, you should have subscribed your app to the `app_mention` event if your Hubot script uses `respond()`, and `reaction_added` if you uses `react()`. -Bolt uses a method called `event()` that allows you to listen to any [Events API event](https://api.slack.com/events). To change your code, you’ll just change any `respond()` to `app.event(‘app_mention’)` and any `react()` to `app.event(‘reaction_added’)`. This is detailed more [in the example script](https://github.com/slackapi/bolt/blob/master/examples/hubot-example/script.js). +Bolt for JavaScript uses a method called `event()` that allows you to listen to any [Events API event](https://api.slack.com/events). To change your code, you’ll just change any `respond()` to `app.event(‘app_mention’)` and any `react()` to `app.event(‘reaction_added’)`. This is detailed more [in the example script](https://github.com/slackapi/bolt/blob/master/examples/hubot-example/script.js). > 👨‍💻👩‍💻Anywhere where you use `respond()` in your code, change it to use `app.event(‘app_mention’)`. Anywhere you use `react`, change it to `app.event(‘reaction_added’)`. [Read more about listening to events](https://slack.dev/bolt/concepts#event-listening). -### Using Web API methods with Bolt -In Hubot, you needed to import the `WebClient` package from `@slack/client`. Bolt imports a `WebClient` instance for you by default, accessible from `app.client`. +### Using Web API methods with Bolt for JavaScript +In Hubot, you needed to import the `WebClient` package from `@slack/client`. Bolt for JavaScript imports a `WebClient` instance for you by default, accessible from `app.client`. To use the built-in `WebClient`, you’ll need to pass the token used to instantiate your app or the token associated with the team your request is coming from. This is found on the `context` object passed in to your listener functions. For example, to add a reaction to a message, you’d use: @@ -134,21 +134,21 @@ app.message('react', async ({ message, context }) => { [Read more about using the Web API with Bolt](https://slack.dev/bolt/concepts#web-api). -### Using middleware with Bolt +### Using middleware with Bolt for JavaScript Hubot has three kinds of middleware: receive (runs before any listeners are called), listener (runs for every matching listener), and response (runs for every response sent). -Bolt only has two kinds of middleware — global and listener: -- Global middleware runs before any listener middleware is called. It’s attached to the Bolt app itself. [Read more about Bolt’s global middleware](https://slack.dev/bolt/concepts#global-middleware). -- Listener middleware only runs for listener functions it’s attached to. [Read more about Bolt’s listener middleware](https://slack.dev/bolt/concepts#listener-middleware). +Bolt for JavaScript only has two kinds of middleware — global and listener: +- Global middleware runs before any listener middleware is called. It’s attached to the Bolt for JavaScript app itself. [Read more about Bolt for JavaScript's global middleware](https://slack.dev/bolt/concepts#global-middleware). +- Listener middleware only runs for listener functions it’s attached to. [Read more about Bolt for JavaScript's listener middleware](https://slack.dev/bolt/concepts#listener-middleware). -With Bolt, both kinds of middleware must call `next()` to pass control of execution from one middleware to the next. If your middleware encounters an error during execution, you can pass an `Error` to `next()` and the error will be bubbled up through the previously-executed middleware chain. +In Bolt for JavaScript, both kinds of middleware must call `next()` to pass control of execution from one middleware to the next. If your middleware encounters an error during execution, you can pass an `Error` to `next()` and the error will be bubbled up through the previously-executed middleware chain. -To migrate your existing middleware functions, it’s evident that Hubot’s receive middleware aligns with the use case for global middleware in Bolt. And Hubot and Bolt’s listener middleware are nearly the same. To migrate Hubot’s response middleware, you can use a Bolt concept called a post-process function. +To migrate your existing middleware functions, it’s evident that Hubot’s receive middleware aligns with the use case for global middleware in Bolt for JavaScript. And Hubot and Bolt’s listener middleware are nearly the same. To migrate Hubot’s response middleware, you can use a Bolt for JavaScript concept called a post-process function. If your middleware needs to perform post-processing of an event, you can call `next()` with a post-processing function rather than it calling it with `undefined`. A post-processing function must call `done()` in the same way a middleware function must call `next()` (and can also be called with an `Error`). ### Migrating the brain to the conversation store -Hubot has an in-memory store called the brain. This enables a Hubot script to `get` and `set` basic pieces of data. Bolt uses something called a conversation store, which is a global middleware with a `get()`/`set()` interface. +Hubot has an in-memory store called the brain. This enables a Hubot script to `get` and `set` basic pieces of data. Bolt for JavaScript uses a conversation store, which is a global middleware with a `get()`/`set()` interface. The default, built-in conversation store uses an in-memory store similar to Hubot, with the ability to set an expiration time in milliseconds. There are two ways to get and set conversation state: - Call `app.convoStore.get()` with a conversation ID to retrieve the state of a conversation, and call `app.convoStore.set()` with a conversation ID, conversation state (key-value pair), and an optional `expiresAt` time in milliseconds. @@ -159,11 +159,11 @@ If there is more than one instance of your app running, the built-in conversatio [Read more about conversation stores](https://slack.dev/bolt/concepts#conversation-store). ### Next steps -If you’ve made it this far, it means you’ve likely converted your Hubot app into a Bolt app! ✨⚡ +If you’ve made it this far, it means you’ve likely converted your Hubot app into a Bolt for JavaScript app! ✨⚡ -Now that you have your flashy new Bolt app, you can explore how to power it up: +Now that you have your flashy new Bolt for JavaScript app, you can explore how to power it up: - Consider adding interactivity [like buttons and select menus](https://api.slack.com/messaging/interactivity#interaction). These weren’t supported by Hubot and will allow your app to include contextual actions when sending messages to Slack. -- Read [the documentation](https://slack.dev/bolt/concepts) to explore what else is possible with Bolt. +- Read [the documentation](https://slack.dev/bolt/concepts) to explore what else is possible with Bolt for JavaScript. - Check out our [sample app](https://glitch.com/~slack-bolt) that shows you how to use events and interactive components. And if you have difficulties while developing, reach out to our developer support team to at [developers@slack.com](mailto:developers@slack.com), and if you run into a problem with the framework [open an issue on Github](https://github.com/slackapi/bolt/issues/new).