Tooling: TypeScript Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• tsconfig.json
• tsconfig.app.json
• tsconfig.node.json
• package.json
• vite.config.ts
• eslint.config.js
• components.json

The Character-Sheet-Maker project leverages TypeScript to ensure type safety and improve developer experience. The configuration is modular, split across multiple files to handle different environments within the project: the main React application and the Node.js-based tooling. This separation is managed through TypeScript's project references feature, which allows for distinct compilation settings for different parts of the codebase.

The root tsconfig.json acts as a "solution-style" configuration, orchestrating the build process by referencing the more specific configuration files. This setup is integrated with the Vite build tool and ESLint for code quality, ensuring that path aliases and type-checking rules are consistent across the development environment. The project uses TypeScript version ~5.9.3.

Sources: package.json:42, tsconfig.json

Configuration Architecture

The TypeScript configuration is structured around a root file and two environment-specific files, linked via project references. This allows for tailored settings for the browser-facing application code and the Node.js environment used for build tooling.

This diagram illustrates the project reference structure, where the root tsconfig.json delegates to specialized configurations for the application and Node.js tooling.

Sources: tsconfig.json:2-8, tsconfig.app.json:30, tsconfig.node.json:22

tsconfig.json (Root)

This is the main entry point for the TypeScript compiler when using project references. It does not compile any files directly ("files": []). Its primary responsibilities are:

1. Defining Project References: It uses the references array to point to the configurations for the application (tsconfig.app.json) and Node.js environment (tsconfig.node.json). This enables the tsc -b command to build both parts of the project according to their respective rules.
2. Global Path Aliases: It establishes the baseUrl and paths for the entire project, allowing for consistent module path aliases like @/*.

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

Sources: tsconfig.json

tsconfig.app.json (Application)

This file contains the compiler options for the main React application code located in the src directory.

Sources: tsconfig.app.json:30

Key settings include:

Option	Value	Description
target	ES2022	Compiles TypeScript down to ECMAScript 2022.
lib	["ES2022", "DOM", "DOM.Iterable"]	Includes type definitions for ES2022, the DOM, and DOM iterables.
moduleResolution	bundler	Uses the modern module resolution strategy expected by bundlers like Vite.
jsx	react-jsx	Enables the modern JSX transform for React 17+ without needing to import React.
noEmit	true	Prevents the TypeScript compiler from generating JavaScript files. Vite handles the transpilation.
strict	true	Enables all strict type-checking options.
paths	{"@/*": ["./src/*"]}	Defines the @/ alias to point to the src directory.

Sources: tsconfig.app.json:2-29

tsconfig.node.json (Node.js Tooling)

This configuration is specifically for files that run in a Node.js environment, such as vite.config.ts.

Sources: tsconfig.node.json:22

Key settings include:

Option	Value	Description
target	ES2023	Compiles to a more modern ECMAScript version suitable for recent Node.js releases.
lib	["ES2023"]	Includes type definitions for ES2023 features.
types	["node"]	Explicitly includes Node.js-specific type definitions (e.g., __dirname, path).
module	ESNext	Uses the latest supported ECMAScript module syntax.
noEmit	true	Prevents output generation, as type-checking is the primary goal.

Sources: tsconfig.node.json:2-21

Build Process Integration

The TypeScript configuration is central to the project's build and development scripts defined in package.json.

Script	Command	Description
build	tsc -b && vite build	First, it runs TypeScript's build mode (-b) to type-check the entire project using references. Then, it uses Vite to bundle the application for production.
lint	eslint .	Runs ESLint across the project, which uses typescript-eslint to parse and lint TypeScript files.

Sources: package.json:7-9

The tsc -b command is crucial as it respects the project reference structure, ensuring both the app and node configurations are checked before the final Vite build proceeds.

Path Alias (@/*) Resolution

The project uses the @/* alias for cleaner, absolute-like imports from the src directory. This requires configuration in multiple places to work correctly across the toolchain.

This diagram shows how the path alias defined in tsconfig.json is consumed by various tools, each requiring its own configuration to understand the alias.

Sources: tsconfig.json:10-15, vite.config.ts:8-12, components.json:11-16

• TypeScript: The baseUrl and paths are defined in tsconfig.json for the compiler.
  Sources: tsconfig.json:11-14
• Vite: The vite.config.ts file must have a corresponding resolve.alias entry to map the alias during bundling.

  // vite.config.ts
  export default defineConfig({
    // ...
    resolve: {
      alias: {
        "@": path.resolve(__dirname, "./src"),
      },
    },
  });
  

  Sources: vite.config.ts:8-12
• Shadcn UI: The components.json file also defines the alias for use by the shadcn-ui command-line tool when adding new components.
  Sources: components.json:11-16
• ESLint: While not explicitly configured with the alias in eslint.config.js, the typescript-eslint parser implicitly uses the tsconfig.json to resolve modules, allowing it to understand the aliased paths during linting.
  Sources: eslint.config.js:12