Deprecation of `contract bindings typescript` shipped before its replacement plugin was released

[y4hyya]

What version are you using?

Stellar CLI 28.1.0, which added the deprecation (#2724, #2725), and @stellar/stellar-sdk 17.1.0, the latest release on npm as of Sep 26, 2026.

What did you do?

Followed the migration path from the new deprecation warning (source):

`stellar contract bindings typescript` is deprecated. Use the JavaScript Stellar SDK instead: https://github.com/stellar/js-stellar-sdk#cli

The linked README says that once the native command is removed, stellar contract bindings typescript will resolve to the stellar-contract-bindings-typescript plugin from stellar/js-stellar-sdk#1738.

What did you expect to see?

A way to keep using the command today, and a warning that tells users what they need to do.

What did you see instead?

1. The plugin is not released. Add Stellar CLI plugin for generating TypeScript bindings js-stellar-sdk#1738 merged on Sep 21, 2026 and is still listed under Unreleased. The published 17.1.0 only ships stellar-js (package.json). So following the warning today means moving to npx @stellar/stellar-sdk generate now, then moving back to stellar contract bindings typescript once the plugin ships.
2. The plugin is not a drop in replacement. It is a Node script that the CLI finds on PATH (lookup), so it needs Node and a global install of the SDK. Environments that only have the stellar binary, like CI images, will break once the native command is removed. The JS CLI also does not read the CLI config, so contract aliases (accepted natively) and networks added with stellar network add are not resolved. It only accepts mainnet, testnet, futurenet or localnet (source), and since the CLI's default local network is named local (source), --network local fails.
3. The generated package changes. The native template pins @stellar/stellar-sdk to ^16.0.1 (source), while the plugin pins the SDK version it ships in, 17.x or later (source).

Suggestion

1. Publish the SDK release that contains the plugin before the native command is removed, and name that version in the warning.
2. Make the warning say what to do, for example: install @stellar/stellar-sdk (that version or later) globally and keep using stellar contract bindings typescript. Mention the differences above.
3. Announce a removal date, counted from the plugin's release rather than from the deprecation, so users are not asked to migrate before the replacement exists.

[aolieman]

Completely agree that this is not handled well. This will be a breaking change for many users, and it needs to be communicated better than the current deprecation notice.

If "AI now cheaply makes the changes needed on the consumer's end" was part of the consideration, please also consider that all models whose training predates this deprecation will still expect stellar contract bindings typescript to work without any additional setup. This arguably makes the problem worse, and causes a waste of time and tokens.

[tupui]

Adding my voice here as I did on Discord as well. The communication in general is not good. You need to change that really. I am leaving here a reference showing how we handle this on a very large project, SciPy: https://docs.scipy.org/doc/scipy/dev/core-dev/index.html#deprecations

---

There are various reasons for wanting to remove existing functionality: it’s buggy, the API isn’t understandable, it’s superseded by functionality with better performance, it needs to be moved to another SciPy submodule, etc.

In general, it’s not a good idea to remove something without warning users about that removal first. Therefore, this is what should be done before removing something from the public API:

1. Propose to deprecate the functionality on the scipy-dev forum and get agreement that that’s OK.
2. Add a DeprecationWarning for it, which states that the functionality was deprecated, and in which release. For Cython APIs, see Deprecating public Cython APIs for the practical steps.
3. Mention the deprecation in the release notes for that release.
4. Wait till at least 6 months after the release date of the release that introduced the DeprecationWarning before removing the functionality.
5. Mention the removal of the functionality in the release notes.
   The 6 months waiting period in practice usually means waiting two releases. When introducing the warning, also ensure that those warnings are filtered out when running the test suite so they don’t pollute the output.

It’s possible that there is reason to want to ignore this deprecation policy for a particular deprecation; this can always be discussed on the scipy-dev forum.

---

This has worked for now more than 20y for SciPy. Please consider this.

[y4hyya]

Thanks both, I appreciate you adding to this.

A quick note to keep this issue in sync with the Discord conversation from last night, since that is where the maintainers replied:

1. @fnando said the JS SDK release with the plugin will be kicked off as soon as possible. That covers the first point above, so thank you for the quick turnaround.
2. @leighmcculloch explained the reasoning behind the move: with the generator inside the CLI, you had to be on the same SDK version the CLI was generating for, and moving it into the SDK removes that coupling. That makes sense to me, and it is really the same problem as the third point above, just seen from the other side.

To be clear about scope, this issue is not questioning the move itself. It is only about the order of the steps and what the warning tells people to do.

One thing I would gently flag is that the SDK release on its own will not close this. As long as the built in command exists, it takes precedence over the plugin, as the README notes, so stellar contract bindings typescript keeps running the old generator even for people who install the SDK globally. (The dashed form, stellar contract-bindings-typescript, should reach the plugin straight away if anyone wants to try it early.) So points 2 and 3 stay relevant until the removal is planned.

If it helps, I would be glad to open a PR for the warning text once the SDK version with the plugin is known: name that version, say to install it globally and keep using the command, and mention the differences above. Happy to include the help doc comment and a test for the message as well. Just let me know.