Slack Bolt with Next.js Template

This is a generic Bolt for JavaScript (TypeScript) template app used to build Slack apps with Next.js

Before getting started, make sure you have a development workspace where you have permissions to install apps. You can use a developer sandbox or create a workspace

Installation

Clone and install dependencies

git clone https://github.com/vercel-partner-solutions/slack-bolt-with-next.git && cd slack-bolt-with-next && pnpm install

Create a Slack App

1. Open https://api.slack.com/apps/new and choose "From an app manifest"
2. Choose the workspace you want to use
3. Copy the contents of manifest.json into the text box that says "Paste your manifest code here" (JSON tab) and click Next
4. Review the configuration and click Create
5. On the Install App tab, click Install to <Workspace_Name>.
   • You will be redirected to the App Configuration dashboard
6. Copy the Bot User OAuth Token into your environment as SLACK_BOT_TOKEN
7. On the Basic Information tab, copy your Signing Secret into your environment as SLACK_SIGNING_SECRET

Prepare for Local Development

1. Add your NGROK_AUTH_TOKEN to your .env file
   • You can get a free token here
2. In the terminal run slack app link
3. If prompted update the manifest source to remote select yes
4. Copy your App ID from the app you just created
5. Select Local when prompted
6. Open .slack/config.json and update your manifest source to local

{
  "manifest": {
    "source": "local"
  },
  "project_id": "<project-id-added-by-slack-cli>"
}

7. Start your local server using slack run. If prompted, select the workspace you'd like to grant access to

• Select yes if asked "Update app settings with changes to the local manifest?"

8. Open your Slack workspace, add your Slackbot to a channel, and send hello. Your app should reply with world!

Deploy to Vercel

1. Create a new Slack app for production following the steps from above
2. Create a new Vercel project here and select this repo
3. Copy the Bot User OAuth Token into your Vercel environment variables as SLACK_BOT_TOKEN
4. On the Basic Information tab, copy your Signing Secret into your Vercel environment variables as SLACK_SIGNING_SECRET
5. When your deployment has finished, open your App Manifest from the Slack App Dashboard
6. Update the manifest so all the request_url and url fields use https://<your-app-domain>/api/slack/events
7. Click save and you will be prompted to verify the URL
8. Open your Slack workspace and add your app to any channel
   • Note: Make sure you add the production app, not the local app we setup earlier
9. Send hello and your app will respond with world!
10. Your app will now automatically build and deploy whenever you commit to your repo. More information here

Project Structure

manifest.json

manifest.json defines your Slack app's configuration. With a manifest, you can create or update an app with a pre-defined configuration

src/bolt/app.ts

This is the Bolt app entry. It initializes @vercel/slack-bolt's VercelReceiver and registers listeners

src/bolt/listeners

Every incoming request is routed to a "listener". Inside this directory, we group each listener by Slack Platform feature, e.g. messages for message events

Route Handler: src/app/api/slack/events/route.ts

This file defines your Next.js Route Handler that receives Slack events. Its pathname matches the URLs defined in your manifest.json. Next.js uses file-based routing for API handlers. Learn more in the Next.js docs: https://nextjs.org/docs/app/building-your-application/routing/route-handlers

Custom Scripts

• pnpm dev:tunnel: A helper script to automatically start your Slack app with ngrok tunneling

Notes

• If you see a warning about express being externalized: @slack/bolt ships an Express receiver. Turbopack may analyze its static import even if you don't use it. Keeping express as a dependency or aliasing it to a stub resolves this during development.