Enable nodejs_compat by default for new projects created by C3

[irvinebroque]

refs #7388

We've gone back and forth on this in the past — but in practice, have found that:

1. People are most successful in getting started when nodejs_compat is enabled. Hit the ground running, and NPM packages you want to use are more likely to work.
2. When nodejs_compat is not enabled by default for new projects, products like Hyperdrive, or tutorials that use any NPM packages, need to explain extra steps and caveats to developers. Steps that are easy to miss, or misunderstand.

Getting the ecosystem using shared standards is important. That's why WinterTC exists, why all the awesome work that @jasnell and others do matters. How we get there is by working with WinterTC and the broader community — not by holding back nodejs_compat to developers getting started building Workers. The whole point is that developers and open-source maintainers shouldn't have to navigate a maze of differences — and enabling nodejs_compat for new projects furthers that goal.

We're going to keep making nodejs_compat better, more native to the Workers Runtime, and more comprehensive. And listen to what the vast majority of people want and expect when starting new projects. Disabling nodejs_compat is just one line of configuration to remove :)

---

Implementation approach

Instead of manually adding nodejs_compat to each template's wrangler.jsonc file, this change adds the flag automatically in C3's updateWranglerConfig function. This approach:

• Centralizes the logic in one place rather than duplicating across templates
• Handles both JSON/JSONC and TOML config formats
• Preserves any existing compatibility flags
• Skips adding nodejs_compat if any of the following are already present:
  • nodejs_compat (already enabled)
  • nodejs_compat_v2 (newer version)
  • no_nodejs_compat (explicitly disabled)
• Skips adding nodejs_compat for Python projects since nodejs_compat is not compatible with Python workers

The Python check (ctx.args.lang !== "python") is performed in updateWranglerConfig before calling the helper functions, making the control flow clearer.

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: This is a sensible default change that doesn't require user action or documentation updates

Human review checklist:

• Verify addNodejsCompatFlag and addNodejsCompatFlagToToml correctly handle edge cases (existing flags, nodejs_compat_v2, no_nodejs_compat)
• Confirm the flag ordering (nodejs_compat first, then existing flags) is acceptable
• Verify Python project detection (ctx.args.lang !== "python") correctly identifies all Python templates

Devin PR requested by @petebacondarwin

Link to Devin run: https://app.devin.ai/sessions/7a606cdbe6d148a48d02975f027bf808

[changeset-bot]

🦋 Changeset detected

Latest commit: 7923b0b

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

[github-actions]

A wrangler prerelease is available for testing. You can install this latest build in your project with:

npm install --save-dev https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-wrangler-8310

You can reference the automatically updated head of this PR with:

npm install --save-dev https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/prs/8310/npm-package-wrangler-8310

Or you can use npx with this latest build directly:

npx https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-wrangler-8310 dev path/to/script.js

Additional artifacts:

cloudflare-workers-bindings-extension:

wget https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-workers-bindings-extension-8310 -O ./cloudflare-workers-bindings-extension.0.0.0-v60c7bd564.vsix && code --install-extension ./cloudflare-workers-bindings-extension.0.0.0-v60c7bd564.vsix

create-cloudflare:

npx https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-create-cloudflare-8310 --no-auto-update

@cloudflare/kv-asset-handler:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-kv-asset-handler-8310

miniflare:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-miniflare-8310

@cloudflare/pages-shared:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-pages-shared-8310

@cloudflare/unenv-preset:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-unenv-preset-8310

@cloudflare/vite-plugin:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-vite-plugin-8310

@cloudflare/vitest-pool-workers:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-vitest-pool-workers-8310

@cloudflare/workers-editor-shared:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-workers-editor-shared-8310

@cloudflare/workers-shared:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-workers-shared-8310

@cloudflare/workflows-shared:

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/13596487290/npm-package-cloudflare-workflows-shared-8310

Note that these links will no longer work once the GitHub Actions artifact expires.

---

wrangler@3.111.0 includes the following runtime dependencies:

Package	Constraint	Resolved
miniflare	workspace:*	3.20250214.1
workerd	1.20250214.0	1.20250214.0
workerd --version	1.20250214.0	2025-02-14

Please ensure constraints are pinned, and miniflare/workerd minor versions match.

[thomasgauvin]

I would lean towards all docs that require nodejs_compat to avoid errors should include it in the steps, even if nodejs_compat becomes a default, in case for some reason, someone has a cloudflare worker without nodejs compat enabled. So I would lean towards leaving https://developers.cloudflare.com/hyperdrive/get-started/#enable-nodejs-compatibility (maybe switch 'Enable' to 'Ensure') and I think we should still merge cloudflare/cloudflare-docs#19860

[Cherry]

Generally I love to see this. nodejs_compat in the runtime is a great addition and something I use on basically all my projects. I have two concerns that would be great to get some insight on though:

• 🐛 BUG: Unnecessary polyfills? #7108 - today, the new nodejs_compat inflates basic worker sizes (gzip) by almost 1000%. It's not a major problem, but it would be nice if this wasn't so inflated and looking at the output worker was easier.

• And then the versioning/backwards compatibility story for nodejs_compat. As so much of this is baked into wrangler now via unenv, and as we recently saw in remove functions that are removed from node:util #7942, I think nodejs_compat not being versioned is going to really cause issues/confusion/frustration in the future.

[claude]

Claude finished @irvinebroque's task —— View job

---

Changeset Review

• Read changeset guidelines
• Review changeset file
• Validate against criteria
• Post review results

---

✅ All changesets look good

[pkg-pr-new]

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: 0c1e2e0

[vicb]

Tests not necessary because: Don't think anything tests what compat flags enabled

I would rephrase to already tested - because there are trivial ways to tests what the flag enables

[vicb]

Generally I love to see this. nodejs_compat in the runtime is a great addition and something I use on basically all my projects. I have two concerns that would be great to get some insight on though:

• 🐛 BUG: Unnecessary polyfills? #7108 - today, the new nodejs_compat inflates basic worker sizes (gzip) by almost 1000%. It's not a major problem, but it would be nice if this wasn't so inflated and looking at the output worker was easier.
• And then the versioning/backwards compatibility story for nodejs_compat. As so much of this is baked into wrangler now via unenv, and as we recently saw in remove functions that are removed from node:util #7942, I think nodejs_compat not being versioned is going to really cause issues/confusion/frustration in the future.

Unnecessary polyfills -> we have removed a lot of them already and will keep removing more. "almost 1000%" is exaggerating, it mostly adds a constant size (a few kB).

I don't think versioning should be a concern. It is handled via the compat date. But please let us know if you have a specific (recent) concern. Thanks.

[Cherry]

I don't think versioning should be a concern. It is handled via the compat date. But please let us know if you have a specific (recent) concern. Thanks.

The versioning concerns were solved with remove_nodejs_compat_eol_v24, etc. flags, thanks!

[penalosa]

This should be added to config files by C3, rather than manually added to each one. Blocking so we don't accidentally merge this, but I'll push a commit to fix soon

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional flags.