[Proposal] Viteless Vitest (Engine-Agnostic API)

[sheremet-va]

Note

The original proposal referred to the new contract as a "framework". After some discussion, the team decided to rename it to "engine" to avoid confusion with frontend frameworks. Vitest already supports many frameworks built on top of Vite; this proposal focuses on supporting more ways to run code, including non-Vite frameworks and no-bundler approaches.

Vitest's tight coupling with Vite has historically been one of its greatest strengths: instant HMR, a unified config, and a shared plugin ecosystem made it the natural choice for projects already invested in the Vite toolchain. That same coupling has also become its most significant constraint. As Vitest matures into a general-purpose test runner, the assumption that every consumer wants (or can afford) a full Vite pipeline in their test process is increasingly hard to justify.

A test runner's job is to execute tests reliably and quickly; everything else, including the transformation pipeline, module graph, and dev server, exists to support that. Decoupling these concerns would let Vitest meet users where they are, whether that's a Webpack-based monorepo, a pure Node service, a Deno project, or a Bun-first codebase.

Summary

Add an --engine flag that points to a package responsible for adapting Vitest to a specific build/runtime environment. The engine package exports a set of instructions (classes/exports/utilities) that Vitest's core uses through a stable contract, and it owns config resolution for that environment. Vite becomes one such engine, shipped as the default. Other engines (esbuild, rsbuild, Rolldown, Oxc, native Node, Deno, Bun, Webpack) can be written independently.

Motivation

Vitest's runner, expectations, snapshotting, mocking, reporters, and watch UX already do not rely on any of the Vite features. The coupling to Vite lives at the edges: transforming source files, resolving modules, hot-reloading, serving assets, and the config pipeline itself, which today is vite.config.ts with a test field. A real extension point would let users pick a different transformer or runtime without forking the runner, and would let the Vitest team treat Vite as one of several integrations instead of the only one.

Prior Art

This proposal is inspired by unplugin project, which lets a single plugin work across many build tools by writing it against a shared contract. Vitest's contract goes the other way (one host plugging into many backends rather than one plugin plugging into many hosts), but the basic idea of a small, stable interface between core and adapter packages is the same.

Proposal

An engine is a regular npm package that the user references by name on the command line:

vitest --engine @vitest/engine-node
vitest --engine @vitest/engine-vite       # default
vitest --engine @web-infra-dev/vitest-engine-rsbuild

The flag is CLI-only on purpose. The engine is what decides what a config file looks like and how it gets loaded. So the framework choice has to come from one of: the --engine flag, an environment variable, or a small top-level marker file that Vitest reads before anything else. The exact discovery rules will be settled in implementation.

The package's main export could be a factory that returns a set of instructions Vitest's core uses to:

• resolve and load the user's config from whatever format the engine picks (currently the idea is for vitest to just pass down the path to the config file)
• resolve and transform modules at runtime
• watch the file system and expose ways to invalidate files
• expose any engine-specific options to user code
• tear down resources cleanly
• parses a Javascript file for static analysis

The exact shape of these instructions (which functions, properties, classes, exports) is left open in this RFC on purpose. It will be pinned down in a follow-up once we have at least two non-Vite implementations to compare against.

Vitest's startup becomes: read the --engine flag, load that package, ask for its instructions, hand config resolution off to it, and then drive the rest of the runner against the returned contract. Everything not covered by the contract (the test runner, expect, mocking, snapshots, reporters, the UI, coverage) keeps working unchanged.

Migration

No breaking changes for existing users. Omitting --engine resolves to @vitest/engine-vite, which preserves today's behavior, including reading vite.config.ts / vitest.config.ts and accepting the test field. The current viteModuleRunner: false mode becomes the prototype for a @vitest/engine-node adapter and is the obvious first non-Vite engine to ship.

Open Questions

• Exact shape of the engine contract (deferred to a follow-up RFC, informed by two or more real adapters).
• How to specify --engine outside the CLI: env var, marker file, package.json field, or some mix, given that a config file can't be the source of truth.
• How engine-specific options are exposed to user config without leaking engine types into Vitest's core types.
• Whether reporters, coverage providers, and browser mode need to declare engine compatibility, or whether the contract is rich enough that they don't have to care.

Non-Goals

• Replacing Vite as the recommended default.
• Defining a universal plugin format across engines.
• Supporting every build tool on day one. Shipping the flag with one alternative engine is enough to validate the contract.

[mindplay-dk]

Would there be support for native Node.JS as a "framework"? This would actually be the main attraction for me - using vitest with native TS support and native loaders/resolvers in Node.

[sheremet-va]

Yes, this is the main motivation of this proposal. The "framework" wording perhaps is wrong here on the implementation level, it will probably be named differently.

You can also already use Vitest with native TS loader via viteModuleRunner: false.

[mindplay-dk]

so what would be the practical difference (in the Node.JS case) versus using the flag that's already supported?

[sheremet-va]

Vite package (and its dependencies like rolldown) won't be installed. viteModuleRunner: false still requires Vite for watcher/module graph/parsing support at the moment.

[seanogdev]

What would this mean for cross-framework setups? Right now we have project-level configs (previously workspaces) which would then be rolled up into the root workspace but this feels like an intentional departure from this approach?

[sheremet-va]

It's a good question I don't have the answer to. The config resolution itself should be defined by the top level "framework" (engine), including the project configuration. Maybe there is a possible mixed approach where some APIs could be project specific, so e.g., you use the top level "node" framework to load the config, but a project could use a "vite" framework to define itself. Maybe it should be possible to process the config based on some flag (project.engine/project.framework) - so we read the file first and then decide on how that part should be processed. I am not sure.

[sheremet-va]

There has been some confusion because of the naming of the proposal. The framework in the name is a more generic term, not the frontend framework (like sveltekit or nuxt which are supported already because they use vite). The proposal is about a generic interface that Vitest could understand without relying on vite.

After some discussion we think that engine describes the concept better, so I am updating the naming in the original message.

[lishaduck]

I'm reading this is a combined proposal to solve #9664 (comment) and #9501 (comment). If so, is there a path in this proposal for people to compose engines together? I don't want to get rid of Vite's bundling, etc, because my code ends up bundled; but I do want to run the tests on a different runtime (Deno) in addition to Node.js. The way I read this proposal, it's locking people into any one runtime + any one bundler instead of many runtimes + any one bundler (e.g. #10271 (comment)).

Is there a way in this proposal to keep Vite while running on (multiple) non-Node.js runtimes, or is that a separate discussion?

[sheremet-va]

I think it is a separate discussion. You can already define a custom pool implementation to run code in any environment as long as it reports back to the main process