Skip to content

Fix stale TypeScript SDK docs on bundle metadata and packing setup - #72115

Merged
jason810496 merged 1 commit into
apache:mainfrom
ColtenOuO:docs/typescript-sdk-fix-metadata-sidecar-and-esbuild
Aug 27, 2026
Merged

Fix stale TypeScript SDK docs on bundle metadata and packing setup#72115
jason810496 merged 1 commit into
apache:mainfrom
ColtenOuO:docs/typescript-sdk-fix-metadata-sidecar-and-esbuild

Conversation

@ColtenOuO

Copy link
Copy Markdown
Contributor

Summary

airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst still described NodeCoordinator's bundles_root as accepting a bundle.mjs "with embedded metadata, or with an airflow-metadata.yaml sidecar." That sidecar fallback was removed in #70273 (Remove airflow-metadata.yaml sidecar support from NodeCoordinator) — airflow-ts-pack always embeds the manifest in bundle.mjs itself, and NodeCoordinator now only reads that embedded metadata; no tool produces the sidecar file, and _bundle_metadata.py's YAML-sidecar parsing helpers are effectively dead code from the doc's point of view. The doc never got updated when the code changed, so it describes a deployment shape (a hand-written airflow-metadata.yaml next to the bundle) that Airflow no longer supports.

Separately, the "Building and packaging" section jumped straight to running npx airflow-ts-pack src/main.ts --outdir dist without ever showing how to get there: it never mentioned installing the apache-airflow-ts-sdk npm package, and it didn't mention that esbuild — the bundler airflow-ts-pack uses — is an optional peer dependency that the runtime install intentionally skips (see ts-sdk/package.json's peerDependenciesMeta.esbuild.optional). A user following the doc exactly as written would run npx airflow-ts-pack in a project that never had esbuild installed and hit a failure with no explanation in the doc of why, or what to install instead. The ts-sdk/README.md already has the correct sequence (npm install --save-dev esbuild before packing); the RST doc had drifted from it.

Change

  • Removed the stale airflow-metadata.yaml sidecar mention from the NodeCoordinator configuration table; bundles_root now just documents the current, single supported shape (a bundle.mjs with embedded metadata).
  • Added a "Prerequisites" bullet showing npm install apache-airflow-ts-sdk for authoring task handlers.
  • Added an explanation plus npm install --save-dev esbuild to the "Building and packaging" section, before the airflow-ts-pack invocation, so the documented steps actually work end-to-end for a fresh project.

Docs-only change.


Was generative AI tooling used to co-author this PR?
  • Yes — Claude Code (Sonnet 5)

The NodeCoordinator config table still described bundles_root as
accepting a bundle.mjs with an airflow-metadata.yaml sidecar, but that
fallback was removed in apache#70273 and the coordinator now only reads
metadata embedded in the bundle by airflow-ts-pack. The packing section
also jumped straight to running airflow-ts-pack without showing that
apache-airflow-ts-sdk and its optional esbuild peer dependency need to
be installed first, so following the doc as written fails.
@ColtenOuO

Copy link
Copy Markdown
ContributorAuthor

cc. @jason810496

@jason810496jason810496 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We intentionally keep the npm install ... command out of the airflow-core docs until the NPM package is ready.

Thanks for adding these back.

@jason810496
jason810496 merged commit f727ea8 into apache:mainAug 27, 2026
70 checks passed
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@ColtenOuO@jason810496