feat: graduate `--x-include-runtime` #8166

emily-shen · 2025-02-17T15:09:02Z

TODO: rebase on /vnext for inclusion in wrangler v4

Might be best to review commit by commit

DEVX-1615 improve logging output: d33b18a, 1b0d071
DEVX-1611 remove --x-include-runtime and consolidate type output into one file: 2b99075
DEVX-1612 prompt users to rerun wrangler types during dev: 4872cb9

This PR will turn on runtime type generation by default for wrangler types.

The --experimental-include-runtime flag will be superseded by include-runtime and include-env, both of which are true by default.

Also, the runtime types will be generated in the same file as the env types, at the location specified by path (worker-configuration.d.ts by default).

Before:

After:

Tests
- TODO (before merge)
- Tests included
- Tests not necessary because:
Wrangler E2E Tests CI Job required? (Use "e2e" label or ask maintainer to run separately)
- I don't know
- Required
- Not required because: covered by unit tests
Public documentation
- TODO (before merge)
- Cloudflare docs PR(s): [wrangler] Update instructions for accessing runtime types cloudflare-docs#20082
- Documentation not necessary because:

changeset-bot · 2025-02-17T15:09:06Z

🦋 Changeset detected

Latest commit: 5eef917

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

This PR includes changesets to release 2 packages

Name	Type
wrangler	Minor
@cloudflare/vitest-pool-workers	Patch

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 · 2025-02-17T15:13:14Z

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/13639768023/npm-package-wrangler-8166

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

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

Or you can use npx with this latest build directly:

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

Additional artifacts:

cloudflare-workers-bindings-extension:

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

create-cloudflare:

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

@cloudflare/kv-asset-handler:

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

miniflare:

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

@cloudflare/pages-shared:

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

@cloudflare/unenv-preset:

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

@cloudflare/vite-plugin:

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

@cloudflare/vitest-pool-workers:

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

@cloudflare/workers-editor-shared:

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

@cloudflare/workers-shared:

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

@cloudflare/workflows-shared:

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

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

[email protected] includes the following runtime dependencies:

Package	Constraint	Resolved
`miniflare`	workspace:*	4.20250214.0-rc.0
`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.

fixtures/type-generation/tests/type-generation.file-comment.test.ts

emily-shen · 2025-02-18T13:45:30Z

.changeset/nasty-kiwis-talk.md

@@ -0,0 +1,9 @@
+---
+"wrangler": minor


major? pretty sure there's nothing breaking. inclusion in v4 is mostly for politeness as there's a fair amount of CI usage

.changeset/nasty-kiwis-talk.md

fixtures/type-generation/tests/type-generation.file-comment.test.ts

packages/wrangler/e2e/types.test.ts

packages/wrangler/src/type-generation/helpers.ts

vicb · 2025-02-20T14:41:52Z

packages/wrangler/src/type-generation/helpers.ts

+	try {
+		const { envHeader } = await generateEnvTypes(
+			config,
+			{ strictVars: previousStrictVars === "false" ? false : true },


Suggested change

{ strictVars: previousStrictVars === "false" ? false : true },

{ strictVars: previousStrictVars !== "false" },

I prefer the current one as its easier to understand (at least for me)

packages/wrangler/src/type-generation/runtime/log-runtime-types-message.ts

vicb · 2025-02-21T09:58:45Z

There's one thing I was thinking about: should we also update the C3 templates?

Currently the worker-configuration.d.ts are static files that only contain interface Env while the cf-typegen scripts will generate both.

Ideally the types should not be in a static file but generated, I have a pending PR that does that for Next.

I think whatever worker-configuration.d.ts contains should match the output of the command. And the best way to do that would be to generate this file (whatever config we decide to use).

If we decide to use the runtime types, tsconfig.json should also be update and we should not install the old types.

/cc @petebacondarwin

emily-shen · 2025-02-21T10:31:52Z

There's one thing I was thinking about: should we also update the C3 templates?

I'm actually working on a PR right now to do that :) It'll update C3 to run wrangler types instead of using @cloudflare/workers-types. The plan is to release this in v4, make sure v4 is stable, then bump wrangler in C3 and then add switch over types in C3.

penalosa · 2025-02-27T14:10:01Z

.changeset/nasty-kiwis-talk.md

+
+Include runtime types in the output of `wrangler types` by default
+
+`wrangler types` will now produce one file that contains both `Env` types and runtime types based on your compatibility date and flags. This is located at `worker-configuration.d.ts` by default.


Worth taking this opportunity to rename this file, maybe to cloudflare.d.ts? cc @irvinebroque if you have any thoughts here

.changeset/nasty-kiwis-talk.md

fixtures/type-generation/package.json

packages/wrangler/e2e/types.test.ts

packages/wrangler/src/type-generation/runtime/index.ts

penalosa · 2025-02-27T14:17:55Z

packages/wrangler/src/type-generation/runtime/index.ts

-	await ensureDirectoryExists(outFile);
-
-	const header = `// Runtime types generated with workerd@${version} ${compatibility_date} ${compatibility_flags.join(",")}`;
+	const header = `// Runtime types generated with workerd@${version} ${compatibility_date} ${compatibility_flags.sort().join(",")}`;


Since this is now a combined types file, the header should probably be Types generated with..., which would also bust all existing caches

#8166 (comment)
also why do we want to bust existing caches?

packages/wrangler/src/type-generation/index.ts

penalosa · 2025-02-27T14:31:13Z

Could we have a more unified single header? Something like:

// Generated by Wrangler by running `wrangler types` ([email protected], compatibility_date: 2023-05-04, compatibility_flags: [], env hash: e82ba4d7b995dd9ca6fb0332d81f889b)

penalosa · 2025-02-27T14:58:22Z

packages/wrangler/src/type-generation/runtime/log-runtime-types-message.ts

 				{
 					"compilerOptions": {
-						...
 						"types": ${updatedTypesString}


I don't think this is actually required? It seems to include that file for me by default

huh yeah so it does. Is it because its covered by **/*.ts in include??

Looks like the default is **/*: https://www.typescriptlang.org/tsconfig/#include

emily-shen · 2025-02-27T17:28:50Z

Could we have a more unified single header? Something like:

// Generated by Wrangler by running `wrangler types` ([email protected], compatibility_date: 2023-05-04, compatibility_flags: [], env hash: e82ba4d7b995dd9ca6fb0332d81f889b)

hmm we could, but since we can use cached runtime types independently of env changes, its slightly more convenient to just have that bit on its own line, and i don't think it'll particularly matter to users. happy to change it if you feel strongly about it.

penalosa

Couple comments, but overall this is looking great!

penalosa · 2025-03-03T12:01:48Z

packages/wrangler/src/type-generation/index.ts

-			config,
-			envInterface,
-			outputPath
+		if ((header.length && content.length) || entrypointFormat === "modules") {


I realise this was probably here before, but I don't really understand this logic. Presumably at this stage there will always be something in header & content? What does the entrypointFormat check do?

this is for the extremely niche situation where its a service syntax worker and --include-runtime=false - we don't want to write an empty Env interface for that case.
I have no idea why that would be a problem, but we do have a test making sure we don't... any ideas? 😅

penalosa · 2025-03-03T12:06:34Z

packages/wrangler/src/type-generation/helpers.ts

+
+	if (envOutOfDate || runtimeOutOfDate) {
+		logger.log(
+			"❓ It looks like your types might be out of date. Have you updated your config file since last running `wrangler types`?"


Could we make this more assertive? What's the recommended user action here?

Right now it's not clear what the user should do as a result of their answer to the question posed

packages/wrangler/src/type-generation/runtime/index.ts

penalosa · 2025-03-03T12:09:23Z

packages/wrangler/src/type-generation/runtime/log-runtime-types-message.ts

 	const isWorkersTypesInstalled = tsconfigTypes.find((type) =>
 		type.startsWith("@cloudflare/workers-types")
 	);
 	const isNodeTypesInstalled = tsconfigTypes.find((type) => type === "node");


I'm not sure this logic is fully correct. If the types array is empty, but @types/node is in node_modules it'll automatically be picked up as well.

(I realise this is existing logic, but we might as well fix it up)

600a895 fixed here, but i can't figure out how to test it because the tests always run in a context where @types/nodes exists 😢

* graduate wrangler type generation to GA * fixups * extra changeset

* ci: setup next branch with prereleases to next tag * chore: remove deprecated `getBindingsProxy` (#5005) * Require Node v18 in Wrangler v4 (#7338) * Remove node_compat in Wrangler & Miniflare v4 (#7336) * Remove v2 warning (#7228) * chore: update esbuild (#6884) * `--local` by default for `wrangler kv` & `wrangler r2` (#7392) * deprecate unused D1 commands/options (#7471) * chore: remove alpha support from `wrangler d1 migrations apply` * chore: remove `wrangler d1 backups` * chore: fixup tests * chore: fixup tests * chore: fixup tests * chore: remove --batch-size * Remove deprecated commands & config (#7352) * Remove wrangler version * Remove generate & strip down init * Add changesets * Remove deprecated --format & config * Add changeset * remove commands * Fix tests * Remove .only() * Remove legacy assets * clarify legacy assets -> sites naming * various test fixes after rebase * fixup! chore: update esbuild (#6884) esbuild 0.24.2 variable naming changes * fixup! Remove node_compat in Wrangler & Miniflare v4 (#7336) * feat(wrangler): Drop worker prefix when creating KV namespaces (#7759) * feat(wrangler): Drop worker prefix when creating KV namespaces --------- Co-authored-by: Samuel Macleod <[email protected]> * Include node version in name * Ignore kv-asset-handler tests on Node 22 * rename tests * Rename positional `json` args. Fixes #7688 * unescape * fix tests * Update .changeset/funny-pets-punch.md * Add system requirements to the README * fix formatting * fix formatting * Address feedback * lockfile * fix test * Fix changeset format * Use RC versioning * feat: graduate `--x-include-runtime` (#8166) * graduate wrangler type generation to GA * fixups * extra changeset * Fix legacy assets * Clarify that node support affects Wrangler & Miniflare & kv-asset-handler * Clarify comment re node 20 * Add more packages * Remove obsolete tests * Rename legacyAssets * more robust isLocal * fix test snapshot * Add --legacy-peer-deps so that installing Wrangler v4 doesn't case issues with frameworks that haven't updated their peer dependency for Wrangler v4 * Remove crypto polyfill * fix kv.local test after rebase * fix lockfile * bump rc version * revert rc versions --------- Co-authored-by: Dario Piotrowicz <[email protected]> Co-authored-by: Max Rozen <[email protected]> Co-authored-by: Pedro Leal <[email protected]> Co-authored-by: emily-shen <[email protected]>

emily-shen force-pushed the emily/dynamic-typegen-ga branch from 56b09dc to 3d88fea Compare February 17, 2025 18:05

github-advanced-security bot found potential problems Feb 17, 2025

View reviewed changes

fixtures/type-generation/tests/type-generation.file-comment.test.ts Fixed Show fixed Hide fixed

emily-shen force-pushed the emily/dynamic-typegen-ga branch from 3d88fea to 68d6130 Compare February 18, 2025 12:22

workers-devprod added the e2e Run wrangler + vite-plugin e2e tests on a PR label Feb 18, 2025

emily-shen force-pushed the emily/dynamic-typegen-ga branch 3 times, most recently from c86cbf3 to 88426fa Compare February 18, 2025 13:42

emily-shen marked this pull request as ready for review February 18, 2025 13:44

emily-shen requested a review from a team as a code owner February 18, 2025 13:44

emily-shen commented Feb 18, 2025

View reviewed changes

emily-shen force-pushed the emily/dynamic-typegen-ga branch 4 times, most recently from a7df791 to c931fe0 Compare February 19, 2025 10:31

emily-shen added the v4 label Feb 19, 2025

emily-shen force-pushed the emily/dynamic-typegen-ga branch from 9a873ab to 4872cb9 Compare February 20, 2025 14:23