@cexbrayat Thanks for the offer! I'll do you one better: here's the documentation I wish I had, based on what I've been able to figure out. Hopefully someone (you?) can fact check & help with areas I'm unclear, and then we'll have the docs and can close out the issue :)

References I used:

Consider flipping order of tsconfig.app.json and tsconfig.vitest.json in tsconfig.json and enabling "vue.server.reverseConfigFilePriority": true #264
Isn't the create-vue types setup broken? core#11113

create-vue tsconfig setup

create-vue sets up TypeScript using multiple tsconfig files. Here’s an overview of how these configurations work together:

Type checking

Type checking is done using vue-tsc --build --force (see the “type-check” command in package.json). This approach leverages two important options:

--build Option: This option enables TypeScript’s project references and incremental builds. By rechecking only the files that have changed since the last build, it speeds up repeat checks and improves overall efficiency.
--force Option: The --force flag ensures that all files are type-checked, not just the ones that have changed. This is important because it provides a comprehensive check, ensuring that any potential issues, even those in unchanged files or due to changes in dependencies or configurations, are caught.

Since the build option is used, TS build info files are emitted. Each tsconfig sets their own output directory, within node_modules/.tmp, so it's always gitignored.

tsconfig files

Primary Configuration (`tsconfig.json`)

The main entry point for type checking is tsconfig.json. It includes references to two specific configurations:

tsconfig.app.json: For code executed in the browser (i.e., most of your application).
tsconfig.build.json: For code executed to build the project (e.g., configuration scripts).

Additional tsconfig.*.json files added

If you use Cypress for end-to-end tests, an additional configuration file is added, cypress/e2e/tsconfig.cypress.json.
If you add vitest, tsconfig.vitest.json is added to the project root, extending from the app config. See "Approach" below for details.

Approach

This tsconfig approach establishes TypeScript “sub-projects” using tsconfig references. This modular approach allows different parts of the project to have distinct TypeScript configurations.

Vitest

When using vitest, a tsconfig.vitest.json is generated, extending from tsconfig.app.json. The app configuration excludes test files (src/**/__tests__/*), while the test configuration overwrites that exclusion with "exclude": []. The result is that both tsconfig's match all app files, while the vitest config additionally matches test files. This requires careful consideration when modifying projects that use create-vue's tsconfig for vitest: see "Vitest Considerations" below.

This overlap in coverage ... TODO: why?. A more precise approach would be to have tsconfig.vitest.json match only test files, but TODO: why?

Only one tsconfig is actually used for files: vue-tsc and Volar. Both tools check the order of the main entry point tsconfig.json’s references, picking the first reference that matches a given file. This means that, while the sub-tsconfig files are isolated, the order in which the app and vitest tsconfigs are listed in the main file is important. TODO: is this true?.

Note that the default output from create-vue expects that Volar's reverseConfigFilePriority is disabled.

Isolation Between References

Typically with tsconfig usage, keys are overwritten within the extend chain. With references, however, they are isolated between different tsconfig references sections. Note that, as described above, tsconfig.vitest.json extends from tsconfig.app.json, so these two are not isolated.

Modifying the Configurations

These tsconfig files extend from other configurations, creating a chain. When adding new libraries or types, check the extended configuration files. Be aware that setting the same key in a configuration file will overwrite the previous value from the extended file.

For example, tsconfig.app.json extends from a tsconfig from Vue that includes DOM libs. If you need to add a new lib to tsconfig.app.json, you have to copy in the entire lib section from the base config, otherwise you will overwrite the lib value and lose all DOM types.

Vitest Considerations

When Vitest is used, modifying either tsconfig.app.json and/or tsconfig.vitest.json, there are interactions between the two to consider. The ones in vitest will overwrite the other.

For example, by default tsconfig.app.json has no "types" set, while tsconfig.vitest.json does. Since the vitest types will overwrite any set in tsconfig.app.json, if you need a type in both the app files and the vitest files, you'll have to duplicate those "types" entries in both files.

Type Checking with Volar and vue-tsc

When you run Volar or vue-tsc, each file is type-checked using the tsconfig file that matches its path (i.e., it is included in an include glob and not excluded by an exclude glob).
The tsconfig.vitest.json also includes the normal sources.
The selection order of which tsconfig is used for a file included in multiple referenced configurations varies between tsserver and Vue files handled by Volar. This can be observed in the VS Code status bar tooltip, which indicates the current file’s tsconfig.

Best Practices

When making changes, regularly verify which tsconfig file is being used for your files in the development environment: Use the VS Code status bar to check the active tsconfig and troubleshoot any configuration issues.

Document tsconfig.*.json #265

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Document `tsconfig.*.json` #265