Slack Edge Framework

Common errors

• HTTP 401: Invalid Signature

• Signature verification failed

• TypeError: app.run is not a function

• Request timed out

• ReferenceError: process is not defined

Warnings

• gotcha Edge functions have strict execution time limits (typically 3 seconds for initial Slack event responses). Any long-running operations in your synchronous handlers will cause timeouts.
  Fix: Offload all long-running tasks to 'lazy listeners' (the optional third argument in event handlers). These execute asynchronously, allowing the initial request to be acknowledged promptly.
• gotcha Direct usage of `slack-edge` for an edge runtime requires installing and configuring a platform-specific adapter package (e.g., `slack-cloudflare-workers`, `slack-vercel-edge`) to handle the request/response context.
  Fix: Install the appropriate adapter package for your chosen runtime environment and follow its documentation for proper integration, as shown in the quickstart for Cloudflare Workers.
• gotcha Prior to version 1.3.8, there was a bug where `oauth.start` might have been incorrectly used for OIDC endpoint customization, potentially leading to misconfiguration.
  Fix: Ensure `oidc.start` is used for OpenID Connect (OIDC) endpoint customization. Upgrade to version 1.3.8 or later to resolve this bug.
• gotcha Incorrect or missing Slack environment variables (`SLACK_SIGNING_SECRET`, `SLACK_BOT_TOKEN`, etc.) are a very common cause of application startup failures or request validation errors, especially during local development.
  Fix: Always verify that all required Slack app environment variables are correctly set in your deployment environment and, for local development, in a `.dev.vars` file or equivalent.

Install

• npm install slack-edge npm
• yarn add slack-edge yarn
• pnpm add slack-edge pnpm

Imports

• SlackApp
  wrong:

  const SlackApp = require('slack-edge');

  correct:

  import { SlackApp } from 'slack-edge';

  The primary class for initializing and configuring your Slack application. While platform-specific adapters may re-export it, the core class is directly from 'slack-edge'.
• SlackEnv
  wrong:

  import { SlackEnv } from 'slack-edge';

  correct:

  import type { SlackEnv } from 'slack-edge';

  A type definition for generic environment variables expected by the SlackApp. For platform-specific environments (e.g., Cloudflare Workers), use the types provided by the respective adapter package.
• LazyListener
  wrong:

  import { LazyListener } from 'slack-edge';

  correct:

  import type { LazyListener } from 'slack-edge';

  A type definition for asynchronous event handlers that run outside the initial 3-second Slack response window.
• CodedError
  wrong:

  import { CodedError } from 'slack-edge';

  correct:

  import type { CodedError } from 'slack-edge';

  Type for errors that include a specific error code, useful for handling API failures or internal framework errors.

Quickstart

Demonstrates a basic Slack app on Cloudflare Workers, handling a slash command. It uses `slack-edge`'s core `SlackApp` and integrates with `slack-cloudflare-workers` to manage the edge function request/response lifecycle, showcasing both synchronous acknowledgment and asynchronous lazy listeners.

import { SlackApp } from "slack-edge";
import { SlackEdgeAppEnv } from "slack-cloudflare-workers";

export default {
  async fetch(
    request: Request,
    env: SlackEdgeAppEnv,
    ctx: ExecutionContext
  ): Promise<Response> {
    // Initialize the SlackApp with environment variables provided by the adapter
    const app = new SlackApp({ env })
      .command("/hello-cf-workers",
        async (req) => {
          // Synchronous handler, responsible for acknowledging the request within 3 seconds
          return ":wave: This app runs on Cloudflare Workers!";
          // If no immediate response is needed, simply `async () => {}` works
        },
        async ({ context: { respond } }) => {
          // Lazy listener, executed asynchronously for longer-running tasks
          // This can take more than 3 seconds without timing out the initial request
          await respond({ text: "This is an async reply. How are you doing?" });
        }
      );
    // Run the app using the Cloudflare Workers adapter's `run` method
    return await app.run(request, ctx);
  }
};

// --- Local Development Environment Variables (e.g., in .dev.vars) ---
// SLACK_SIGNING_SECRET=...
// SLACK_BOT_TOKEN=xoxb-...
// SLACK_LOGGING_LEVEL=DEBUG