Correctly integrating worker-configuration.d.ts into the TS configuration

[kotkoroid]

Which Cloudflare product(s) does this pertain to?

Workers for Platforms

What versions & operating system are you using?

Wrangler 4.13.2, TypeScript 5.8.3, Node 22.14.0, macOS 15.3.2

Please provide a link to a minimal reproduction

No response

Describe the Bug

Hi,

I'm reaching out to clarify some aspects of integrating TypeScript into my project. Although I've been following the documentation, I found certain points to be unclear.

This page provides the following steps for proper integration:

1. Update wrangler to version 4
2. Generate types via wrangler types
3. Add worker-configuration.d.ts into compilerOptions.types

I've successfully incorporated these steps into my codebase. However, I have a few questions to ensure I understand correctly:

• Is the @cloudflare/workers-types package no longer required due to the --include-runtime flag being enabled by default in wrangler 4?
• If so, can it be removed from tsconfig.json as well? The documentation mentions removing @cloudflare/workers-types imports in Worker code, but it's unclear if this applies to configurations as well.

Assuming the answer to both questions is yes, I noticed that in the TypeScript template, worker-configuration.d.ts is included in the include rather than compilerOptions.types. I'm guessing this might be because the template is still using wrangler 3, which would also explain @cloudflare/workers-types being still present in compilerOptions.types.

Could you provide clarification on this? The answer I am most looking for is whether I should include worker-configuration.d.ts in compilerOptions.types or include when using wrangler 4.

Please provide any relevant error logs

No response

[emily-shen]

1. Yes, @cloudflare/workers-types is no longer needed if you generate runtime types instead using wrangler@4 types, and you should remove any references to it since you should have uninstalled it. I'll clarify the docs :)
2. You should include worker-configuration.d.ts in compilerOptions.types, although it doesn't seem like there is a functinoal difference if you put it in include? let me know if you're not finding that to be the case though!
3. Sorry about the templates being out of date! there is a PR in progress to update the templates here use generated types in c3 use generated types in c3 #8886.

[kotkoroid]

@emily-shen

Thank you for confirming and addressing all the points! I've taken a closer look at the issue I'm encountering, and it seems to be related to the monorepository setup.

I have a tsconfig.json file in the root that each worker extends in its respective directory. However, when I run type checking with bun --filter '*' typecheck, I encounter the following error:

@minerva/gateway typecheck $ tsc
│ ../services/auth/src/index.ts(12,47): error TS2304: Cannot find name 'AuthEnv'.
│ ../services/auth/src/index.ts(15,42): error TS2304: Cannot find name 'AuthEnv'.
└─ Exited with code 2

This issue arises because, although tsc is executed in the gateway directory, it attempts to type check the entire repository. Since the worker-configuration.d.ts for the auth service is not included in the gateway's tsconfig.json, it results in a failure.

As a temporary solution, I've added the auth worker-configuration.d.ts to the include key of root tsconfig.json, which makes it accessible throughout the project.

The core issue seems to be less about whether worker-configuration.d.ts should be in compilerOptions.types or include, and more about how to configure tsc to compile only within the directory and its subdirectories from which it is executed.

Could you guide me about what steps I should take in order to prevent tsc from checking the entire repository during each run? You can review the TypeScript configuration in this repository: minerva

[petebacondarwin]

I think you should have a look into TS project references: https://www.typescriptlang.org/docs/handbook/project-references.html#overall-structure:~:text=Another%20good%20practice%20is%20to%20have%20a%20%E2%80%9Csolution%E2%80%9D%20tsconfig.json%20file%20that%20simply%20has%20references%20to%20all%20of%20your%20leaf%2Dnode%20projects%20and%20sets%20files%20to%20an%20empty%20array%20(otherwise%20the%20solution%20file%20will%20cause%20double%20compilation%20of%20files).

[petebacondarwin]

This is working as expected and I don't believe there is any issue with Wrangler here, so I am going to close this issue. Thanks.