Why does Vite create multiple TypeScript config files: tsconfig.json, tsconfig.app.json and tsconfig.node.json?

In Vite TypeScript projects you may have noticed three typescript configuration files, tsconfig.json, tsconfig.app.json, and tsconfig.node.json. Each file is used for a different purpose and understanding their use cases can help you manage TypeScript configurations for your project.

In this article, you will learn about the three TypeScript config files: tsconfig.json, tsconfig.app.json, and tsconfig.node.json.

Prerequisites:

• Angular CLI
• NodeJS and NPM

Understanding the Three TypeScript Config Files

To control how your code is processed by the TypeScript compiler (tsc) you need to use TypeScript configuration files. These files define the TypeScript compilers' behavior and are also used to include or exclude files from compilation. There can be multiple config files that target different environments of development. In Vite projects, you can three TypeScript configuration files for a new TypeScript project.

1. tsconfig.json: The Base Configuration

This is the main TypeScript configuration file used for setting up the base settings for the entire project. It controls the compilation of your TypeScript code into JavaScript and you can specifying various options such as module resolution, target JavaScript version, and include/exclude patterns. Common settings in this file are:

• compilerOptions: Used for compiler settings such as module resolution, target JavaScript version, and strictness options.
• include and exclude: Used to specify the files and directories that should be included or excluded from TypeScript.
• baseUrl and paths: Used to specify import paths.

2. tsconfig.app.json: Application-Specific Configurations

This file is specifically used for the application code which is used by Vite to handle settings that are unique to the application's source code as some settings are not relevant to server-side code or libraries.

The main config tsconfig.json provides the base configuration for both application code and node.js environment but tsconfig.app.json extends or overrides settings to benefit only the application code. For example, in the tsconfig.app.json the paths or settings that is specified will override the tsconfig.file.

3. tsconfig.node.json: Node-Specific Configurations

This file is used only for TypeScript used for Node.js environments such as server-side code, build scripts, or any part of the project that runs in a Node.js context. Vite also uses it for its development and build processes.

Vite uses tsconfig.node.json to set TypeScript's compiler options for Node.js execution. These are settings that differ from client-side code such as target versions for Node.js.

How Vite Utilizes Multiple Config Files?

Configuration Inheritance and Overrides

Vite handles TypeScript configurations by merging and overriding settings from multiple tsconfig files. This allows specific configurations to be applied where needed without affecting the global settings. For example, tsconfig.app.json inherits settings from tsconfig.json but overrides or extends them for application-specific requirements.

Benefits of Splitting Configurations Across Multiple Files

Splitting TypeScript configurations across multiple files have many benefits such as:

• Clarity: Each file has a specific purpose, making it easier to manage and understand.
• Flexibility: Allows to set different settings for various parts of the project (e.g., client-side vs. server-side).
• Isolation: Reduces the risk of confusion and affecting unrelated parts of the project.

Examples of Common Use Cases for Each Config File

The following is the explanation of each config file content generated by Vite:

1. tsconfig.json

This is the base configuration file. It generally includes references to other TypeScript configuration files, as well as global settings that apply to the entire project.

//tsconfig.json
{
    "files": [],
    "references": [
        {
            "path": "./tsconfig.app.json"
        },
        {
            "path": "./tsconfig.node.json"
        }
    ],
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@/*": [
                "./src/*"
            ]
        }
    }
}

In the above example,

• 'files' are used add files for compilation, an empty array means this file does not include specific files for compilation but references other configurations.
• 'references' are used to reference other tsconfig.json files, making it easier to manage projects with multiple TypeScript configurations and
• 'compilerOptions' are used to control many aspects of TypeScript compiler such as target version, enable strict type checking etc

2. tsconfig.app.json

This configuration file is used for application-specific settings. It's common in projects that use different configurations for the server and client parts.

//tsconfig.app.json
{
    "compilerOptions": {
        "composite": true,
        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
        "target": "ES2020",
        "useDefineForClassFields": true,
        "lib": [
            "ES2020",
            "DOM",
            "DOM.Iterable"
        ],
        "module": "ESNext",
        "skipLibCheck": true,
        /* Bundler mode */
        "moduleResolution": "bundler",
        "allowImportingTsExtensions": true,
        "resolveJsonModule": true,
        "isolatedModules": true,
        "moduleDetection": "force",
        "noEmit": true,
        "jsx": "react-jsx",
        /* Linting */
        "strict": true,
        "noUnusedLocals": true,
        "noUnusedParameters": true,
        "noFallthroughCasesInSwitch": true,
        "baseUrl": ".",
        "paths": {
            "@/*": [
                "./src/*"
            ]
        }
    },
    "include": [
        "src"
    ]
}

In the above example,

• 'compilerOptions' are used to control many aspects of TypeScript compiler.
• 'Composite' is used to enables project references which needed by TypeScript to quickly determine where to find the outputs.
• 'Target' is used to specify the JavaScript language version to compile.
• 'lib' is used to specify the library files to include during compilation.
• 'Module' is used to set the module code generation method. 'Strict' is used as a flag, if true it enables strict type checking options

3. tsconfig.node.json

This configuration is used specifically for Node.js related code or server-side logic. It has settings specific to Node.js environments.

{
    "compilerOptions": {
        "composite": true,
        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
        "skipLibCheck": true,
        "module": "ESNext",
        "moduleResolution": "bundler",
        "allowSyntheticDefaultImports": true,
        "strict": true,
        "noEmit": true
    },
    "include": [
        "vite.config.ts"
    ]
}

In the above example,

• 'compilerOptions' are used to control many aspects of TypeScript compiler.
• 'Composite' is used to enables project references which needed by TypeScript to quickly determine where to find the outputs.
• 'tsBuildInfoFile'is used to specifies the path for the build information which help to speed up building of larger TypeScript code.
• 'skipLibCheck' is used as a flag, if true it skips type checking of default library declaration files
• 'Module' is used to set the module code generation method. 'Strict' is used as a flag, if true it enables strict type checking options.
• 'include' is used to specify the files or directories that are to be included for compilation.

Best Practices for Managing TypeScript Config Files in Vite

• Carefully use Base Configurations: Use tsconfig.json for settings that apply for the application code and node.js environments.
• Customize Application TypeScript: Customize tsconfig.app.json for application needs without affecting the base configuration.
• Isolate Node specific Settings: Use tsconfig.node.json for server-side or build script configurations to maintain clarity and separation of concerns.
• Review regularly: Check and update TypeScript configurations time to time to reflect the project changes and TypeScript updates.

Conclusion

TypeScript configuration is important the development and build process in Vite projects. Understanding the roles of tsconfig.json, tsconfig.app.json, and tsconfig.node.json helps in managing complex projects more efficiently. By adopting the best practices for each configuration file you can have a smooth and organized development experience.

R

rohan_paul

Follow

Improve