Repository navigation
Improve documentation to make all information available in a single view #2208
Description
This would solve...
I found it challenging to navigate the documentation and understand how to do things like
- What are all the options available to
request() - I have an old legacy streams1 package, how do I create a
reqinstance and dooldstream.pipe(req)to write the HTTP body
The implementation should look like...
I have also considered...
Not using undici, and using another package with a more user friendly README
Additional context
All the documentation is there, I just have to click around and read multiple pages and multiple sections and its very confusing,
- https://github.com/nodejs/undici/blob/main/docs/api/Dispatcher.md#parameter-requestoptions
- then click https://github.com/nodejs/undici/blob/main/docs/api/Dispatcher.md#parameter-dispatchoptions
- but also i had to click https://github.com/nodejs/undici/blob/main/docs/api/Dispatcher.md#dispatcherrequestoptions-callback
Activity
mcollina commentedon Aug 3, 2023
A massive overhaul of our docs is welcomed, but at this point it seems a stretch for the current team. I would love if somebody volunteered for this effort.
AliMahmoudDev commentedon Jun 6, 2026
One thing that helped me a lot when getting started with undici was the typed options in the source code itself — each class has JSDoc types that list all available options with defaults. For example,
new Pool(url, options)hasPoolOptionswhich documents every field.As a quick reference, the high-level mapping is:
fetch()wrapsClient.request(), options are mostly the same plus a few extrasrequest()/stream()are directDispatchermethodsPool/Agenthandle connection management withPoolOptionsandAgentOptionsconnectTimeout,headersTimeout,bodyTimeout,keepAliveTimeoutA getting started page that maps common use cases (basic fetch, streaming, custom dispatcher, mocking) to the relevant API surface would go a long way. Happy to draft something if there is interest.
mcollina commentedon Jun 6, 2026
Absolutely! Go for it!
AliMahmoudDev commentedon Jun 6, 2026
thanks, will start putting together a PR.
AliMahmoudDev commentedon Jun 6, 2026
opened a draft PR for a getting started guide -- #5371. covers fetch/request/stream/pipeline, dispatcher selection, timeouts, error handling, and links to the relevant api pages. lmk if the scope/direction looks right.