Lumirelle's TypeScript Config

Caution

Since 0.1.0, this package only supports TypeScript 6.0 and above, if you are using older versions of TypeScript, please use 0.0.x versions.

Lumirelle's opinionated TypeScript config.

Motivation

The tsconfig.json is the configuration file for TypeScript compilers (tsc, tsgo, tsdown, bunup, ... All of the compilers / build tools who respect the tsconfig.json file). It's used to tell the compiler what files should be included, and how they should be processed.

In modern TypeScript projects, we often use tsconfig.json files to:

1. IDE LSP (Language Server Protocol) support, powered by IDE plugin with tsserver (TypeScript language server);
2. Build tool configuration, for example, this project uses tsdown as the build tool, who respects the tsconfig.json file, and will change its behavior based on the config;
3. Type aware linting, for example, some ESLint or OxLint rules require type information, how the generator of type information is configured is also based on the tsconfig.json file;
4. Type aware checking, for example, for library projects, we may use tsc --noEmit to check the type correctness; for Vue application projects, we may use vue-tsc --noEmit to do this.

In order to get better DX (development experience) and UX (user experience), we need a good tsconfig.json setup, so that we can build libaries / applications with correct types and better quality.

Configuration

@lumirelle/tsconfig/ts

For TypeScript projects.

@lumirelle/tsconfig/vue

For Vue projects.

Specially, this config assumes you are using Vite to build Vue applications, so it limits the language level to ES2022, to align with the default build target of Vite.

Usage

1. Install this package (also install the referenced types you may need):

   # nub, https://nubjs.com/
   nub add -D @lumirelle/tsconfig
   # pnpm
   pnpm add -D @lumirelle/tsconfig
   # npm
   npm install -D @lumirelle/tsconfig
   # ...
   
   # Referenced types
   # For example, if you are building a Node.js package:
   nub add -D @types/node
   # ...Or else

2. Extend this config in your tsconfig.json:

   [!Note] We highly recommend you to use TypeScript project references to split the TypeScript setup of source files and other project files.

   For library projects:

   tsconfig.json

   {
     "references": [
       { "path": "./tsconfig.lib.json" },
       { "path": "./tsconfig.node.json" }
     ],
     "files": []
   }

   tsconfig.lib.json

   {
     "extends": "@lumirelle/tsconfig/lib",
     "compilerOptions": {
       // To ensure your library's Node.js compatibility, we use Node.js API types in source and test files.
       "types": ["node"],
       // Enable isolated declarations to speed up type checking & generation
       "declaration": true,
       "isolatedDeclarations": true
     },
     // Only include your project's source files who are expected to run with `isolatedDeclarations` and use Node.js API types, also test files who are related to source files.
     "include": ["src/**/*", "test/**/*"],
     "exclude": ["test/fixtures/**/*"]
   }

   tsconfig.node.json

   {
     "extends": "@lumirelle/tsconfig/ts",
     "compilerOptions": {
       "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
       // To get the benefits of your runtime, we use runtime-specific API types here.
       "types": ["node"],
       // Allow importing JavaScript files
       "allowJs": true
     },
     // Your project files others than source & test files who are need type support
     "include": ["scripts/**/*", "*.ts", "*.js"]
   }

   For Vue application projects:

   tsconfig.json

   {
     "references": [
       { "path": "./tsconfig.app.json" },
       { "path": "./tsconfig.node.json" }
     ],
     "files": []
   }

   tsconfig.app.json

   {
     "extends": "@lumirelle/tsconfig/vue",
     "compilerOptions": {
       "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
       // Please adjust the path aliases to match your bundler's configuration.
       "paths": {
         "~": ["./src"],
         "~/*": ["./src/*"]
       },
       // Include types you need.
       // For example, "vite/client" provides extra types to source files for Vite's `import.meta.env` and `import.meta.hot` API, and more.
       // Some Vite plugins may also provide extra types to source files, like `vite-svg-loader`, please also include them.
       // If you are not using Vite, you can change below types as you need.
       "types": ["vite/client"]
     },
     // Only include your project's source files who are expected to run in the browser, also extra types to source files generated by tools (matched by `*.d.ts`), also test files who are related to source files.
     "include": ["src/**/*", "test/**/*", "*.d.ts"],
     "exclude": ["test/fixtures/**/*"]
   }

   tsconfig.node.json

   {
     "extends": "@lumirelle/tsconfig/ts",
     "compilerOptions": {
       "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
       // To get the benefits of your runtime, we use runtime-specific API types here.
       "types": ["node"],
       // Allow importing JavaScript files
       "allowJs": true
     },
     // Your project files others than source & test files who are need type support
     "include": ["scripts/**/*", "*.ts", "*.js"]
   }

Examples

You can find example projects using this config in the examples directory.

Or see the real-world usage:

• TypeScript library project: lumirelle/starter-ts
• TypeScript monorepo library project: lumirelle/starship-butler & lumirelle/starter-monorepo
• Vue application project: lumirelle/lumirelle.me

Sponsors

License

MIT License © Lumirelle