Migration Guide

Purpose and Scope

Use this page when upgrading an existing Anthropic TypeScript SDK integration to the latest package generation. The repository migration guide frames the upgrade as mostly small application-code edits, but it also calls out runtime requirements and several API-shape changes that can break code relying on older generated method signatures or older response objects. The main project-level shift is that the SDK now uses the built-in Web Fetch API across platforms instead of the older node-fetch model, and the migration guide describes this alongside the goal of reducing dependency surface. Sources: MIGRATION.md

The migration is not only a dependency update. It is also an opportunity to audit how your application handles streaming response bodies, response headers, path parameters, and beta Managed Agents resource methods. The safest approach is to first upgrade the package, run the repository-provided migration CLI in dry-run mode, review the generated changes, and then manually inspect any call sites that depend on response internals or multi-parameter paths. Release notes should be reviewed in parallel so you can connect code changes to the SDK version you are adopting. Sources: MIGRATION.md, CHANGELOG.md

Relevant Source Files

• MIGRATION.md — Primary reader-facing migration guide. It describes the built-in Web Fetch API change, the migration CLI, environment requirements, and breaking changes around response objects, named path parameters, and URI-encoded path parameters.
• bin/migration-config.json — Machine-readable configuration for the migration tool. It identifies the package, client class names, affected generated methods, current parameter shapes, and old parameter shapes that the tool can rewrite.
• CHANGELOG.md — Release-history companion for migration work. Use it to correlate the version you are adopting with behavior changes, fixes, and any additional notes not covered by the focused migration guide.

Migration Workflow

Start by upgrading the installed SDK package in your application, then run the migration command against the folders that contain your TypeScript or JavaScript source. The guide’s command uses the installed package binary under your local dependencies and accepts one or more source folders. In review-oriented teams, run the command with dry-run first so the tool prints or previews edits without writing them to disk. That lets you separate mechanical rewrites from manual decisions, which is especially helpful when migration touches beta resources or code paths with test coverage gaps. Sources: MIGRATION.md

./node_modules/.bin/anthropic-ai-sdk migrate ./your/src/folders
./node_modules/.bin/anthropic-ai-sdk migrate --dry ./your/src/folders

After the dry run, inspect each changed call site rather than merging the output blindly. The migration configuration encodes method-level parameter transformations, so it is useful for straightforward generated-method rewrites, but it cannot fully understand every application-level abstraction around the SDK. For example, a wrapper function may forward path identifiers in the old order, construct request options separately, or hide response conversion behind a helper. Treat the CLI as the first pass, then run your unit tests, integration tests, and representative streaming flows to confirm behavior. Sources: MIGRATION.md, bin/migration-config.json

Environment and Runtime Requirements

The migration guide raises the minimum supported runtime and tooling versions to Node.js 20 LTS, TypeScript 4.9, and Jest 28. That matters because some migration issues are not visible at the SDK call-site level. A project pinned to an older Node release may compile but fail when it reaches Web platform primitives, and an older TypeScript configuration may report confusing type errors around the newer generated declarations. Plan the runtime upgrade before changing production traffic, and ensure your continuous integration image uses the same major versions you expect in deployment. Sources: MIGRATION.md

Jest deserves special attention because many SDK users validate streaming, error, and response-handling behavior in tests. If your test environment previously mocked node-fetch-specific objects, update the mocks to Web Fetch-compatible Request, Response, Headers, and stream behavior. This is also a good moment to remove assumptions about Node readable streams from tests that exercise raw responses. The migration guide’s examples show that Web response bodies need explicit conversion when existing code wants to pipe them through Node stream utilities. Sources: MIGRATION.md

Breaking Changes to Audit

The most visible response-object change affects code that uses withResponse or asResponse and then accesses node-fetch-specific properties. Under the migrated SDK, response bodies are Web ReadableStream instances instead of Node Readable streams. Existing code such as piping the body directly to process output must first convert the Web stream using Node’s stream utilities. Similarly, APIError headers are now Web Headers objects rather than plain records. Code that indexes headers as ordinary object properties should switch to the standard Headers methods so it works consistently across supported runtimes. Sources: MIGRATION.md

Named path parameters are the other major migration category. The guide explains that methods with multiple path parameters generally keep only the last path parameter positional, while earlier path parameters move into a named parameters object. This avoids a common footgun where two identifiers of the same primitive type could be passed in the wrong order without a type-level signal. The migration configuration shows this concretely for beta environment work methods: the current shape takes the work identifier positionally and moves the environment identifier into the params object, while the old shape accepted both as positional path parameters. Sources: MIGRATION.md, bin/migration-config.json

URI encoding is also part of the migration checklist. The guide states that path parameters are now encoded by default and warns users to stop manually encoding values before passing them to the SDK. This is subtle because manually encoded strings may look correct in logs but become double-encoded when the SDK performs its own encoding. Search for wrappers that call URI encoding helpers before invoking resource methods, especially around identifiers that can contain slashes, spaces, or provider-specific characters. The right migrated code passes the raw logical identifier and lets the SDK build the path safely. Sources: MIGRATION.md

Migration CLI Configuration Mapping

The migration configuration identifies the package as the Anthropic SDK package, the public client class as Anthropic, and the base client class as BaseAnthropic. Its methods array describes old and new parameter lists for generated resource methods. Each entry includes a resource base, a method name, and ordered parameter descriptors with type, key, and path location metadata. That structure is what lets the CLI recognize a call such as a beta environments work method and rewrite the argument list toward the new named-parameter convention. Sources: bin/migration-config.json

Use the method mapping as a checklist for code review. If your application uses Managed Agents beta resources, search for the affected bases and verify the new call signatures directly in your editor. Pay extra attention to internal helper functions that accept several identifiers and then call the SDK. The migration tool may update direct method calls, but your own helper signatures may still preserve the old mental model. Renaming local variables or changing helper parameter objects to mirror the SDK can prevent future ordering mistakes. Sources: MIGRATION.md, bin/migration-config.json

Validation and Next Steps

A completed migration should leave you with an upgraded package, source changes from the CLI where applicable, manual fixes for Web Fetch response handling, and passing tests under the new minimum toolchain. For confidence, add focused checks around raw responses, error-header handling, streaming bodies, path identifiers that contain special characters, and beta resource methods with multiple path parameters. Then read the changelog for the target release range and follow the related runtime, authentication, messages, streaming, and beta resource reference pages for deeper API-specific validation. Sources: MIGRATION.md, CHANGELOG.md