Template Slack app built with @tightknitai/slack-hono and slack-cloudflare-workers on Cloudflare Workers.

Demonstrates OAuth multi-workspace installation, slash commands, event handling, block actions, and view submissions — all running on the edge with KV-backed storage.

Once installed, try these in Slack:

Get the app running locally with a tunnel so Slack can reach your dev server.

You'll need a Slack workspace where you have permissions to install apps. Options:

• Your team's workspace — if you have admin permissions
• A free Slack workspace — create one for testing
• Slack Developer Program sandbox — join the Developer Program for a dedicated dev environment

• Node.js >= 20
• pnpm
• cloudflared — for tunneling to your local dev server
• A Cloudflare account (free)

pnpm install

pnpm run setup:kv

Copy the namespace IDs from the output and update wrangler.jsonc.

pnpm run dev:tunnel

Copy the tunnel URL from the output (e.g. https://xxx-yyy-zzz.trycloudflare.com).

Note: Quick tunnels generate a new URL each time you restart. You'll need to update the Slack app's Request URL when the tunnel URL changes. See Permanent dev tunnel below for a fixed URL, or go straight to Production Setup to deploy with a permanent Worker URL.

This updates manifest.json with your tunnel URL, copies it to your clipboard, and opens the Slack app creation page:

pnpm run setup:manifest https://xxx-yyy-zzz.trycloudflare.com

In the browser: choose "From an app manifest" → paste from clipboard → Next → Create.

Grab the Signing Secret, Client ID, and Client Secret from the app you just created (Settings > Basic Information > App Credentials).

cp .dev.vars.example .dev.vars
# Fill in the values

Restart the dev server for the new secrets to take effect.

pnpm run install-app

You're up and running! Try /hello in Slack.

Deploy to Cloudflare Workers for a permanent URL that doesn't change.

pnpm run deploy

Note your Worker URL from the output (e.g. https://slack-hono-template.your-subdomain.workers.dev).

Replace the tunnel/placeholder URL with your Worker URL in manifest.json, then push the changes:

1. Go to api.slack.com/apps and select your app
2. Click App Manifest in the sidebar
3. Paste the contents of manifest.json and click Save Changes

pnpm run setup:secrets

Stream real-time logs from your deployed Worker:

pnpm run logs

You can also view logs, analytics (request count, errors, latency), and traces in the Cloudflare dashboard under Workers & Pages → your worker → Logs / Analytics.

This template includes a GitHub Actions workflow (.github/workflows/deploy.yml) that auto-deploys on push to main.

To set it up, create a Cloudflare API token at dash.cloudflare.com/profile/api-tokens with the "Edit Cloudflare Workers" template. Add it as a GitHub secret named CLOUDFLARE_API_TOKEN.

If you have a domain on Cloudflare, you can create a named tunnel with a fixed URL that survives restarts — no more updating the Slack Request URL every time.

One-time setup (requires a domain on Cloudflare):

pnpm run setup:tunnel slack-dev.yourdomain.com

This logs into Cloudflare, creates a named tunnel, routes your subdomain to it, and writes cloudflared.yml. Then just use pnpm run dev:tunnel as usual — your dev URL is now permanent.

cloudflared.yml is gitignored since the tunnel ID is specific to your account.

You can optionally link this project to the Slack CLI for manifest validation.

• macOS & Linux
• Windows

slack login
slack app link

Follow the prompts to select your workspace and app.

slack manifest validate --source local

This checks your local manifest.json against the Slack manifest schema without having to paste it into the web UI.

src/
 index.ts — Main Hono app with OAuth + all Slack handlers
scripts/
 setup-manifest.sh — Updates manifest.json with your URL
 setup-secrets.sh — Prompts for Cloudflare Workers secrets
 install-app.sh — Opens the app install page
vite.config.ts — Vite config with Cloudflare plugin
wrangler.jsonc — Cloudflare Workers config with KV bindings
manifest.json — Slack app manifest
.dev.vars — Local secrets (not committed)
.github/workflows/
 deploy.yml — Auto-deploy on push to main

MIT

Built with @tightknitai/slack-hono. Maintained by the Tightknit team.