●Change8

Migrating to esbuild v0.25.0

Version v0.25.0 introduces 5 breaking changes. This guide details how to update your code.

Released: 2/8/2025

5
Breaking Changes
4
Migration Steps
4
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

servesourceMappingURLsources@esbuild/netbsd-arm64

Breaking Changes

●Issue #1

CORS is now disabled by default on the development server; requests will be denied if the 'Host' header does not match the one provided to --serve.

●Issue #2

The serve() API call now returns an array of 'hosts' instead of a single 'host' string.

●Issue #3

In watch mode, esbuild now deletes all output files if a rebuild fails, rather than leaving the old files in place.

●Issue #4

CSS nesting expansion no longer uses :is() to collapse levels to avoid exponential blow-up, which may change the structure of generated CSS when nesting is unsupported.

●Issue #5

Source map path references are now treated as URLs instead of file paths, affecting how spaces and file:// schemes are handled.

Migration Steps

  1. 1
    Pin the exact version of esbuild to '0.24.0' or use a strict range like '^0.24.0' to manage breaking changes.
  2. 2
    If using the development server, ensure clients send a matching 'Host' header or use a proxy to customize server behavior.
  3. 3
    Update code calling the serve() API to handle the 'hosts' array instead of the 'host' string.
  4. 4
    Verify watch mode workflows that might rely on old output files persisting after a failed build.

Release Summary

This release addresses a security vulnerability in the development server, introduces breaking changes to the serve() API and watch mode file handling, and fixes several CSS nesting and source map correctness issues.

Need More Details?

View the full release notes and all changes for esbuild v0.25.0.

View Full Changelog