Switch wrangler and workers-utils to tsdown

[ascorbic]

Wrangler uses some external types that aren't dependencies, because the code itself is bundled. This meant that the types are unavailable in production. This was a massive pain to try and get working in tsup, so I've migrated to tsdown. This needed some changes in the config, particularly as it uses a custom esbuild plugin which I ported to a rolldown plugin instead. I've also had to externalise some dependencies because they didn't play nicely with the bundling.

---

• Tests
  • [ ] Tests included
  • [x] Tests not necessary because: just types
• Public documentation
  • [ ] Cloudflare docs PR(s):
  • [x] Documentation not necessary because: just types
• Wrangler V3 Backport
  • [ ] Wrangler PR:
  • [x] Not necessary because: bug not present in v3

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: f7291fcdf0fccd6a0fd4e36af29bba8bc6229c1b

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new[bot]]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@11248

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@11248

miniflare

npm i https://pkg.pr.new/miniflare@11248

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@11248

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@11248

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@11248

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@11248

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@11248

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@11248

wrangler

npm i https://pkg.pr.new/wrangler@11248

commit: 7f5f8fd

[github-actions[bot]]

Failed to automatically backport this PR's changes to Wrangler v3. Please manually create a PR targeting the v3-maintenance branch with your changes. Thank you for helping us keep Wrangler v3 supported!

Depending on your changes, running git rebase --onto v3-maintenance main mk/wrangler/bundle-types might be a good starting point.

Notes:

• your PR branch should be named v3-backport-11248
• add the skip-v3-pr label to the current PR to stop this workflow from failing

[ascorbic]

@claude

[claude[bot]]

Claude finished @ascorbic's task —— View job

---

Code Review: Switch wrangler and workers-utils to tsdown

I've reviewed the migration from tsup to tsdown for better type handling. Here's my comprehensive analysis:

Todo List:

• [x] Read CLAUDE.md for repo guidelines
• [x] Examine the new tsdown configuration
• [x] Compare with the old tsup configuration
• [x] Review dependency externalization changes
• [x] Check package.json modifications
• [x] Review code changes for TS 5.9 compatibility
• [x] Analyze potential risks and benefits
• [x] Provide comprehensive review feedback

Review Findings

✅ Positive Changes

1. Better Type Resolution: The new tsdown config includes explicit type resolution for external packages:

   dts: {
     resolve: [
       "@cloudflare/workers-shared",
       "@cloudflare/containers-shared", 
       "@cloudflare/workers-types/experimental",
     ],
   }
   

   This addresses the core issue where external types weren't available in production.

2. Plugin Migration: The custom esbuild plugin for embedding workers has been successfully ported to a rolldown plugin with equivalent functionality. The logic for resolving workers and creating build contexts is preserved.

3. Clean Configuration: The new tsdown config is well-structured and includes proper workarounds (like the path mapping for issue #345).

⚠️ Areas of Concern

1. Dependency Externalization Risk: As noted by @penalosa's review comment, externalizing more dependencies increases runtime risk. The current externals include some that weren't external before, which could lead to:

   • Larger bundle sizes for end users
   • Potential version mismatches
   • More surface area for supply chain attacks

2. workers-utils Reverted: The PR title mentions switching both packages to tsdown, but the latest commit shows workers-utils was reverted back to tsup (packages/workers-utils/tsdown.config.ts → packages/workers-utils/tsup.config.ts). This suggests tsdown may not have worked well for that package.

3. Missing Context on TS 5.9 Changes: The review comments mention "TS 5.9" on several code changes, but there's no clear explanation of what TypeScript 5.9 compatibility issues were encountered or how they were resolved.

🔍 Technical Analysis

Configuration Differences (tsup → tsdown):

• ✅ Maintained equivalent plugin functionality
• ✅ Preserved all build settings (sourcemaps, externals, defines)
• ✅ Added explicit type resolution capabilities
• ⚠️ Changed from inject to banner for polyfills
• ⚠️ Removed import.meta.url handling (deleted import_meta_url.js)

Package.json Changes:

• ✅ Properly added tsdown dependency
• ✅ Removed tsup dependency
• ✅ Updated build scripts to use tsdown
• ✅ Changeset properly documents the fix

📝 Recommendations

1. Documentation: Consider adding a comment in the tsdown config explaining why specific packages need to be resolved for types, as this is the core problem being solved.

2. Dependency Review: The externalized dependencies should be reviewed for security and maintenance burden. Consider opening issues in tsdown/rolldown for the bundling problems that forced externalization.

3. Testing: Given that this affects the build system, ensure comprehensive testing of the generated types and bundle output.

4. Monitoring: Watch for any runtime issues in production that might stem from the newly externalized dependencies.

💯 Overall Assessment

This is a solid technical solution to a real problem. The migration maintains functional parity while solving the type availability issue that was "a massive pain" with tsup. The approach is pragmatic - when the existing tool couldn't handle the requirements, switching to a tool that could was the right call.

The code quality is good, the changeset is appropriate, and the solution addresses the core issue effectively. The main concerns are around the broader implications of dependency externalization, but those appear to be necessary tradeoffs for the type resolution benefits.

Recommendation: ✅ Approve - This solves a real pain point with a well-executed technical solution.

---