From 9fe53ed5057f06481f9868f4d5b28e40ba9d0382 Mon Sep 17 00:00:00 2001 From: Hiroki Osame Date: Thu, 10 Oct 2024 12:58:06 +0900 Subject: [PATCH 1/5] docs: global type recommendation --- docs/config/index.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/config/index.md b/docs/config/index.md index e9df0fc6090c..b988ecf404cf 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -353,7 +353,7 @@ Vitest uses Vite SSR primitives to run tests which has [certain pitfalls](https: - **Default:** `false` - **CLI:** `--globals`, `--globals=false` -By default, `vitest` does not provide global APIs for explicitness. If you prefer to use the APIs globally like Jest, you can pass the `--globals` option to CLI or add `globals: true` in the config. +By default, `vitest` does not provide global APIs for testing to encourage explicitness and reduce potential conflicts. If you prefer using global APIs like Jest, you can enable them by passing the `--globals` option in the CLI or setting `globals: true` in your config file. ```ts // vitest.config.ts @@ -366,9 +366,26 @@ export default defineConfig({ }) ``` -To get TypeScript working with the global APIs, add `vitest/globals` to the `types` field in your `tsconfig.json` +#### TypeScript integration -```json +To ensure TypeScript recognizes the global APIs, you have two options: + +1. Import the global types + +Add `import 'vitest/globals'` to any `.ts` file (e.g., your [setup file](#setupfiles) or a `.d.ts` file). This registers the global APIs types automatically. Ensure the file is included in your `tsconfig.json` so TypeScript knows it's apart of the same context. + +```ts +// test-setup.ts or vitest.d.ts +import 'vitest/globals' +``` + +2. Configure it in [`tsconfig.json#compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) + +Alternatively, add `vitest/globals` to the `types` field in `tsconfig.json`. + +Warning: this will disable TypeScript's automatic type discovery, meaning you'll need to manually include other types as needed. + +```ts // tsconfig.json { "compilerOptions": { @@ -377,7 +394,9 @@ To get TypeScript working with the global APIs, add `vitest/globals` to the `typ } ``` -If you are already using [`unplugin-auto-import`](https://github.com/antfu/unplugin-auto-import) in your project, you can also use it directly for auto importing those APIs. +#### Auto-import + +If you are already using [`unplugin-auto-import`](https://github.com/antfu/unplugin-auto-import) in your project, you can simplify this process by automatically importing the Vitest APIs without having to manually manage global type imports. This also generates TypeScript declarations for you. ```ts // vitest.config.ts From a923e96744ddbc05d08e60bd585c7f1ddf0cd682 Mon Sep 17 00:00:00 2001 From: Hiroki Osame Date: Thu, 10 Oct 2024 13:07:11 +0900 Subject: [PATCH 2/5] Update index.md --- docs/config/index.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/config/index.md b/docs/config/index.md index b988ecf404cf..96e732723efa 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -372,27 +372,27 @@ To ensure TypeScript recognizes the global APIs, you have two options: 1. Import the global types -Add `import 'vitest/globals'` to any `.ts` file (e.g., your [setup file](#setupfiles) or a `.d.ts` file). This registers the global APIs types automatically. Ensure the file is included in your `tsconfig.json` so TypeScript knows it's apart of the same context. - -```ts -// test-setup.ts or vitest.d.ts -import 'vitest/globals' -``` + Import `vitest/globals` from any `.ts` file (e.g., your [setup file](#setupfiles) or a `.d.ts` file). This registers the global APIs types automatically. Ensure the file is included in your `tsconfig.json` so TypeScript knows it's apart of the same project. + + ```ts + // test-setup.ts or vitest.d.ts + import 'vitest/globals' + ``` 2. Configure it in [`tsconfig.json#compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) -Alternatively, add `vitest/globals` to the `types` field in `tsconfig.json`. - -Warning: this will disable TypeScript's automatic type discovery, meaning you'll need to manually include other types as needed. - -```ts -// tsconfig.json -{ - "compilerOptions": { - "types": ["vitest/globals"] - } -} -``` + Alternatively, add `vitest/globals` to the `types` field in `tsconfig.json`. + + Warning: This disables TypeScript's automatic type detection, which could break your setup if your project relies on it. If you encounter types missing from other packages, you'll now need to manually register them here. + + ```ts + // tsconfig.json + { + "compilerOptions": { + "types": ["vitest/globals"] + } + } + ``` #### Auto-import From 7fa7084e2051ef64a9ff8ecc559733677fb0ebb3 Mon Sep 17 00:00:00 2001 From: Hiroki Osame Date: Thu, 10 Oct 2024 13:21:09 +0900 Subject: [PATCH 3/5] wip --- docs/config/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/config/index.md b/docs/config/index.md index 96e732723efa..239b68b7cb36 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -373,7 +373,7 @@ To ensure TypeScript recognizes the global APIs, you have two options: 1. Import the global types Import `vitest/globals` from any `.ts` file (e.g., your [setup file](#setupfiles) or a `.d.ts` file). This registers the global APIs types automatically. Ensure the file is included in your `tsconfig.json` so TypeScript knows it's apart of the same project. - + ```ts // test-setup.ts or vitest.d.ts import 'vitest/globals' @@ -382,10 +382,10 @@ To ensure TypeScript recognizes the global APIs, you have two options: 2. Configure it in [`tsconfig.json#compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) Alternatively, add `vitest/globals` to the `types` field in `tsconfig.json`. - + Warning: This disables TypeScript's automatic type detection, which could break your setup if your project relies on it. If you encounter types missing from other packages, you'll now need to manually register them here. - - ```ts + + ```json5 // tsconfig.json { "compilerOptions": { From 07958117f7f076c245755254ecd4922835fb9b70 Mon Sep 17 00:00:00 2001 From: Hiroki Osame Date: Thu, 10 Oct 2024 13:22:33 +0900 Subject: [PATCH 4/5] wip --- docs/config/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config/index.md b/docs/config/index.md index 239b68b7cb36..9e2d220a9e81 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -383,7 +383,7 @@ To ensure TypeScript recognizes the global APIs, you have two options: Alternatively, add `vitest/globals` to the `types` field in `tsconfig.json`. - Warning: This disables TypeScript's automatic type detection, which could break your setup if your project relies on it. If you encounter types missing from other packages, you'll now need to manually register them here. + Warning: This disables TypeScript's automatic type detection, which could break your setup if your project relies on it. If you encounter types missing from other packages, you'll now need to manually register them here as well. ```json5 // tsconfig.json From 67dce54720f729e54452400aec75bbca68c95fe3 Mon Sep 17 00:00:00 2001 From: Hiroki Osame Date: Thu, 10 Oct 2024 13:41:43 +0900 Subject: [PATCH 5/5] wip --- docs/config/index.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/config/index.md b/docs/config/index.md index 9e2d220a9e81..5fe592fa7cd6 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -353,7 +353,7 @@ Vitest uses Vite SSR primitives to run tests which has [certain pitfalls](https: - **Default:** `false` - **CLI:** `--globals`, `--globals=false` -By default, `vitest` does not provide global APIs for testing to encourage explicitness and reduce potential conflicts. If you prefer using global APIs like Jest, you can enable them by passing the `--globals` option in the CLI or setting `globals: true` in your config file. +By default, Vitest does not provide global APIs for testing to encourage explicitness and reduce potential conflicts. If you prefer using global APIs like Jest, you can enable them by passing the `--globals` option in the CLI or setting `globals: true` in your config file. ```ts // vitest.config.ts @@ -368,18 +368,26 @@ export default defineConfig({ #### TypeScript integration -To ensure TypeScript recognizes the global APIs, you have two options: +To register global API types, follow one of the following methods: -1. Import the global types +1. Use a `@types/vitest.d.ts` file - Import `vitest/globals` from any `.ts` file (e.g., your [setup file](#setupfiles) or a `.d.ts` file). This registers the global APIs types automatically. Ensure the file is included in your `tsconfig.json` so TypeScript knows it's apart of the same project. + Create a `@types/vitest.d.ts` file in your project root that imports `vitest/globals`: ```ts - // test-setup.ts or vitest.d.ts import 'vitest/globals' ``` -2. Configure it in [`tsconfig.json#compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) +2. Type-import the global types from a source file + + Add a type-import from `vitest/globals` in any `.ts` file (e.g., your [setup file](#setupfiles)). This registers the global APIs types automatically. Ensure the file is included in your `tsconfig.json` so TypeScript knows it's apart of the same project. + + ```ts + // test-setup.ts + import type {} from 'vitest/globals' + ``` + +3. Configure it in [`tsconfig.json#compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) Alternatively, add `vitest/globals` to the `types` field in `tsconfig.json`.