Skip to content

docs: replace the removed agent proxy option with fetch on the web-api and webhook pages - #2880

Merged
zimeg merged 1 commit into
mainfrom
zimeg-docs-proxy-without-agent
Nov 20, 2026
Merged

zimeg merged 1 commit into
mainfrom
zimeg-docs-proxy-without-agent

Conversation

@zimeg

@zimeg zimeg commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Summary

This pull request updates the "Proxy requests" sections of the @slack/web-api and @slack/webhook docs, since v8 of both packages removed the agent option these sections described.

  • Prefers the built-in proxy support of Node.js: NODE_USE_ENV_PROXY=1 (v22.21.0, v24.0.0, or later) or http.setGlobalProxyFromEnv() (v24.14.0 or later).
  • Adds a fetch option alternative that passes an undici ProxyAgent as the dispatcher to globalThis.fetch, with the undici major that matches Node.js from the long-term support table. Keeping globalThis.fetch keeps files.uploadV2 working, since undici's own fetch doesn't recognize the global FormData used for uploads, and an undici@8 ProxyAgent fails with the fetch in Node.js v24.
  • Renames the heading from "Proxy requests with a custom agent" to "Proxy requests", so the #proxy-requests-with-a-custom-agent anchor changes.
  • Uses ESM in the new snippets. The rest of each page stays CommonJS for now.

Tested against a local forwarding proxy with @slack/[email protected], @slack/[email protected] and [email protected], checking chat.postMessage, files.uploadV2 (the proxy received the multipart body), a webhook send, and api.test to slack.com over a CONNECT tunnel:

Node.js Bundled undici undici@7 dispatcher NODE_USE_ENV_PROXY=1 http.setGlobalProxyFromEnv()
v20.19.6 6.22.0 ✅ not available not available
v22.18.0 6.21.2 ✅ not available not available
v22.23.5 6.29.1 ✅ ✅ not available
v24.21.0 7.29.1 ✅ ✅ ✅

Notes

  • The bolt-js Japanese reference links to the old anchor from its agent option row (docs/japanese/reference.md:92), which could be updated in a follow-up.

Requirements

🤖 Generated with Claude Code

…i and webhook pages

Co-Authored-By: Claude <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
@zimeg zimeg added this to the web-api@next milestone Nov 20, 2026
@zimeg zimeg added docs M-T: Documentation work only pkg:web-api applies to `@slack/web-api` pkg:webhook applies to `@slack/webhook` labels Nov 20, 2026
@zimeg zimeg self-assigned this Nov 20, 2026
@changeset-bot

changeset-bot Bot commented Nov 20, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 4d281da

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@codecov

codecov Bot commented Nov 20, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.46%. Comparing base (c7f9d39) to head (4d281da).
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2880      +/-   ##
==========================================
+ Coverage   94.41%   94.46%   +0.04%     
==========================================
  Files          68       68              
  Lines       10942    10942              
  Branches      696      693       -3     
==========================================
+ Hits        10331    10336       +5     
+ Misses        580      575       -5     
  Partials       31       31              
Flag Coverage Δ
cli-hooks 94.40% <ø> (ø)
cli-test 94.40% <ø> (ø)
logger 94.40% <ø> (ø)
oauth 94.40% <ø> (ø)
socket-mode 94.40% <ø> (ø)
web-api 94.40% <ø> (ø)
webhook 94.40% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@zimeg
zimeg marked this pull request as ready for review November 20, 2026 09:02
@zimeg
zimeg requested a review from a team as a code owner November 20, 2026 09:02

@cchensh cchensh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. This matches the code: agent is gone, fetch is the option on both WebClientOptions and IncomingWebhook and defaults to globalThis.fetch, and the ProxyAgent/dispatcher samples are right. Follow-up: the v8 migration guides (migrating-web-api-package-to-v8.md:76 and the matching webhook section) still show undici's own fetch, which the description says breaks files.uploadV2. Nit: the new samples are ESM with top-level await, while the rest of the page is CommonJS.

@zimeg

zimeg commented Nov 20, 2026

Copy link
Copy Markdown
Member Author

🌟 Thanks for the kind review @cchensh! The migration guide follow-up is a great catch 🔌

@zimeg
zimeg merged commit 6815a97 into main Nov 20, 2026
22 checks passed
@zimeg
zimeg deleted the zimeg-docs-proxy-without-agent branch November 20, 2026 14:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs M-T: Documentation work only pkg:web-api applies to `@slack/web-api` pkg:webhook applies to `@slack/webhook`

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants