nuxt-vitest-shared-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Semenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,389 @@
+# nuxt-vitest-shared-app
+
+Run Nuxt component tests in Vitest on one Nuxt app per Vitest worker, shared by all test files of that worker.
+
+The library provides:
+
+- the shared-app lifecycle on top of `@nuxt/test-utils` (`environment: "nuxt"`, `mountSuspended`, `mockNuxtImport`);
+- deterministic cleanup of documented Nuxt and test-owned state after each test, with explicit project resets for application-specific resources;
+- typed per-test overrides of Nuxt auto-imports.
+
+It does not reset the whole app state.
+State created by startup plugins is not re-created between tests or files.
+Tests that need plugins re-initialized or a different startup config belong in a [separate Vitest config](#startup-sensitive-tests).
+
+- [The problem](#the-problem)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Migrating an existing suite](#migrating-an-existing-suite)
+- [Per-test overrides](#per-test-overrides)
+- [Project resets](#project-resets)
+- [Worker state](#worker-state)
+- [DOM helpers](#dom-helpers)
+- [Lifecycle](#lifecycle)
+- [Cleanup](#cleanup)
+- [Startup-sensitive tests](#startup-sensitive-tests)
+- [Compatibility and upstream](#compatibility-and-upstream)
+
+## The problem
+
+`@nuxt/test-utils` adds its runtime entry to `test.setupFiles`.
+The entry calls `vi.resetModules()` and starts Nuxt in `beforeAll` for every test file, so Nuxt is initialized again per file even with `isolate: false`.
+In a project with many small component test files, most of the run time goes into Nuxt startup.
+
+With this library, each Vitest worker starts Nuxt once, and all its test files run on that app.
+As a data point from one application with a local workaround, [nuxt/test-utils#1750](https://github.com/nuxt/test-utils/issues/1750) reports 12 files with 22 tests going from 19.6 s to 6.6 s with one worker; your numbers will differ.
+
+## Install
+
+```sh
+npm install -D nuxt-vitest-shared-app
+```
+
+Supported versions:
+
+| Package            | Versions                 |
+| ------------------ | ------------------------ |
+| `@nuxt/test-utils` | 4.3.x                    |
+| `nuxt`             | 4.4.2 and later 4.x      |
+| `vitest`           | 4.1.0 and later 4.x, 5.x |
+| `vue`              | 3.5.30 and later 3.x     |
+| `@vue/test-utils`  | 2.4.2 and later 2.x      |
+| `happy-dom`        | 20.0.11 and later        |
+
+CI runs the whole suite with the lowest listed versions, with the versions pinned in the lockfile, and with the latest compatible Vitest 4 release.
+jsdom is not supported in this version.
+
+## Quick start
+
+Replace `defineVitestConfig` with `defineSharedNuxtVitestConfig` in the Vitest config of your Nuxt component tests:
+
+```ts
+// vitest.config.ts
+import { defineSharedNuxtVitestConfig } from "nuxt-vitest-shared-app/config"
+
+export default defineSharedNuxtVitestConfig({
+  test: {
+    include: ["**/*.vitest.ts"],
+    environment: "nuxt",
+    pool: "threads",
+    isolate: false,
+  },
+})
+```
+
+Keep your existing test file patterns and other settings.
+Existing `mountSuspended` tests run on the shared app with the built-in cleanup as they are.
+Add a project setup file only when you need [per-test overrides](#per-test-overrides) or [project resets](#project-resets).
+
+The wrapper passes the config to `defineVitestConfig` from `@nuxt/test-utils/config`, adds the library lifecycle, and checks the settings a shared app relies on:
+
+- `test.environment` must be `"nuxt"` at the top level; Vitest projects and browser mode are not supported;
+- `test.isolate` must be `false`;
+- `test.pool` must be `"threads"` or `"forks"`; `isolate` has no effect in the VM pools;
+- `test.sequence.setupFiles` is set to `"list"`, and `"parallel"` is rejected;
+- `test.sequence.hooks: "parallel"` and `test.sequence.concurrent: true` are rejected.
+
+The second argument takes options:
+
+```ts
+defineSharedNuxtVitestConfig(config, { silenceSuspenseInfo: true })
+```
+
+With `silenceSuspenseInfo: true`, Vue's `<Suspense> is an experimental feature and its API will likely change.` message, which every `mountSuspended` call prints, is filtered through `test.onConsoleLog`; your own `onConsoleLog` still receives all other messages.
+
+## Migrating an existing suite
+
+Remove what the library now does:
+
+- `enableAutoUnmount` calls in project setup files: the library installs its own, and `@vue/test-utils` rejects a second call;
+- hooks that clean up what the library [cleans up](#cleanup), such as Nuxt state, storage, cookies, timers, and stubbed globals;
+- local patches or workarounds that start Nuxt once per worker.
+
+Keep project-specific cleanup, and move hooks that must run after every test into [project resets](#project-resets).
+
+Because modules stay cached, objects created at module level live for the whole environment, not for one file.
+A global replaced by one test file affects every file that runs after it in the worker, including objects that other modules already created from the previous global.
+For example, a test file that imports a forced `Intl` polyfill replaces the global constructor, while a formatter created earlier at module level still belongs to the previous implementation.
+
+- Install global polyfills once in a project setup file, before components are imported, and prefer polyfills that keep an existing implementation.
+- Do not replace global constructors with side-effect imports in individual test files.
+- Review module-level objects that depend on such globals, such as formatters, clients, and caches.
+- After the migration, run the suite on one worker with shuffled files, so all files share one environment in a different order, e.g. `vitest run --maxWorkers=1 --sequence.shuffle.files --sequence.seed=1`.
+
+## Per-test overrides
+
+A module mock registered again in a later file does not change references that the started app already captured.
+So the project installs a stable wrapper once with `mockNuxtImport`, and tests swap its implementation for one test.
+
+Register overridable imports in a project setup file:
+
+```ts
+// vitest.config.ts
+export default defineSharedNuxtVitestConfig({
+  test: {
+    // ...
+    setupFiles: ["./testing/nuxt/setup.ts"],
+  },
+})
+```
+
+```ts
+// testing/nuxt/setup.ts
+import { mockNuxtImport } from "@nuxt/test-utils/runtime"
+import { overridableNuxtImport } from "nuxt-vitest-shared-app"
+
+import type { navigateTo, useRoute } from "#app/composables/router"
+
+declare module "nuxt-vitest-shared-app" {
+  interface TestNuxtImports {
+    navigateTo: typeof navigateTo
+    useRoute: typeof useRoute
+  }
+}
+
+mockNuxtImport("navigateTo", overridableNuxtImport("navigateTo"))
+mockNuxtImport("useRoute", overridableNuxtImport("useRoute"))
+```
+
+Override them inside a test or a test hook:
+
+```ts
+import { mountSuspended } from "@nuxt/test-utils/runtime"
+import { overrideNuxtImport, overrideNuxtRoute } from "nuxt-vitest-shared-app"
+import { expect, it, vi } from "vitest"
+
+import ItemPage from "~/pages/items/[id].vue"
+
+it("opens the edit page", async () => {
+  const navigate = vi.fn()
+  overrideNuxtImport("navigateTo", navigate)
+  overrideNuxtRoute({ params: { id: "1" } })
+
+  const wrapper = await mountSuspended(ItemPage)
+  await wrapper.get("button").trigger("click")
+
+  expect(navigate).toHaveBeenCalledWith("/items/1/edit")
+})
+```
+
+Overrides apply to the current test only; the cleanup clears them.
+Do not set them at the top level of a test file: the file is collected before the app starts, and the override would outlive the test.
+
+Use a fallback for behavior that the app needs while it starts.
+First add `useUser` and its type to `TestNuxtImports`, as in the setup file above, then:
+
+```ts
+// testing/nuxt/setup.ts
+mockNuxtImport(
+  "useUser",
+  overridableNuxtImport("useUser", () => ref(null)),
+)
+```
+
+Plugins and other startup code call auto-imports before any test hook runs, so only a fallback applies to them.
+
+### `overridableNuxtImport(name, fallback?)`
+
+```ts
+overridableNuxtImport(name, fallback?): (original) => wrapper
+```
+
+Creates the `mockNuxtImport` factory; `mockNuxtImport` is a compile-time macro, so its calls stay in your project setup file.
+The wrapper calls the current test's override, or otherwise `fallback` if given, or the original import, preserving `this` and arguments.
+
+The project augments `TestNuxtImports` once, mapping import names to their types.
+`overridableNuxtImport` and `overrideNuxtImport` accept only registered names, and implementations are typed by the registry.
+
+The factory can run during hoisted mock evaluation: it does not initialize Nuxt or import the mocked modules.
+When a mock factory is evaluated again, it returns the wrapper that the app already holds.
+
+### `overrideNuxtImport(name, implementation)`
+
+Overrides the import for the current test.
+It throws when no wrapper for `name` was installed, so a missing `mockNuxtImport` line does not look like a working override.
+
+### `overrideNuxtRoute(route)`
+
+Makes the `useRoute` wrapper return exactly `route`, a `Partial` of the registered `useRoute` return type, for the current test.
+It requires `useRoute` in `TestNuxtImports` and an overridable `useRoute` mock.
+
+- It does not navigate or sync the real router.
+- It does not merge `route` with the real route: missing fields are not filled in, and the object does not satisfy the full `useRoute` contract.
+- Mounted components do not react to it; set it before mounting.
+
+## Project resets
+
+```ts
+registerNuxtTestReset(key: string, reset: () => unknown): () => void
+```
+
+Registers a reset that runs after each test, see step 6 of the [cleanup](#cleanup).
+Use it for application resources that the library does not know about, such as test API clients, subscriptions, and caches:
+
+```ts
+// testing/nuxt/setup.ts
+import { registerNuxtTestReset } from "nuxt-vitest-shared-app"
+
+import { testApiClient } from "./api-client"
+
+registerNuxtTestReset("api-client", () => testApiClient.reset())
+```
+
+Registering the same key again replaces the callback and keeps its position, so a setup file that runs for every test file does not accumulate registrations.
+The returned function removes the registration, unless it has already been replaced.
+
+## Worker state
+
+```ts
+getOrCreateWorkerState<T>(name: string, create: () => T): T
+```
+
+Returns state bound to the current Nuxt environment, creating it on first use.
+Use it for project helpers whose state must survive module re-evaluation between files, such as a test API client that the started app also uses.
+
+## DOM helpers
+
+```ts
+import { stubVisibleIntersectionObserver } from "nuxt-vitest-shared-app/dom"
+import { beforeEach } from "vitest"
+
+beforeEach(() => {
+  stubVisibleIntersectionObserver()
+})
+```
+
+Stubs the global `IntersectionObserver` with one that reports each observed element as visible immediately in `observe()`, because happy-dom and the `@nuxt/test-utils` mock never call the observer callback.
+It accepts elements and the environment's `window` and `document`, which VueUse passes for window scrolling, e.g. in `useInfiniteScroll(window)`; they are measured as `document.documentElement` and reported as the entry `target` unchanged.
+Any other target throws a `TypeError`.
+Entries include `time`, which vueuse `useElementVisibility` uses to pick the latest entry.
+The stub is installed with `vi.stubGlobal`, so the cleanup removes it after the test; install it in `beforeEach` or in the test itself.
+
+## Lifecycle
+
+| What                                                                           | Lifetime                                          |
+| ------------------------------------------------------------------------------ | ------------------------------------------------- |
+| Started app, route baseline, project resets, overridable imports, worker state | The Nuxt environment (its `window`) of the worker |
+| Library `beforeAll` / `beforeEach` hooks                                       | One test file                                     |
+| Import overrides and per-test resources                                        | One test                                          |
+
+For each test file of a worker, the library:
+
+1. starts Nuxt if this environment has no app yet, or awaits the startup in progress;
+2. checks that the Nuxt app is mounted in the current environment's document, and fails the file with a clear error otherwise;
+3. captures the route baseline and the direct children of `document.body` once per environment, right after the first successful startup and before any project `beforeAll` or `beforeEach`;
+4. fails tests that run concurrently in the worker (`test.concurrent`, `describe.concurrent`);
+5. cleans up after each test.
+
+Vitest drops hooks between files even with `isolate: false`, so the lifecycle hooks are registered again for every file.
+
+Library state is bound to the environment's `window` and is never reused by another environment.
+
+Watch mode is not tested; the guarantees in this document apply to `vitest run`.
+
+### Tests run sequentially within a worker
+
+All tests of a worker share one app, so they must not run concurrently.
+Parallelism across workers is supported: each worker has its own environment and its own app.
+
+### Module cache
+
+Modules are evaluated once per environment and stay cached for the following files.
+A singleton created by a plugin at startup is the same instance that components and test files see in every file of the worker.
+Only the first file of an environment, or the next file after a failed startup, starts from a clean module graph.
+
+### Files with another environment
+
+Test files with another environment, such as `// @vitest-environment node`, run without the library lifecycle.
+In such files, `overridableNuxtImport` factories return the fallback or the original import, and `registerNuxtTestReset` registers nothing, so the same project setup file works for them.
+`overrideNuxtImport`, `overrideNuxtRoute` and `getOrCreateWorkerState` throw outside the `nuxt` environment.
+
+## Cleanup
+
+After each test, the library runs these steps in order.
+They run after all `afterEach` hooks of the project, also when one of these hooks fails.
+
+1. unmounts wrappers mounted in the test through `@vue/test-utils` (including `mountSuspended`), using `enableAutoUnmount`;
+2. `await nextTick()` and `await flushPromises()`;
+3. navigates the app's own router back to the route baseline with `router.replace` if the route differs, and verifies the resulting route;
+4. clears import overrides;
+5. `await clearError()`, `clearNuxtData()`, `clearNuxtState(undefined, { reset: false })`;
+6. runs project resets registered with `registerNuxtTestReset`, in registration order, awaiting each;
+7. `localStorage.clear()`, `sessionStorage.clear()`, and expires every cookie visible in `document.cookie` for path `/` of the current origin;
+8. `vi.clearAllTimers()`, `vi.useRealTimers()`, `vi.unstubAllEnvs()`, `vi.unstubAllGlobals()`;
+9. removes direct children of `document.body` that were not present at startup.
+
+The exact scope:
+
+- `flushPromises` only settles handlers of promises that are already resolved; subscriptions, requests, and other background work need their own project resets;
+- step 3 uses the router instance of the app, never the overridable `useRoute`/`navigateTo`;
+- DOM cleanup removes only new direct children of `document.body`; changes to nodes that existed at startup are not reverted;
+- cookies are expired only as listed above; `HttpOnly` cookies and cookies of other paths or domains are not touched;
+- state created by startup plugins is not re-created.
+
+The library does not touch Vitest mocks (`vi.fn`, `vi.spyOn`, call history).
+Configure `clearMocks`, `mockReset`, or `restoreMocks` in your Vitest config as needed.
+
+### Failed cleanup
+
+If a cleanup step throws or rejects, the remaining steps still run.
+Failures are reported with their step names, and all collected errors are preserved.
+
+If the cleanup does not finish within the Vitest hook timeout, e.g. because a project reset never settles, Vitest does not cancel it, and it may still change state later.
+The library then restores real timers, envs, and globals right away, because project `afterEach` and `afterAll` hooks still run, but the other remaining steps are not guaranteed to run.
+If Vitest aborts a test because the test, one of its hooks, or an `onTestFinished`/`onTestFailed` callback times out, the environment is rejected the same way, because unfinished asynchronous work may continue after Vitest stops waiting for it; the cleanup of that test still runs.
+
+After a failed or timed out cleanup or an aborted test, the environment is in an unknown state, even if the pending work finishes later.
+Every following test in it fails with an error that references the original failure, and following files fail before their own `beforeAll` hooks.
+There is no recovery in this version.
+
+### Failed startup
+
+If Nuxt startup fails, the file fails with the original error, and a partially created app is unmounted.
+Nuxt itself catches errors of plugins during startup and continues with a partially initialized app; the library treats such an error as a startup failure too, and reports it with the Nuxt error as its cause.
+If unmounting fails too, both errors are reported together in an `AggregateError`, the original one first.
+The next file of the worker tries the startup again from a clean module graph.
+
+## Startup-sensitive tests
+
+Tests that need startup plugins re-initialized, a different runtime config, or other startup options cannot share the app.
+Put them in a separate Vitest config with normal isolation and run it with its own command, because the shared-app config does not support Vitest projects:
+
+```ts
+// vitest.isolated.config.ts
+import { defineVitestConfig } from "@nuxt/test-utils/config"
+
+export default defineVitestConfig({
+  test: {
+    include: ["**/*.isolated.vitest.ts"],
+    environment: "nuxt",
+  },
+})
+```
+
+```sh
+vitest run
+vitest run --config vitest.isolated.config.ts
+```
+
+Exclude the isolated files from the shared-app config.
+
+## Compatibility and upstream
+
+Until `@nuxt/test-utils` reuses the app natively, the library replaces its runtime entry with an adapter that follows the lifecycle of [nuxt/test-utils#1821](https://github.com/nuxt/test-utils/pull/1821).
+The adapter loads the internal `setupNuxt` from `@nuxt/test-utils/dist/runtime/shared/nuxt.mjs` through the Vitest module runner, because it shares state with `mountSuspended`.
+This internal module is not part of the public `@nuxt/test-utils` API, so each supported release line is tested explicitly.
+
+| Installed `@nuxt/test-utils`                            | Behavior                                                        |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| 4.3.x                                                   | The adapter replaces the upstream runtime entry                 |
+| A tested release with native reuse (none published yet) | The upstream entry is kept; the library lifecycle runs after it |
+| Any other version                                       | The config throws an error with the installed version           |
+
+Native reuse is detected by version, not by inspecting `@nuxt/test-utils` internals.
+Your tests and setup files stay the same when the library switches to native reuse.
+Upstream work on native reuse is tracked in [nuxt/test-utils#1750](https://github.com/nuxt/test-utils/issues/1750) and [nuxt/test-utils#1821](https://github.com/nuxt/test-utils/pull/1821).
+
+[untestutils](https://github.com/s00d/untestutils) is a test harness whose Nuxt unit environment (`environment: "untestutils"`) has the same per-file startup.
+Worker-scoped app reuse there is requested in [s00d/untestutils#1](https://github.com/s00d/untestutils/issues/1).
+This library supports only `@nuxt/test-utils` for now; untestutils support may be added later, natively if that request is implemented.

package/dist/adapter/entry.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/adapter/entry.mjs

@@ -0,0 +1,62 @@
+import { t as SETUP_NUXT_ID } from "../setup-nuxt-id-Bb5_sSMp.mjs";
+import { t as getStartupError } from "../startup-error-C4H64PiD.mjs";
+import { beforeAll, vi } from "vitest";
+//#region src/adapter/entry.ts
+const ADAPTER_KEY = Symbol.for("nuxt-vitest-shared-app:adapter");
+if (typeof window !== "undefined" && window.__NUXT_VITEST_ENVIRONMENT__) {
+	const win = window;
+	const state = win[ADAPTER_KEY] ??= {};
+	if (!state.started) vi.resetModules();
+	beforeAll(async () => {
+		state.startup ??= startNuxt(win, state).finally(() => {
+			if (!state.started) delete state.startup;
+		});
+		await state.startup;
+	});
+}
+async function startNuxt(win, state) {
+	const { getNuxtAppCtx, tryUseNuxtApp } = await import("#app/nuxt");
+	const previousApp = tryUseNuxtApp();
+	const hasPayload = "__NUXT__" in win;
+	const payload = win.__NUXT__;
+	let failed = false;
+	let setupError;
+	try {
+		const { setupNuxt } = await import(
+			/* @vite-ignore */
+			SETUP_NUXT_ID
+);
+		if (typeof setupNuxt !== "function") throw new TypeError("nuxt-vitest-shared-app: @nuxt/test-utils no longer exports setupNuxt from dist/runtime/shared/nuxt.mjs; this @nuxt/test-utils version is not supported.");
+		await setupNuxt();
+	} catch (error) {
+		failed = true;
+		setupError = error;
+	}
+	const createdApp = tryUseNuxtApp();
+	const app = createdApp && createdApp !== previousApp ? createdApp : void 0;
+	const startupError = app && getStartupError(app);
+	if (!failed && !startupError) {
+		state.started = true;
+		return;
+	}
+	const error = startupError ?? setupError;
+	let rollbackError;
+	try {
+		app?.vueApp.unmount();
+	} catch (unmountError) {
+		rollbackError = unmountError;
+	} finally {
+		if (app) {
+			const context = getNuxtAppCtx(app._id);
+			if (context.tryUse() === app) context.unset();
+		}
+		if (hasPayload) win.__NUXT__ = payload;
+	}
+	if (rollbackError === void 0) throw error;
+	throw new AggregateError([error, rollbackError], `nuxt-vitest-shared-app: Nuxt startup failed (${errorMessage(error)}), and unmounting the partially created app failed too (${errorMessage(rollbackError)}).`, { cause: error });
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+export {};

package/dist/config.d.mts

@@ -0,0 +1,21 @@
+import { defineVitestConfig } from "@nuxt/test-utils/config";
+//#region src/config/apply.d.ts
+/** Config accepted by `defineVitestConfig` from `@nuxt/test-utils/config`. */
+type NuxtVitestConfig = NonNullable<Parameters<typeof defineVitestConfig>[0]>;
+/** Options of `defineSharedNuxtVitestConfig`. */
+interface SharedNuxtVitestOptions {
+  /** Hide Vue's `<Suspense> is an experimental feature` console message, which every `mountSuspended` call prints. */
+  silenceSuspenseInfo?: boolean;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Wraps `defineVitestConfig` from `@nuxt/test-utils/config` so all test files of a Vitest worker share one Nuxt app.
+ *
+ * It starts Nuxt once per environment, adds the library lifecycle (readiness check, per-test cleanup, rejection of concurrent tests), and validates the settings a shared app relies on.
+ *
+ * @throws When the config uses an unsupported setting or the installed `@nuxt/test-utils` version was not tested.
+ */
+declare function defineSharedNuxtVitestConfig(config: NuxtVitestConfig, options?: SharedNuxtVitestOptions): ReturnType<typeof defineVitestConfig>;
+//#endregion
+export { type SharedNuxtVitestOptions, defineSharedNuxtVitestConfig };

package/dist/config.mjs

@@ -0,0 +1,151 @@
+import "./setup-nuxt-id-Bb5_sSMp.mjs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { defineVitestConfig } from "@nuxt/test-utils/config";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+//#region src/adapter/setup-nuxt-plugin.ts
+/**
+* Creates the Vite plugin that resolves `SETUP_NUXT_ID` to the internal `setupNuxt` module of the installation.
+*
+* @throws When the installation has no such module.
+*/
+function setupNuxtPlugin(installation) {
+	const setupNuxtPath = join(installation.runtimeDir, "shared", "nuxt.mjs");
+	if (!existsSync(setupNuxtPath)) throw new Error(`nuxt-vitest-shared-app: @nuxt/test-utils ${installation.version} has no internal ${setupNuxtPath}; this version is not supported.`);
+	return {
+		name: "nuxt-vitest-shared-app:setup-nuxt",
+		enforce: "pre",
+		resolveId(id) {
+			if (id === "#nuxt-vitest-shared-app/setup-nuxt") return setupNuxtPath;
+		}
+	};
+}
+//#endregion
+//#region src/config/versions.ts
+/**
+* Tested `@nuxt/test-utils` release lines.
+*
+* Native reuse is detected by version only, until upstream offers a documented public signal:
+*
+* - https://github.com/nuxt/test-utils/issues/1750
+* - https://github.com/nuxt/test-utils/pull/1821
+*/
+const TESTED_VERSIONS = [{
+	line: "4.3",
+	mode: "adapter"
+}];
+/**
+* Resolves the startup mode for an installed `@nuxt/test-utils` version.
+*
+* @throws For versions that were not tested, instead of guessing.
+*/
+function resolveStartupMode(version) {
+	const match = /^(\d+\.\d+)\.\d+$/.exec(version);
+	const tested = match && TESTED_VERSIONS.find((entry) => entry.line === match[1]);
+	if (!tested) {
+		const lines = TESTED_VERSIONS.map((entry) => `${entry.line}.x`).join(", ");
+		throw new Error(`nuxt-vitest-shared-app: @nuxt/test-utils ${version} is not supported. Supported versions: ${lines}.`);
+	}
+	return tested.mode;
+}
+//#endregion
+//#region src/config/apply.ts
+const SUSPENSE_INFO = "<Suspense> is an experimental feature and its API will likely change.";
+/** Locates the `@nuxt/test-utils` installation that `@nuxt/test-utils/config` resolves to from `from`. */
+function locateTestUtils(from) {
+	const require = createRequire(from);
+	const configPath = require.resolve("@nuxt/test-utils/config");
+	return {
+		version: JSON.parse(readFileSync(require.resolve("@nuxt/test-utils/package.json"), "utf8")).version,
+		runtimeDir: join(dirname(configPath), "runtime")
+	};
+}
+/**
+* Turns a config resolved by `defineVitestConfig` into a shared-app config, in place.
+*
+* @throws When the config is incompatible with a shared app or the installed `@nuxt/test-utils` is not supported.
+*/
+function applySharedApp(config, { options, installation, files, mode = resolveStartupMode(installation.version) }) {
+	const test = config.test ??= {};
+	const fail = (message) => {
+		throw new Error(`nuxt-vitest-shared-app: ${message}`);
+	};
+	if (test.environment !== "nuxt") fail("set test.environment to \"nuxt\"; Vitest projects and other environments are not supported.");
+	if (test.browser?.enabled) fail("Vitest browser mode is not supported.");
+	if (test.isolate !== false) fail("set test.isolate to false so test files share the Nuxt app.");
+	if (test.pool !== void 0 && test.pool !== "threads" && test.pool !== "forks") fail(`test.pool must be "threads" or "forks", got ${JSON.stringify(test.pool)}.`);
+	const sequence = test.sequence ??= {};
+	if (sequence.setupFiles === "parallel") fail("test.sequence.setupFiles must be \"list\".");
+	sequence.setupFiles = "list";
+	if (sequence.hooks === "parallel") fail("test.sequence.hooks must be \"stack\" or \"list\".");
+	if (sequence.concurrent) fail("test.sequence.concurrent is not supported.");
+	const root = config.root ? resolve(config.root) : process.cwd();
+	const setupFiles = toArray(test.setupFiles);
+	const upstreamEntry = join(installation.runtimeDir, "entry.mjs");
+	const entryIndexes = setupFiles.flatMap((file, index) => samePath(isAbsolute(file) ? file : resolve(root, file), upstreamEntry) ? [index] : []);
+	if (entryIndexes.length !== 1) fail(`expected exactly one @nuxt/test-utils ${installation.version} runtime entry (${upstreamEntry}) in test.setupFiles, found ${entryIndexes.length}. Setup files: ${setupFiles.join(", ") || "(none)"}.`);
+	const entryIndex = entryIndexes[0];
+	test.setupFiles = [
+		mode === "adapter" ? files.adapterEntry : setupFiles[entryIndex],
+		files.lifecycle,
+		...setupFiles.filter((_, index) => index !== entryIndex)
+	];
+	if (mode === "adapter") (config.plugins ??= []).push(setupNuxtPlugin(installation));
+	const deps = (test.server ??= {}).deps ??= {};
+	if (deps.inline !== true) deps.inline = [...deps.inline ?? [], /[\\/]node_modules[\\/]nuxt-vitest-shared-app[\\/]/];
+	if (options.silenceSuspenseInfo) {
+		const onConsoleLog = test.onConsoleLog;
+		test.onConsoleLog = (log, ...args) => {
+			if (log.includes(SUSPENSE_INFO)) return false;
+			return onConsoleLog?.(log, ...args);
+		};
+	}
+	return config;
+}
+function toArray(value) {
+	return value === void 0 ? [] : Array.isArray(value) ? value : [value];
+}
+function samePath(left, right) {
+	return realpath(left) === realpath(right);
+}
+function realpath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return resolve(path);
+	}
+}
+//#endregion
+//#region src/config/define.ts
+/**
+* Creates the config function; `mode` bypasses the version policy and is used only by this library's own tests.
+*/
+function createSharedNuxtVitestConfig(config, options, libraryUrl, mode) {
+	const extension = libraryUrl.endsWith(".ts") ? ".ts" : ".mjs";
+	const files = {
+		adapterEntry: fileURLToPath(new URL(`./adapter/entry${extension}`, libraryUrl)),
+		lifecycle: fileURLToPath(new URL(`./runtime/lifecycle${extension}`, libraryUrl))
+	};
+	const resolveConfig = defineVitestConfig(config);
+	return async (...args) => applySharedApp(await resolveConfig(...args), {
+		options,
+		installation: locateTestUtils(libraryUrl),
+		files,
+		mode
+	});
+}
+//#endregion
+//#region src/config.ts
+/**
+* Wraps `defineVitestConfig` from `@nuxt/test-utils/config` so all test files of a Vitest worker share one Nuxt app.
+*
+* It starts Nuxt once per environment, adds the library lifecycle (readiness check, per-test cleanup, rejection of concurrent tests), and validates the settings a shared app relies on.
+*
+* @throws When the config uses an unsupported setting or the installed `@nuxt/test-utils` version was not tested.
+*/
+function defineSharedNuxtVitestConfig(config, options = {}) {
+	return createSharedNuxtVitestConfig(config, options, import.meta.url);
+}
+//#endregion
+export { defineSharedNuxtVitestConfig };

package/dist/dom.d.mts

@@ -0,0 +1,13 @@
+//#region src/dom.d.ts
+/**
+ * Stubs the global `IntersectionObserver` with one that reports every observed target as visible immediately in `observe()`.
+ *
+ * Targets are elements, plus the environment's own `window` and `document`, which are measured as `document.documentElement`.
+ * Any other target throws a `TypeError`, as a browser does.
+ *
+ * happy-dom and the `@nuxt/test-utils` mock never call the observer callback, so components that wait for visibility never render their content.
+ * The stub is installed with `vi.stubGlobal`, so the per-test cleanup removes it.
+ */
+declare function stubVisibleIntersectionObserver(): void;
+//#endregion
+export { stubVisibleIntersectionObserver };

package/dist/dom.mjs

@@ -0,0 +1,54 @@
+import { vi } from "vitest";
+//#region src/dom.ts
+/**
+* Stubs the global `IntersectionObserver` with one that reports every observed target as visible immediately in `observe()`.
+*
+* Targets are elements, plus the environment's own `window` and `document`, which are measured as `document.documentElement`.
+* Any other target throws a `TypeError`, as a browser does.
+*
+* happy-dom and the `@nuxt/test-utils` mock never call the observer callback, so components that wait for visibility never render their content.
+* The stub is installed with `vi.stubGlobal`, so the per-test cleanup removes it.
+*/
+function stubVisibleIntersectionObserver() {
+	vi.stubGlobal("IntersectionObserver", VisibleIntersectionObserver);
+}
+var VisibleIntersectionObserver = class {
+	root;
+	rootMargin;
+	scrollMargin = "0px";
+	thresholds;
+	#callback;
+	constructor(callback, options = {}) {
+		this.#callback = callback;
+		this.root = options.root ?? null;
+		this.rootMargin = options.rootMargin ?? "0px";
+		const threshold = options.threshold ?? 0;
+		this.thresholds = Array.isArray(threshold) ? threshold : [threshold];
+	}
+	observe(target) {
+		const rect = measure(target);
+		const entry = {
+			target,
+			isIntersecting: true,
+			intersectionRatio: 1,
+			boundingClientRect: rect,
+			intersectionRect: rect,
+			rootBounds: null,
+			time: performance.now()
+		};
+		this.#callback([entry], this);
+	}
+	unobserve() {}
+	disconnect() {}
+	takeRecords() {
+		return [];
+	}
+};
+function measure(target) {
+	const unknownTarget = target;
+	if (unknownTarget === window || unknownTarget === document) return document.documentElement.getBoundingClientRect();
+	if (typeof target?.getBoundingClientRect !== "function") throw new TypeError("Failed to execute 'observe' on 'IntersectionObserver': parameter 1 is not of type 'Element'.");
+	return target.getBoundingClientRect();
+}
+//#endregion
+export { stubVisibleIntersectionObserver };

package/dist/index.d.mts

@@ -0,0 +1,71 @@
+//#region src/overrides.d.ts
+/**
+ * Registry of Nuxt auto-imports that tests may override.
+ *
+ * Augment it once in the project setup file, mapping each import name to its type:
+ *
+ * ```ts
+ * declare module "nuxt-vitest-shared-app" {
+ *   interface TestNuxtImports {
+ *     useRoute: typeof useRoute
+ *   }
+ * }
+ * ```
+ */
+interface TestNuxtImports {}
+/** Name of a registered overridable auto-import. */
+type TestNuxtImportName = keyof TestNuxtImports & string;
+/** Route object accepted by `overrideNuxtRoute`, derived from the registered `useRoute` type. */
+type TestNuxtRoute = TestNuxtImports extends {
+  useRoute: (...args: never[]) => infer Route;
+} ? Partial<Route> : never;
+/**
+ * Creates a `mockNuxtImport` factory that installs a stable overridable wrapper for `name`.
+ *
+ * The wrapper calls the implementation set with `overrideNuxtImport` for the current test, or otherwise `fallback` if given, or the original import, preserving `this` and arguments.
+ * Unlike `overrideNuxtImport` in `beforeEach`, `fallback` also applies while the app starts, e.g. to auto-imports called by plugins.
+ * Outside the Vitest `nuxt` environment, e.g. in a file with `@vitest-environment node`, the factory returns `fallback` or the original.
+ *
+ * @example
+ * ```ts
+ * mockNuxtImport("useRoute", overridableNuxtImport("useRoute"))
+ * mockNuxtImport("useUser", overridableNuxtImport("useUser", () => ref(null)))
+ * ```
+ */
+declare function overridableNuxtImport<Name extends TestNuxtImportName>(name: Name, fallback?: TestNuxtImports[Name]): (original: TestNuxtImports[Name]) => TestNuxtImports[Name];
+/**
+ * Overrides a registered Nuxt auto-import for the current test.
+ *
+ * Overrides are cleared after each test.
+ *
+ * @throws When no wrapper for `name` was installed with `mockNuxtImport(name, overridableNuxtImport(name))`.
+ */
+declare function overrideNuxtImport<Name extends TestNuxtImportName>(name: Name, implementation: TestNuxtImports[Name]): void;
+/**
+ * Makes the registered `useRoute` wrapper return exactly `route` for the current test.
+ *
+ * The object is not merged with the real route, does not navigate or sync the real router, and is read by components only when they call `useRoute`, so set it before mounting.
+ */
+declare function overrideNuxtRoute(route: TestNuxtRoute): void;
+//#endregion
+//#region src/resets.d.ts
+/**
+ * Registers a project reset that runs after each test, in registration order, and is awaited.
+ *
+ * Registering the same `key` again replaces the callback and keeps its position, so a setup file that runs for every test file does not accumulate registrations.
+ *
+ * Outside the Vitest `nuxt` environment, e.g. in a file with `@vitest-environment node`, nothing is registered.
+ *
+ * @returns A function that removes this registration, unless it has already been replaced.
+ */
+declare function registerNuxtTestReset(key: string, reset: () => unknown): () => void;
+//#endregion
+//#region src/worker-state.d.ts
+/**
+ * Returns state bound to the current Nuxt environment, creating it with `create` on first use.
+ *
+ * Use it for project helpers whose state must survive module re-evaluation between test files, such as a test API client shared with the started app.
+ */
+declare function getOrCreateWorkerState<T>(name: string, create: () => T): T;
+//#endregion
+export { type TestNuxtImportName, type TestNuxtImports, type TestNuxtRoute, getOrCreateWorkerState, overridableNuxtImport, overrideNuxtImport, overrideNuxtRoute, registerNuxtTestReset };

package/dist/index.mjs

@@ -0,0 +1,95 @@
+import { n as isNuxtEnvironment, t as getEnvironmentStore } from "./store-Dklvd4X3.mjs";
+//#region src/overrides.ts
+const WRAPPER_MARK = Symbol.for("nuxt-vitest-shared-app:wrapper");
+/**
+* Creates a `mockNuxtImport` factory that installs a stable overridable wrapper for `name`.
+*
+* The wrapper calls the implementation set with `overrideNuxtImport` for the current test, or otherwise `fallback` if given, or the original import, preserving `this` and arguments.
+* Unlike `overrideNuxtImport` in `beforeEach`, `fallback` also applies while the app starts, e.g. to auto-imports called by plugins.
+* Outside the Vitest `nuxt` environment, e.g. in a file with `@vitest-environment node`, the factory returns `fallback` or the original.
+*
+* @example
+* ```ts
+* mockNuxtImport("useRoute", overridableNuxtImport("useRoute"))
+* mockNuxtImport("useUser", overridableNuxtImport("useUser", () => ref(null)))
+* ```
+*/
+function overridableNuxtImport(name, fallback) {
+	return (original) => {
+		if (!isNuxtEnvironment()) return fallback ?? original;
+		const store = getEnvironmentStore();
+		const existing = store.imports.get(name);
+		const defaultImplementation = unwrap(fallback ?? original);
+		if (existing) {
+			existing.defaultImplementation = defaultImplementation;
+			return existing.wrapper;
+		}
+		const entry = {
+			defaultImplementation,
+			wrapper(...args) {
+				return (store.overrides.get(name) ?? entry.defaultImplementation).apply(this, args);
+			}
+		};
+		Object.defineProperty(entry.wrapper, WRAPPER_MARK, { value: entry });
+		store.imports.set(name, entry);
+		return entry.wrapper;
+	};
+}
+function unwrap(fn) {
+	const entry = fn[WRAPPER_MARK];
+	return entry ? entry.defaultImplementation : fn;
+}
+/**
+* Overrides a registered Nuxt auto-import for the current test.
+*
+* Overrides are cleared after each test.
+*
+* @throws When no wrapper for `name` was installed with `mockNuxtImport(name, overridableNuxtImport(name))`.
+*/
+function overrideNuxtImport(name, implementation) {
+	const store = getEnvironmentStore();
+	if (!store.imports.has(name)) throw new Error(`nuxt-vitest-shared-app: "${name}" is not overridable. Add mockNuxtImport("${name}", overridableNuxtImport("${name}")) to the project setup file.`);
+	store.overrides.set(name, implementation);
+}
+/**
+* Makes the registered `useRoute` wrapper return exactly `route` for the current test.
+*
+* The object is not merged with the real route, does not navigate or sync the real router, and is read by components only when they call `useRoute`, so set it before mounting.
+*/
+function overrideNuxtRoute(route) {
+	overrideNuxtImport("useRoute", (() => route));
+}
+//#endregion
+//#region src/resets.ts
+/**
+* Registers a project reset that runs after each test, in registration order, and is awaited.
+*
+* Registering the same `key` again replaces the callback and keeps its position, so a setup file that runs for every test file does not accumulate registrations.
+*
+* Outside the Vitest `nuxt` environment, e.g. in a file with `@vitest-environment node`, nothing is registered.
+*
+* @returns A function that removes this registration, unless it has already been replaced.
+*/
+function registerNuxtTestReset(key, reset) {
+	if (!isNuxtEnvironment()) return () => {};
+	const store = getEnvironmentStore();
+	const registration = { reset };
+	store.resets.set(key, registration);
+	return () => {
+		if (store.resets.get(key) === registration) store.resets.delete(key);
+	};
+}
+//#endregion
+//#region src/worker-state.ts
+/**
+* Returns state bound to the current Nuxt environment, creating it with `create` on first use.
+*
+* Use it for project helpers whose state must survive module re-evaluation between test files, such as a test API client shared with the started app.
+*/
+function getOrCreateWorkerState(name, create) {
+	const { workerState } = getEnvironmentStore();
+	if (!workerState.has(name)) workerState.set(name, create());
+	return workerState.get(name);
+}
+//#endregion
+export { getOrCreateWorkerState, overridableNuxtImport, overrideNuxtImport, overrideNuxtRoute, registerNuxtTestReset };

package/dist/runtime/lifecycle.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/runtime/lifecycle.mjs

@@ -0,0 +1,180 @@
+import { n as isNuxtEnvironment, t as getEnvironmentStore } from "../store-Dklvd4X3.mjs";
+import { t as getStartupError } from "../startup-error-C4H64PiD.mjs";
+import { beforeAll, beforeEach, vi } from "vitest";
+import { disableAutoUnmount, enableAutoUnmount, flushPromises } from "@vue/test-utils";
+import { nextTick } from "vue";
+//#region src/runtime/router.ts
+/**
+* Returns the router instance of the app.
+*
+* Unlike the auto-imported `useRouter`/`useRoute`/`navigateTo`, it cannot be replaced by a project's `mockNuxtImport`.
+*/
+function getRealRouter(nuxtApp) {
+	return nuxtApp.$router;
+}
+//#endregion
+//#region src/runtime/cleanup.ts
+/** Thrown after cleanup when one or more steps failed; `errors` holds every original error. */
+var CleanupError = class extends AggregateError {
+	failures;
+	constructor(failures) {
+		super(failures.map((failure) => failure.error), `nuxt-vitest-shared-app: cleanup failed.\n${failures.map((failure) => `- ${failure.step}: ${errorMessage(failure.error)}`).join("\n")}`);
+		this.name = "CleanupError";
+		this.failures = failures;
+	}
+};
+/**
+* Restores documented Nuxt and test-owned state after a test.
+*
+* Every step runs even if an earlier independent step failed.
+*
+* @throws {CleanupError} With all step failures after all steps have run.
+*/
+async function cleanupAfterTest(store, baseline, unmountWrappers) {
+	const failures = [];
+	async function step(name, run) {
+		try {
+			await run();
+		} catch (error) {
+			failures.push({
+				step: name,
+				error
+			});
+		}
+	}
+	await step("unmount wrappers", () => unmountWrappers?.());
+	await step("flush promises", async () => {
+		await nextTick();
+		await flushPromises();
+	});
+	await step("restore route", async () => {
+		const { useNuxtApp } = await importNuxt();
+		const router = getRealRouter(useNuxtApp());
+		if (router.currentRoute.value.fullPath !== baseline.route) {
+			await router.replace(baseline.route);
+			const route = router.currentRoute.value.fullPath;
+			if (route !== baseline.route) throw new Error(`route is ${route} after navigating back to ${baseline.route}`);
+		}
+	});
+	await step("clear overrides", () => store.overrides.clear());
+	await step("clearError", async () => {
+		const { clearError } = await importNuxt();
+		await clearError();
+	});
+	await step("clearNuxtData", async () => {
+		const { clearNuxtData } = await importNuxt();
+		clearNuxtData();
+	});
+	await step("clearNuxtState", async () => {
+		const { clearNuxtState } = await importNuxt();
+		clearNuxtState(void 0, { reset: false });
+	});
+	for (const [key, { reset }] of store.resets) await step(`project reset "${key}"`, reset);
+	await step("clear localStorage", () => localStorage.clear());
+	await step("clear sessionStorage", () => sessionStorage.clear());
+	await step("expire cookies", expireCookies);
+	for (const [name, run] of RUNNER_STEPS) await step(name, run);
+	await step("remove body children", () => {
+		for (const child of Array.from(document.body.children)) if (!baseline.bodyChildren.has(child)) child.remove();
+	});
+	if (failures.length) throw new CleanupError(failures);
+}
+function importNuxt() {
+	return import("nuxt/app");
+}
+const RUNNER_STEPS = [
+	["clear timers", () => vi.clearAllTimers()],
+	["use real timers", () => vi.useRealTimers()],
+	["unstub envs", () => vi.unstubAllEnvs()],
+	["unstub globals", () => vi.unstubAllGlobals()]
+];
+/** Restores timers, envs and globals as far as possible, ignoring failures, for an environment that is already contaminated. */
+function restoreTestRunner() {
+	for (const [, run] of RUNNER_STEPS) try {
+		run();
+	} catch {}
+}
+/** Expires every cookie visible in `document.cookie` for path `/` of the current origin. */
+function expireCookies() {
+	for (const cookie of document.cookie.split(";")) {
+		const name = cookie.split("=", 1)[0].trim();
+		if (name) document.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/`;
+	}
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/runtime/readiness.ts
+/**
+* Checks that `nuxtApp` is mounted in `document`, whichever entry started it.
+*
+* The global Nuxt context may still hold an app started in another environment of the same worker, so existence alone is not enough.
+*
+* @throws When the app is missing, unmounted, or mounted in another document.
+*/
+function assertAppRunning(nuxtApp, document) {
+	const vueApp = nuxtApp?.vueApp;
+	const container = vueApp?._container;
+	const problem = !nuxtApp ? "no Nuxt app exists" : !container || container.__vue_app__ !== vueApp ? "the Nuxt app is not mounted" : container.ownerDocument !== document || !container.isConnected ? "the Nuxt app is mounted in another document" : void 0;
+	if (problem) throw new Error(`nuxt-vitest-shared-app: the Nuxt app is not running in the current test environment (${problem}). Make sure the config is created with defineSharedNuxtVitestConfig and the Nuxt startup succeeded.`);
+	return nuxtApp;
+}
+//#endregion
+//#region src/runtime/lifecycle.ts
+if (isNuxtEnvironment()) installLifecycle();
+function installLifecycle() {
+	let unmountWrappers;
+	disableAutoUnmount();
+	enableAutoUnmount((unmount) => {
+		unmountWrappers = unmount;
+	});
+	beforeAll(async () => {
+		const store = getEnvironmentStore();
+		assertNotContaminated(store);
+		const { tryUseNuxtApp } = await import("nuxt/app");
+		const nuxtApp = assertAppRunning(tryUseNuxtApp(), document);
+		if (store.startupFailure) throw new Error("nuxt-vitest-shared-app: Nuxt startup failed earlier in this environment.", { cause: store.startupFailure });
+		if (!store.baseline) {
+			const startupError = getStartupError(nuxtApp);
+			if (startupError) {
+				store.startupFailure = startupError;
+				throw startupError;
+			}
+		}
+		store.baseline ??= {
+			route: getRealRouter(nuxtApp).currentRoute.value.fullPath,
+			bodyChildren: new Set(document.body.children)
+		};
+	});
+	beforeEach(({ task, signal, onTestFinished }) => {
+		const store = getEnvironmentStore();
+		assertNotContaminated(store);
+		if (task.concurrent) throw new Error("nuxt-vitest-shared-app: concurrent tests are not supported, because all tests of a worker share one Nuxt app. Remove test.concurrent / describe.concurrent.");
+		const onAbort = () => {
+			store.contamination ??= new Error(store.cleanupPending ? "nuxt-vitest-shared-app: the cleanup after an earlier test did not finish in time." : "nuxt-vitest-shared-app: an earlier test was aborted, e.g. by a timeout, and its work may still be running.", { cause: signal.reason });
+			restoreTestRunner();
+		};
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+		onTestFinished(async () => {
+			if (!store.baseline) return;
+			store.cleanupPending = true;
+			try {
+				await cleanupAfterTest(store, store.baseline, unmountWrappers);
+			} catch (error) {
+				store.contamination ??= error;
+				throw error;
+			} finally {
+				store.cleanupPending = false;
+			}
+		});
+	});
+}
+/** @throws When a failed or unfinished cleanup left the environment in an unknown state. */
+function assertNotContaminated(store) {
+	if (store.cleanupPending) store.contamination ??= /* @__PURE__ */ new Error("nuxt-vitest-shared-app: the cleanup after an earlier test did not finish in time.");
+	if (store.contamination) throw new Error("nuxt-vitest-shared-app: this environment is contaminated by an earlier test and cannot run more tests.", { cause: store.contamination });
+}
+//#endregion
+export {};

package/dist/setup-nuxt-id-Bb5_sSMp.mjs

@@ -0,0 +1,9 @@
+//#region src/adapter/setup-nuxt-id.ts
+/**
+* Module id imported by the adapter entry to load the internal `setupNuxt`.
+*
+* The `#` prefix keeps it inlined by the `@nuxt/test-utils` config, so the module runner resolves it through the adapter plugin instead of importing it natively.
+*/
+const SETUP_NUXT_ID = "#nuxt-vitest-shared-app/setup-nuxt";
+//#endregion
+export { SETUP_NUXT_ID as t };

package/dist/startup-error-C4H64PiD.mjs

@@ -0,0 +1,13 @@
+//#region src/runtime/startup-error.ts
+/**
+* Returns the error that Nuxt caught while starting `nuxtApp`, wrapped with the Nuxt error as its cause.
+*
+* Nuxt catches plugin and mount errors during startup, stores them in `payload.error`, and continues with a partially initialized app.
+*/
+function getStartupError(nuxtApp) {
+	const error = nuxtApp.payload.error;
+	if (!error) return void 0;
+	return new Error(`nuxt-vitest-shared-app: Nuxt startup failed: ${error.message}`, { cause: error });
+}
+//#endregion
+export { getStartupError as t };

package/dist/store-Dklvd4X3.mjs

@@ -0,0 +1,32 @@
+//#region src/store.ts
+const STORE_KEY = Symbol.for("nuxt-vitest-shared-app:store");
+/** Whether the current test file runs in the Vitest `nuxt` environment. */
+function isNuxtEnvironment() {
+	return !!globalThis.window?.__NUXT_VITEST_ENVIRONMENT__;
+}
+/**
+* Returns the store bound to the current environment `window`, creating it on first use.
+*
+* @throws Outside the Vitest `nuxt` environment.
+*/
+function getEnvironmentStore() {
+	const win = globalThis.window;
+	if (!win?.__NUXT_VITEST_ENVIRONMENT__) throw new Error("nuxt-vitest-shared-app: not running in the Vitest \"nuxt\" environment.");
+	const existing = win[STORE_KEY];
+	if (existing && existing.window === win && existing.document === win.document) return existing;
+	const store = {
+		window: win,
+		document: win.document,
+		imports: /* @__PURE__ */ new Map(),
+		overrides: /* @__PURE__ */ new Map(),
+		resets: /* @__PURE__ */ new Map(),
+		workerState: /* @__PURE__ */ new Map()
+	};
+	Object.defineProperty(win, STORE_KEY, {
+		value: store,
+		configurable: true
+	});
+	return store;
+}
+//#endregion
+export { isNuxtEnvironment as n, getEnvironmentStore as t };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "nuxt-vitest-shared-app",
+  "version": "0.1.0",
+  "description": "Run Nuxt component tests in Vitest on one Nuxt app per worker, with deterministic per-test cleanup and typed auto-import overrides.",
+  "keywords": [
+    "nuxt",
+    "nuxt-test-utils",
+    "testing",
+    "vitest",
+    "vue"
+  ],
+  "homepage": "https://github.com/IlyaSemenov/nuxt-vitest-shared-app#readme",
+  "bugs": "https://github.com/IlyaSemenov/nuxt-vitest-shared-app/issues",
+  "license": "MIT",
+  "author": "Ilya Semenov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IlyaSemenov/nuxt-vitest-shared-app.git"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "imports": {
+    "#src/*": "./src/*.ts"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./config": "./dist/config.mjs",
+    "./dom": "./dist/dom.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint --fix && oxfmt",
+    "lint:check": "oxlint && oxfmt --check",
+    "prepare": "lefthook install",
+    "prepublishOnly": "bun run build",
+    "test": "vitest run",
+    "test:consumer": "bun run build && bun tests/consumer/run.ts",
+    "types": "tsc && tsc -p tests/tsconfig.json && tsc -p tests/types/tsconfig.route-unregistered.json"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@changesets/cli": "^2.31.1",
+    "@nuxt/test-utils": "4.3.2",
+    "@types/node": "^24.0.0",
+    "@vue/test-utils": "^2.4.8",
+    "@vueuse/core": "^15.0.0",
+    "happy-dom": "^20.14.5",
+    "nuxt": "~4.5.2",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
+    "publint": "^0.3.22",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.2",
+    "vue": "^3.5.43"
+  },
+  "peerDependencies": {
+    "@nuxt/test-utils": "~4.3.0",
+    "@vue/test-utils": "^2.4.2",
+    "nuxt": "^4.4.2",
+    "vitest": "^4.1.0 || ^5.0.0",
+    "vue": "^3.5.30"
+  },
+  "packageManager": "bun@1.4.2"
+}