"Referenced projects must have the new composite setting enabled" does not hold true

[haoqunjiang]

🔎 Search Terms

composite, project references, solution-style tsconfig

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about tsconfig.

⏯ Playground Link

https://vite.new/react-ts

💻 Code

The above link is a project created from the vite react-ts template (https://vite.new/react-ts).
It uses project references in tsconfig.json, but no composite: true specified in both tsconfig.app.json and tsconfig.node.json.

On the other hand, the TypeScript handbook says:

Referenced projects must have the new composite setting enabled.

🙁 Actual behavior

The project builds (npm run build) successfully without composite: true.

🙂 Expected behavior

If I understand correctly, the documentation means I have to specify composite: true when using references. I'd expect an error or warning if I didn't follow the guide.

Additional information about the issue

I'm curious whether it's a bug or a feature.
If it's a bug, what's the expected behavior?
If it's a feature, I'd like to see the documentation updated accordingly.

[codethief]

When the docs say

Referenced projects must have the new composite setting enabled.

what they mean is that if project A references project B, the latter must have composite: true. In your example, however, your two projects (tsconfig.app.json and tsconfig.node.json) don't reference each other.¹ They are merely referenced by the main ("solution-style") tsconfig.json, in which case you don't need the composite: true. I agree that the docs could be a bit more explicit about this.

¹) In your case (tsconfig.app.json and tsconfig.node.json) this is likely not needed since Node/config code will likely never import application code or vice versa. However, references will be needed as soon as one project needs to import code from another project (that is type-checked with a different tsconfig). For an example please see the tsconfigs in https://github.com/microsoft/TypeScript/tree/main/src and its subfolders.

[haoqunjiang]

I see. So solution-style references don't require composite; only cross-references need composite?

[codethief]

Yes, at least that's been my understanding.

[haoqunjiang]

I found that the TypeScript 5.7 RC release blog has confirmed this behavior:

every project that can be referenced by another (non-workspace) project must enable a flag called composite

https://devblogs.microsoft.com/typescript/announcing-typescript-5-7-rc/#faster-project-ownership-checks-in-editors-for-composite-projects:~:text=every%20project%20that%20can%20be%20referenced%20by%20another%20(non%2Dworkspace)%20project%20must%20enable%20a%20flag%20called%20composite%2C

[segevfiner]

This really needs to be clarified in the docs. The fact that you can use project references without composite, and without requiring composite and "noEmit": false to reference multiple tsconfig files that don't reference each other is quite useful for many cases, such as specifying project config files in their own separate tsconfig for ESLint type checking rules.

create-vue already creates projects using this.