diff --git a/src/content/changelog/workers/2026-10-20-source-maps-on-by-default.mdx b/src/content/changelog/workers/2026-10-20-source-maps-on-by-default.mdx new file mode 100644 index 00000000000..88a9890a42a --- /dev/null +++ b/src/content/changelog/workers/2026-10-20-source-maps-on-by-default.mdx @@ -0,0 +1,34 @@ +--- +title: Wrangler and cf now upload source maps by default +description: Stack traces from your Workers point at your original source without any configuration +products: + - workers + - cf +date: 2026-10-20 +--- + +import { WranglerConfig } from "~/components"; + +From Wrangler 4.150.0, [`wrangler deploy`](/workers/wrangler/commands/general/#deploy), [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload), and [`wrangler preview`](/workers/wrangler/commands/workers/#preview) generate and upload [source maps](/workers/observability/source-maps/) by default. You no longer need to set `upload_source_maps` to get stack traces with your original file names and line numbers. + +[`cf deploy`](/cf/) also uploads source maps by default. With the [Cloudflare Vite plugin](/workers/vite-plugin/) 1.64.0 or later, Worker builds generate source maps by default, and `cf deploy` uploads every source map in the build output. + +![Stack Trace with Source Map remapping](~/assets/images/workers-observability/with-source-map.png) + +Remapped stack traces show up in [Workers Logs](/workers/observability/logs/workers-logs/), [real-time logs](/workers/observability/logs/real-time-logs/), [Tail Workers](/workers/observability/logs/tail-workers/), and [Workers Issues](/workers/observability/issues/). Source maps are applied after your Worker runs, so they don't affect CPU time, bundle size, or cold starts. + +If your Worker uses a custom build, Wrangler uploads any external source maps it finds. Maps it can't resolve, such as inline `data:` source maps, are skipped instead of failing the upload. Set `upload_source_maps` to `true` if you'd prefer the upload to fail. + +To opt out with Wrangler, set `upload_source_maps` to `false`: + + + +```jsonc +{ + "upload_source_maps": false +} +``` + + + +To opt out with `cf` or the Cloudflare Vite plugin, set `build.sourcemap` to `false` for your Worker's Vite environment. Refer to [Disable source maps](/workers/observability/source-maps/#disable-source-maps). diff --git a/src/content/docs/cf/wrangler/migrate.mdx b/src/content/docs/cf/wrangler/migrate.mdx index bbe22552601..b7c8d90e5fe 100644 --- a/src/content/docs/cf/wrangler/migrate.mdx +++ b/src/content/docs/cf/wrangler/migrate.mdx @@ -411,11 +411,15 @@ runs Vite directly, so run the command yourself first, for example ### Source maps {/* source-maps */} -With the Vite bundler, `cf migrate` lists `upload_source_maps` in its required -item for build settings. To keep uploading Worker source maps, turn on -`build.sourcemap` for the Worker's Vite environment, then delete the TODO -comment. By default, the Cloudflare Vite plugin beta names the Worker's -environment `ssr`: +With the Vite bundler, `cf migrate` does not move `upload_source_maps` and +reports it as a follow-up item. `cf deploy` uploads every source map in the +build output, and the Cloudflare Vite plugin generates source maps for the +Worker's Vite environment by default from version 1.64.0. You do not need to +replace `upload_source_maps: true`. + +To stop uploading source maps, set `build.sourcemap` to `false` for the +Worker's Vite environment. By default, the Cloudflare Vite plugin beta names +the Worker's environment `ssr`: ```ts title="vite.config.ts" {6-12} import { cloudflare } from "@cloudflare/vite-plugin"; @@ -426,13 +430,16 @@ export default defineConfig({ environments: { ssr: { build: { - sourcemap: true, + sourcemap: false, }, }, }, }); ``` +On earlier versions of the Cloudflare Vite plugin, set `build.sourcemap` to +`true` to generate source maps. + How `cf migrate` reports source maps can change during the beta. ### D1 migrations {/* d1-migrations */} diff --git a/src/content/docs/workers/observability/profiling-in-production.mdx b/src/content/docs/workers/observability/profiling-in-production.mdx index 5eb8a213277..cdeca76c3b7 100644 --- a/src/content/docs/workers/observability/profiling-in-production.mdx +++ b/src/content/docs/workers/observability/profiling-in-production.mdx @@ -31,7 +31,7 @@ The historical log time range and filters do not control capture. A profile reco Enable source maps before capturing a profile so the flamegraph shows readable function names and file locations instead of minified code. If your Worker bundles and minifies code, frames without source maps reference the minified bundle and are difficult to read. -To enable source maps, set `upload_source_maps` to `true` in your [Wrangler configuration](/workers/wrangler/configuration/), then deploy your Worker. Refer to [Source maps and stack traces](/workers/observability/source-maps/) for details. +Wrangler uploads source maps by default from Wrangler 4.150.0. On earlier versions, set `upload_source_maps` to `true` in your [Wrangler configuration](/workers/wrangler/configuration/), then deploy your Worker. Refer to [Source maps and stack traces](/workers/observability/source-maps/) for details. ## Capture a profile diff --git a/src/content/docs/workers/observability/source-maps.mdx b/src/content/docs/workers/observability/source-maps.mdx index ce58e63ee31..0c6cd603103 100644 --- a/src/content/docs/workers/observability/source-maps.mdx +++ b/src/content/docs/workers/observability/source-maps.mdx @@ -14,7 +14,9 @@ import { Render, WranglerConfig, FileTree } from "~/components"; ## Enable source maps -Enable source maps for every JavaScript or TypeScript Worker to get stack traces with original file names and line numbers. Add the following to your Worker's [Wrangler configuration](/workers/wrangler/configuration/): +Source maps are uploaded by default from Wrangler 4.150.0. When you run [`wrangler deploy`](/workers/wrangler/commands/general/#deploy), [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload), or [`wrangler preview`](/workers/wrangler/commands/workers/#preview), Wrangler generates and uploads source maps for your Worker, so stack traces show original file names and line numbers without any configuration. + +By default, Wrangler skips source maps it cannot resolve, such as inline `data:` source maps or a `sourceMappingURL` that points to a missing file, and continues the upload. To fail the upload instead, set `upload_source_maps` to `true` in your Worker's [Wrangler configuration](/workers/wrangler/configuration/): @@ -26,8 +28,9 @@ Enable source maps for every JavaScript or TypeScript Worker to get stack traces -When `upload_source_maps` is set to `true`, Wrangler will automatically generate and upload source map files when you run [`wrangler deploy`](/workers/wrangler/commands/general/#deploy) or [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload). -​​ +On earlier versions of Wrangler, source maps are only uploaded when `upload_source_maps` is set to `true`. + +[`cf deploy`](/cf/) also uploads source maps by default. It uploads every source map in the build output, and `cf build` generates them for Workers built with the Cloudflare Vite plugin 1.64.0 or later, or with Wrangler 4.151.0 or later. To opt out, [disable source maps](#disable-source-maps) in your build. :::note @@ -37,9 +40,11 @@ Miniflare can also [output source maps](https://miniflare.dev/developing/source- ### Frameworks and custom builds -When Vite or another build tool bundles your Worker, that tool must generate source maps. Setting `upload_source_maps` only enables uploading maps from an existing build. +When Vite or another build tool bundles your Worker, that tool must generate source maps. Wrangler only uploads maps that already exist in the build output. + +The [Cloudflare Vite plugin](/workers/vite-plugin/) generates external maps for your [Worker environment](/workers/vite-plugin/reference/vite-environments/) by default from version 1.64.0, unless you set Vite's `build.sourcemap` or the Worker's `upload_source_maps`. Maps are not added to the client environment, so they do not end up in your public assets. -With the [Cloudflare Vite plugin](/workers/vite-plugin/), enable external maps for your [Worker environment](/workers/vite-plugin/reference/vite-environments/). For a Worker environment named `my_worker`, use: +On earlier versions, enable external maps for your Worker environment. For a Worker environment named `my_worker`, use: ```ts title="vite.config.ts" import { defineConfig } from "vite"; @@ -59,7 +64,23 @@ Use `ssr` when your framework assigns the Worker to that environment. The plugin For other build tools, emit external map files and preserve their `sourceMappingURL` references in the generated JavaScript. Keep server maps out of your public assets directory. -To disable uploads, set `upload_source_maps` to `false` or pass `--no-upload-source-maps` when deploying or uploading a version. +### Disable source maps + +To disable uploads, set `upload_source_maps` to `false`: + + + +```jsonc +{ + "upload_source_maps": false +} +``` + + + +You can also pass `--no-upload-source-maps` to `wrangler deploy` or `wrangler versions upload`. + +With the Cloudflare Vite plugin, you can instead set `build.sourcemap` to `false` for the Worker environment. `cf deploy` uploads every source map in the build output, so with a `cf` project, turn off source map generation in your build to opt out. ## Stack traces diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 77a7c9b255c..6093beb3c65 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1884,10 +1884,13 @@ In many cases, this allows you to work provide just enough of an API to make a d [Source maps](/workers/observability/source-maps/) translate compiled and minified code back to the original code that you wrote. Source maps are combined with the stack trace returned by the JavaScript runtime to present you with a stack trace. -Enable source map uploads for JavaScript and TypeScript Workers. Frameworks and custom builds must also [generate maps](/workers/observability/source-maps/#frameworks-and-custom-builds). +Source maps are uploaded by default for JavaScript and TypeScript Workers. Frameworks and custom builds must also [generate maps](/workers/observability/source-maps/#frameworks-and-custom-builds). -- `upload_source_maps` - - When `upload_source_maps` is set to `true`, Wrangler will automatically generate and upload source map files when you run [`wrangler deploy`](/workers/wrangler/commands/general/#deploy) or [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload). +- `upload_source_maps` + - Controls whether Wrangler generates and uploads source map files when you run [`wrangler deploy`](/workers/wrangler/commands/general/#deploy), [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload), or [`wrangler preview`](/workers/wrangler/commands/workers/#preview). + - When unset, Wrangler uploads source maps and skips any it cannot resolve. This is the default from Wrangler 4.150.0. Earlier versions only upload source maps when this is set to `true`. + - When set to `true`, Wrangler fails the upload if a source map cannot be resolved. + - When set to `false`, Wrangler does not upload source maps. Example: @@ -1895,7 +1898,7 @@ Example: ```jsonc { - "upload_source_maps": true, + "upload_source_maps": false, } ```