Slack App Framework for Cloudflare Workers

Common errors

• Error: Signature verification failed.

  cause The Slack `x-slack-signature` header does not match the computed signature using `SLACK_SIGNING_SECRET`.
  fix Ensure `SLACK_SIGNING_SECRET` is correctly set in your Cloudflare Worker's environment variables and exactly matches the value from your Slack app settings. Check for leading/trailing whitespace or accidental character changes.

• TypeError: app.message is not a function

  cause The `App` instance was not correctly initialized or the import path is wrong, leading to an undefined or incorrect object.
  fix Verify that `import { App } from 'slack-cloudflare-workers';` is correct and that `new App({ ... })` is called with valid parameters before attempting to call listener methods.

• Failed to execute 'fetch' on 'WorkerGlobalScope': The provided URL 'undefined' is not valid.

  cause This error often occurs when `SLACK_BOT_TOKEN` is missing or undefined, causing the underlying `SlackAPIClient` to attempt an API call with an invalid base URL.
  fix Ensure `SLACK_BOT_TOKEN` is correctly provided to the `App` instance, either directly or via environment variables, and that it is a valid Slack bot token.

Warnings

• gotcha This framework's design, while inspired by Slack's Bolt.js, does not strictly follow its blueprint. Developers migrating from Bolt.js might find differences in API surface or expected behavior, requiring careful review of the `slack-cloudflare-workers` documentation.
  Fix: Consult the `slack-cloudflare-workers` documentation (especially for event payloads and context objects) when porting Bolt.js code or encountering unexpected behavior.
• breaking Prior to version 1.0, the package's core logic and API surface were less stable. While no explicit breaking change documentation is provided for minor versions, it is generally recommended to pin to a major version (e.g., `slack-cloudflare-workers@^1.0.0`) and review changelogs for updates.
  Fix: Update to version `1.x.x` for the latest stable API. Always test updates thoroughly, especially if upgrading from pre-1.0 versions.
• gotcha Cloudflare Workers do not have a traditional filesystem or `process.env` in the same way as Node.js. Environment variables must be passed explicitly via the `env` argument in the `fetch` handler or configured via `wrangler.toml` and accessed via the `Env` interface. Hardcoding secrets is a security risk.
  Fix: Define secrets (like `SLACK_SIGNING_SECRET`, `SLACK_BOT_TOKEN`) in `wrangler.toml` or using Cloudflare's dashboard, then access them via the `env` object passed to the Worker's `fetch` handler and during `App` initialization.

Install

• npm install slack-cloudflare-workers npm
• yarn add slack-cloudflare-workers yarn
• pnpm add slack-cloudflare-workers pnpm

Imports

• App
  wrong:

  const App = require('slack-cloudflare-workers');

  correct:

  import { App } from 'slack-cloudflare-workers';

  Cloudflare Workers primarily use ESM. CommonJS `require` is not natively supported without a build step.
• Context

  import type { Context } from 'slack-cloudflare-workers';

  Import types separately for clarity and to avoid runtime overhead, especially for TypeScript projects.
• SlackAPIClient

  import type { SlackAPIClient } from 'slack-cloudflare-workers';

  Import the type definition for the underlying Slack API client if direct API calls are made outside of event contexts.

Quickstart

Sets up a basic Cloudflare Worker handling Slack 'hello' messages and '/echo' slash commands, demonstrating app initialization and event listeners.

import { App } from 'slack-cloudflare-workers';

interface Env {
  SLACK_SIGNING_SECRET: string;
  SLACK_BOT_TOKEN: string;
}

const app = new App({
  signingSecret: process.env.SLACK_SIGNING_SECRET ?? 'your-signing-secret-if-not-env',
  token: process.env.SLACK_BOT_TOKEN ?? 'your-bot-token-if-not-env',
});

// Listen for a 'hello' message
app.message('hello', async ({ say, payload }) => {
  await say(`Hello, <@${payload.user}>! How can I help you?`);
});

// Respond to a slash command
app.command('/echo', async ({ command, ack, respond }) => {
  await ack(); // Acknowledge the command immediately
  await respond(`You said: ${command.text}`);
});

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext
  ): Promise<Response> {
    // Ensure the app instance uses the environment variables from the Worker's context
    // This is crucial for local development vs. deployed Worker
    app.oauth = undefined; // Reset OAuth for each request to use correct env
    app.receiver.signingSecret = env.SLACK_SIGNING_SECRET;
    app.client.token = env.SLACK_BOT_TOKEN;
    
    return app.fetch(request, env, ctx);
  },
};