workspaces & projects

23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Project extends option

Inline projects inherit all options from the root-level configuration when 'extends' is true (default since Vitest 5.0). Set 'extends: false' to ignore root options. The 'extends' option also accepts a string path to another config file to inherit from that file instead.

Define projects with glob patterns

Projects are defined in the root Vitest config using the projects array. You can use glob patterns like 'packages/*' to match folders, and negation patterns like '!packages/excluded' to exclude specific folders.

Valid project config file names

Project configuration files must follow these naming patterns: start with 'vitest.config' or 'vite.config' (e.g., 'vitest.config.unit.ts'), or match 'vitest.<name>.config.*' / 'vite.<name>.config.*' where <name> contains letters, numbers, underscore, or dash. Valid examples include vitest.config.ts, vite.config.js, vitest.unit.config.ts, vitest.e2e-node.config.ts, vite.e2e.config.js, vitest.config.unit.js, vite.config.e2e.js.

Nested glob pattern brackets for project exclusion

Use bracket patterns like 'packages/!(business)' to match every folder except the specified one. This allows defining nested structures where parent folders are excluded but their subfolders can be projects. For example, 'packages/!(business)' and 'packages/business/*' will create projects at packages/a, packages/b, packages/business/c, and packages/business/d, but not packages/business itself.

Inline project configuration inheritance

Inline projects inherit options from the root config file by default. This behavior is controlled by the 'extends' option, which is enabled by default since Vitest 5.0. The extends option can also accept a path to another config file to inherit from a different config instead of the root.

Project configuration inheritance rules

When projects inherit from a config, all options are merged with the project's own options. Arrays like 'setupFiles' are concatenated, not overridden. Special inheritance rules: 'name' and 'projects' are never inherited, 'globalSetup' is not inherited from the root config (only from non-root config files), and the project's own 'tags' replace the inherited array instead of merging.

Project configuration name requirement

All projects must have unique names; otherwise Vitest throws an error. If a name is not provided in inline configuration, Vitest assigns a number. For projects defined with glob syntax, Vitest defaults to using the 'name' property in the nearest package.json file, or the folder name if no package.json exists.

Project configuration with defineProject

For better type safety in project configuration files, use the 'defineProject' method instead of 'defineConfig'. Projects do not support all configuration properties, and defineProject provides type checking to prevent errors.

Root config not treated as project

Vitest does not treat the root vitest.config file as a project unless explicitly specified. The root configuration only influences global options such as 'reporters' and 'coverage'. However, Vitest always runs certain plugin hooks like 'apply', 'config', 'configResolved', and 'configureServer' from the root config file.

Inline project name styling

When defining inline projects, the 'name' property can be a string or an object with properties 'label' and 'color' to customize the appearance of the project name label.

Nested projects configuration

A project referenced as a config file or directory can declare 'projects' itself. Such a config behaves like the root config: it doesn't run tests on its own, only provides the projects that do. This allows referencing a workspace that already defines its own projects.

Nested project naming

The names of nested projects are prefixed with the name of the config that declares them. For example, a config named 'app' with nested projects 'unit' and 'e2e' creates projects named 'app (unit)' and 'app (e2e)'. The '--project' filter matches the prefix as well: '--project app' runs every project of the app config.

Nested projects inheritance

Nested projects work the same way as projects defined in the root config: inline configurations extend the config that declares them (not the root one), 'extends' paths are resolved relative to the declaring config, and the declaring config's own 'globalSetup' is inherited by extending projects.

Nested projects must be in config files

Only config files can define nested projects. The 'projects' option inside an inline configuration is not supported.

Project configuration unsupported options

Some configuration options are not allowed in a project config: 'coverage' (coverage is done for the whole process), 'reporters' (only root-level reporters are supported), 'resolveSnapshotPath' (only root-level resolver is respected), 'attachmentsDir' (attachments are stored in one root-level directory shared by all projects), and all other options that don't affect test runners.

Merge config files with mergeConfig function

Use the 'mergeConfig' function imported from 'vitest/config' to merge a shared config file with a project config. This is useful for projects referenced as config files or directories that don't inherit from the root config. Example: mergeConfig(configShared, defineProject({test: {environment: 'jsdom'}}))

Config file projects don't inherit from root

Projects referenced as config files or directories do not inherit any options from the root config. You must create a shared config file and merge it with the project config yourself using mergeConfig.

Feature name: workspace replaced by projects

The 'workspace' feature is deprecated since Vitest 3.2 and replaced with the 'projects' configuration. They are functionally the same.

project CLI flag

The project CLI flag is `-p` or `--project <name>` and specifies the name of the project to run when using Vitest workspace feature. This can be repeated for multiple projects: `--project=1 --project=2`. You can also filter projects using wildcards like `--project=packages*`, and exclude projects with `--project=!pattern`. A project runs if it matches no negated pattern and matches at least one regular pattern.

Inline projects inherit root config by default

In Vitest 5.0, the extends option for inline projects defined in test.projects defaults to true. Every project defined as an inline configuration inherits all options from the root configuration, including Vite options like plugins or resolve.alias. Arrays are merged, not overridden. Set extends: false in the project configuration if you need the previous behavior.

Referenced config files can define their own projects

A config file referenced in test.projects that declares projects itself now provides the nested projects it declares instead of running tests as a single project. In Vitest 4, the projects field of a referenced config was silently ignored. Check that your project configs don't carry a projects field unknowingly.

Inline projects share Vite server by default

In Vitest 5.0, inline projects that don't modify the Vite config now reuse the Vite server of the config that declares them instead of creating a new server per project. This is controlled by the new sharedViteServer option, which is enabled by default. When the server is shared, the declaring config file is executed once instead of once per project, so its plugins are instantiated once.

sharedViteServer option controls server sharing

The sharedViteServer option (default: true) controls whether inline projects share the Vite server. Set sharedViteServer: false to give each inline project its own server, useful if a plugin relies on being re-instantiated per project.

Give your agent this brain