{"id":12039,"library":"slack-cloudflare-workers","title":"Slack App Framework for Cloudflare Workers","description":"slack-cloudflare-workers is an opinionated framework for building Slack applications designed specifically for Cloudflare Workers, leveraging their serverless environment. Inspired by Slack's popular Bolt framework but not strictly following its blueprint, it distinguishes itself with a strong TypeScript focus, built-in lazy listener capabilities (similar to bolt-python), and a commitment to zero additional runtime dependencies beyond its foundational `slack-edge` module. The current stable version is 1.3.9. This library caters to developers seeking highly performant, type-safe, and lightweight Slack integrations on the Cloudflare Workers platform, providing a streamlined experience compared to general-purpose Node.js frameworks. While release cadence isn't explicitly stated, the active development and frequent updates to the `slack-edge` ecosystem suggest a responsive maintenance schedule.","status":"active","version":"1.3.9","language":"javascript","source_language":"en","source_url":"https://github.com/slack-edge/slack-cloudflare-workers","tags":["javascript","Slack","ChatBot","TypeScript","Cloudflare","Cloudflare Workers","Serverless","typescript"],"install":[{"cmd":"npm install slack-cloudflare-workers","lang":"bash","label":"npm"},{"cmd":"yarn add slack-cloudflare-workers","lang":"bash","label":"yarn"},{"cmd":"pnpm add slack-cloudflare-workers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core foundational module for Slack API interactions, providing primitives for event handling and API calls.","package":"slack-edge","optional":false}],"imports":[{"note":"Cloudflare Workers primarily use ESM. CommonJS `require` is not natively supported without a build step.","wrong":"const App = require('slack-cloudflare-workers');","symbol":"App","correct":"import { App } from 'slack-cloudflare-workers';"},{"note":"Import types separately for clarity and to avoid runtime overhead, especially for TypeScript projects.","symbol":"Context","correct":"import type { Context } from 'slack-cloudflare-workers';"},{"note":"Import the type definition for the underlying Slack API client if direct API calls are made outside of event contexts.","symbol":"SlackAPIClient","correct":"import type { SlackAPIClient } from 'slack-cloudflare-workers';"}],"quickstart":{"code":"import { App } from 'slack-cloudflare-workers';\n\ninterface Env {\n  SLACK_SIGNING_SECRET: string;\n  SLACK_BOT_TOKEN: string;\n}\n\nconst app = new App({\n  signingSecret: process.env.SLACK_SIGNING_SECRET ?? 'your-signing-secret-if-not-env',\n  token: process.env.SLACK_BOT_TOKEN ?? 'your-bot-token-if-not-env',\n});\n\n// Listen for a 'hello' message\napp.message('hello', async ({ say, payload }) => {\n  await say(`Hello, <@${payload.user}>! How can I help you?`);\n});\n\n// Respond to a slash command\napp.command('/echo', async ({ command, ack, respond }) => {\n  await ack(); // Acknowledge the command immediately\n  await respond(`You said: ${command.text}`);\n});\n\nexport default {\n  async fetch(\n    request: Request,\n    env: Env,\n    ctx: ExecutionContext\n  ): Promise<Response> {\n    // Ensure the app instance uses the environment variables from the Worker's context\n    // This is crucial for local development vs. deployed Worker\n    app.oauth = undefined; // Reset OAuth for each request to use correct env\n    app.receiver.signingSecret = env.SLACK_SIGNING_SECRET;\n    app.client.token = env.SLACK_BOT_TOKEN;\n    \n    return app.fetch(request, env, ctx);\n  },\n};\n","lang":"typescript","description":"Sets up a basic Cloudflare Worker handling Slack 'hello' messages and '/echo' slash commands, demonstrating app initialization and event listeners."},"warnings":[{"fix":"Consult the `slack-cloudflare-workers` documentation (especially for event payloads and context objects) when porting Bolt.js code or encountering unexpected behavior.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update to version `1.x.x` for the latest stable API. Always test updates thoroughly, especially if upgrading from pre-1.0 versions.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The Slack `x-slack-signature` header does not match the computed signature using `SLACK_SIGNING_SECRET`.","error":"Error: Signature verification failed."},{"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.","cause":"The `App` instance was not correctly initialized or the import path is wrong, leading to an undefined or incorrect object.","error":"TypeError: app.message is not a function"},{"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.","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.","error":"Failed to execute 'fetch' on 'WorkerGlobalScope': The provided URL 'undefined' is not valid."}],"ecosystem":"npm"}