Uh oh!
There was an error while loading. Please reload this page.
docs: fix stale/incorrect v5 API reference details - #3017
Conversation
- start error text: "Workflow Development Kit" -> "Workflow SDK" (v5 only; v4 published packages still emit the old string, so v4 docs are left as-is) - define-hook: TypedHook.resume returns Promise<HookEntity> and throws HookNotFoundError; the previous docs claimed it could return null - fatal-error: document the `fatal` property and FatalError.is(); fix the broken placeholder TSDoc block - resume-webhook: enumerate the three Response outcomes (202 / configured static Response / manual respondWith) - sleep: it is a built-in runtime timer primitive, not a step function - fetch: call globalThis.fetch inside the custom "use step" wrapper to avoid nesting a step in a step; drop the maxRetries bullet describing code the example never contained Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: a67c74c The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Uh oh!
There was an error while loading. Please reload this page.
No backport to All changes are to v5 docs pages ( To override, re-run the Backport to stable workflow manually via |
* origin/main: (162 commits) Implement `max_events` per run limit (#2986) [core] Enforce maxRetries for steps that time out (#3035) [world-vercel] Idempotent retry policy for stream close (5xx retriable) (#3038) [world] Guard hook_received against a concurrent run termination (#2987) docs: fix stale/incorrect v5 API reference details (#3017) Default WORKFLOW_PRECONDITION_GUARD on (#2946) docs: replace migration guides with a Comparisons section (#2676) feat(core): add experimental Hook minimum retention (#2865) test: regression coverage for hook.resume() from isolated route bundles (o2flow beta.26 incident) (#3001) docs(agents): note lint/format/typecheck are advisory, not blocking (#2886) Retry transient connection timeouts (#3013) fix(world-vercel): append caller User-Agent products instead of discarding them (#2998) [ci] Enable NestJS e2e-vercel-prod and add to docs as "experimental" (#3011) [ci] Benchmark comment: Best column + best/p75/p99 deltas (drop Avg/P10) (#3005) docs: fall back to first child page for sidebar folders without an index (#3009) [nest] Fix NestJS Vercel build output (#2988) Avoid resolving run data for background steps (#2993) chore(docs): update @vercel/geistdocs to 1.14.0 (#3002) fix(docs): add version-switcher fallback redirects for pages missing in one version (#3003) ci: update opencode to 1.18.4 and switch backport AI model to claude-fable-5 (#3006) ... # Conflicts: # docs/content/docs/v4/deploying/meta.json # docs/content/docs/v5/deploying/meta.json # packages/core/src/runtime.ts # packages/world-local/src/index.ts # packages/world-postgres/src/index.ts # packages/world/src/events.ts # packages/world/src/interfaces.ts # packages/world/src/recovery.ts # workbench/nest/src/main.ts # workbench/sveltekit/src/hooks.server.ts
Summary
Salvages the still-valid, verified improvements from the stale AI-generated audit in #1516 and drops everything that no longer applies. #1516 predates the v4/v5 docs split and the substantial reference-doc rework since, and several of its claims were wrong. Every change here was checked against current
mainsource before applying.Scope is v5 only — v5 is the current source of truth. v4 docs describe the shipped 4.x packages and are intentionally left alone (see the error-text note below).
What changed (all verified against source)
starterror text — "Workflow Development Kit" → "Workflow SDK" instart.mdx+ 10 getting-started pages. Source emits the new string (packages/core/src/runtime/start.ts, renamed in Rename 'Workflow Development Kit' / 'DevKit' to 'Workflow SDK' #1595). v4 is not touched: noworkflow@4.xtag ever emitted "Workflow SDK", so v4 docs correctly quote the old message.define-hook— corrected a wrong return type.TypedHook.resume()returnsPromise<HookEntity>and throwsHookNotFoundError; the docs claimed it could returnnulland the example did aif (!result)check that can never fire. Fixed the signature block and the example (try/catch +HookNotFoundError.is).fatal-error— replaced the broken placeholder TSDoc (interface Errorwith mangled JSDoc) with the real shape:message+fatalproperties and theFatalError.is()static, matching theworkflow-errors/*page convention.resume-webhook— the Returns section listed only the manualrespondWith()case; now enumerates all three outcomes (default202 Accepted, configured staticResponse, manualResponse).sleep— it was described as "a special type of step function"; it is a built-in runtime primitive backed by a timer event, not a step.fetch— the custom-wrapper example now callsglobalThis.fetch(calling the imported workflowfetchinside a"use step"nests a step in a step); removed a bullet describing amaxRetriesoption the example never set.Deliberately dropped from #1516 (not applied)
withWorkflowworkflows.lazyDiscovery/WORKFLOW_NEXT_LAZY_DISCOVERY/ "Next ≥ 16.2.0-canary.48" — no such option, env var, or version gate exists inpackages/next. Fabricated. The currentwith-workflow.mdxis already correct; applying docs: audit and align API reference with source #1516 would have regressed it (it also mislabeled theWORKFLOW_TARGET_WORLDvalues).workflow-apioverviewgetWorldmove — already done onmain(there's a dedicatedworkflow-runtimesection).get-step-metadata/get-workflow-metadatareturn tables — those pages already auto-render the real types via<TSDoc>; hand tables would duplicate and drift.workflow-aiprovider-subpath section — that surface is now documented as deprecated in favor of@ai-sdk/workflow; left to a maintainer.workflow/indexexecution-context reorg — subjective restructuring; the current page has diverged (addssetAttributes/getWritable) and isn't wrong, just flat.Validation
@workflow/docs-typecheck(test:docs) passes for all changed files — the new/edited code samples typecheck against the built packages.fumadocs-mdxcompiles the content collection with no parse errors.Docs Preview
Base:
workflow-docspreview (behind Vercel deployment protection — requires team access).workflow/define-hookworkflow/fatal-errorworkflow/fetchworkflow/sleepworkflow-api/resume-webhookworkflow-api/start🤖 Generated with Claude Code