Migration Guide: Wretch v1 to v2

October 19, 2025 ยท View on GitHub

This guide outlines the breaking changes and migration steps required when upgrading from Wretch v1 to v2.

Philosophy

Wretch v2 was completely rewritten with the following goals in mind:

  • Reduce bundle size by making it modular
  • Preserve TypeScript type coverage
  • Improve the API by removing several awkward choices

Compatibility

  • wretch@1 was transpiled to es5
  • wretch@2 is transpiled to es2018

Any "modern" browser and Node.js versions >= 14 should parse the library without issues.

If you need compatibility with older browsers/Node.js versions, then either:

  • Stick with v1
  • Use polyfills
  • Configure @babel to transpile wretch

Breaking Changes

1. Addons System

Some features that were part of wretch v1 core are now split into separate addons that must be imported and registered.

Before (v1)

import wretch from "wretch"

wretch()
  .formData({ hello: "world" })
  .query({ check: true })

After (v2)

import FormDataAddon from "wretch/addons/formData"
import QueryStringAddon from "wretch/addons/queryString"
import wretch from "wretch"

// Register addons
const w = wretch().addon(FormDataAddon).addon(QueryStringAddon)

// Now the features are available
w.formData({ hello: "world" }).query({ check: true })

Affected Features (Now Addons)

The following features are now separate addons:

  • QueryString - wretch/addons/queryString
  • FormData - wretch/addons/formData
  • FormUrl - wretch/addons/formUrl
  • BasicAuth - wretch/addons/basicAuth
  • Abort - wretch/addons/abort
  • Progress - wretch/addons/progress
  • Performance - wretch/addons/perfs

Please refer to the Addons documentation for details.

2. TypeScript Types

Types have been renamed and refactored. Update your imports accordingly.

Refer to the TypeScript API documentation for the new type names.

3. Replace/Mixin Arguments

Before (v1)

Some functions used inconsistent mixin or replace arguments:

// false: do not merge the value
wretch.options({ credentials: "same-origin" }, false)

After (v2)

All functions now consistently use replace = false arguments:

// Use per-instance configuration instead of global
const api = wretch("https://api.example.com", { credentials: "same-origin" })

The default behavior (merging) is preserved.

4. HTTP Methods Extra Argument

Before (v1)

In v1, you could pass fetch options as an argument to HTTP methods:

wretch("...").get({ my: "option" })

After (v2)

The extra argument now appends a URL segment instead:

wretch("https://base.com").get("/resource/1")

// To set options, use .options() before calling the HTTP method
wretch("...")
  .options({ my: "option" })
  .get()

This change makes the API more consistent and intuitive.

5. Replay Function Renamed

Before (v1)

wretch("...").replay()

After (v2)

wretch("...").fetch()

The .replay() function has been renamed to .fetch().

Migration Checklist

  • Update minimum Node.js version to 14+
  • Import and register required addons (QueryString, FormData, etc.)
  • Update TypeScript type imports
  • Replace .replay() calls with .fetch()
  • Update HTTP method calls if passing options as arguments
  • Review replace/mixin argument usage
  • Test your application thoroughly

Benefits of v2

  • Smaller core bundle - Only include addons you need
  • Better modularity - Tree-shakeable imports
  • Improved API consistency - More intuitive method signatures
  • Maintained type safety - Full TypeScript coverage
  • Modern JavaScript - Cleaner, more performant code

Need Help?

If you encounter issues during migration:

  1. Check the API documentation
  2. Review the examples in the README
  3. Open an issue on GitHub

Staying on v1

If you need to support older environments (ES5, Node.js <14), continue using Wretch v1:

npm install wretch@^1