From 06dff21ce2ccfacd61481d6da256654e131bb195 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ari=20Perkki=C3=B6?= <ari.perkkio@gmail.com>
Date: Fri, 27 Mar 2026 15:57:10 +0200
Subject: [PATCH] docs(reporters): `.vitest` results directory convention

---
 docs/guide/advanced/reporters.md | 23 +++++++++++++++++++++++
 docs/guide/index.md              |  7 +++++++
 2 files changed, 30 insertions(+)

diff --git a/docs/guide/advanced/reporters.md b/docs/guide/advanced/reporters.md
index 925e4559d110..80a8bbe8447d 100644
--- a/docs/guide/advanced/reporters.md
+++ b/docs/guide/advanced/reporters.md
@@ -72,6 +72,29 @@ class MyReporter implements Reporter {
 }
 ```
 
+## Storing artifacts on file system
+
+If your custom reporter needs to store any artifacts on file system it should place them inside `.vitest` directory. This directory is a convention that Vitest reporters and third party integrations can use to co-locate their results in a single directory. This way users of your custom reporter do not need to add multiple exclusion in their `.gitignore`. Only the `.vitest` is needed.
+
+Reporters and other integrations should respect following rules around `.vitest` directory:
+
+- `.vitest` directory is placed in [the `root` of the project](/config/root)
+- Reporter can create `.vitest` directory if it does not already exist
+- Reporter should never remove `.vitest` directory
+- Reporter should create their own directory inside `.vitest`, for example `.vitest/yaml-reporter/`
+- Reporter can remove their own specific directory inside `.vitest`, for example `.vitest/yaml-reporter/`
+
+```ansi
+.vitest
+│
+├── yaml-reporter
+│   ├── results.yaml
+│   └── summary.yaml
+│
+└── junit-reporter
+    └── report.xml
+```
+
 ## Exported Reporters
 
 `vitest` comes with a few [built-in reporters](/guide/reporters) that you can use out of the box.
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 6d81e9b01fbb..f9b7b3c95c4a 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -43,6 +43,13 @@ It is recommended that you install a copy of `vitest` in your `package.json`, us
 
 The `npx` tool will execute the specified command. By default, `npx` will first check if the command exists in the local project's binaries. If it is not found there, `npx` will look in the system's `$PATH` and execute it if found. If the command is not found in either location, `npx` will install it in a temporary location prior to execution.
 
+Vitest and third party integrations can use `.vitest` directory to store generated artifacts. It's recommended to add this in your `.gitignore`.
+
+``` sh [.gitignore]
+# Vitest reports and artifacts
+.vitest/
+```
+
 ## Writing Tests
 
 As an example, we will write a simple test that verifies the output of a function that adds two numbers.