@stjoseph/prumo 0.5.0 → 0.5.1

package/.prumo-templates/core/testing.md

@@ -15,7 +15,8 @@ Do not mock `EntityManager` or any concrete class from a library.
 
 **In a client, replace the network through the injected transport**: pass a fake `fetch` to `createClient`.
 Do not add a request-mocking library. Test a component that shows an error by rendering it and asserting
-**where** the error appears.
+**where** the error appears. Build every test's `QueryClient` with `createTestQueryClient()` from
+`@test/support/query-client`, never with `new QueryClient()`: the defaults a test needs live there, once.
 
 Measure coverage and report it. Do not block a merge on a coverage threshold.
 
@@ -59,9 +60,18 @@ written in a mobile test is a mistake an assistant will make.
 is **asynchronous** and its matchers need no setup. `expo-secure-store` needs the native Keychain or Keystore,
 which Jest does not have, so a test builds the auth client with an in-memory token store, which is why a form
 asks only for the auth methods it calls. And `jest-expo` leaves the app manifest empty, so `expo-linking` cannot
-know the app's scheme: a test that reaches `Linking.createURL` mocks it with the scheme it expects. A test rendering a `useMutation` builds
-its `QueryClient` with `mutations: { gcTime: Infinity }`: once unmounted, the mutation otherwise starts TanStack
-Query's five-minute garbage-collection timer, and Jest force-exits the worker still waiting on it.
+know the app's scheme: a test that reaches `Linking.createURL` mocks it with the scheme it expects. And a query
+or mutation left without an observer once a test unmounts starts TanStack Query's five-minute garbage-collection
+timer, which Jest's worker waits on until it is force-exited. `createTestQueryClient()` sets `gcTime: Infinity`
+for both, so no timer starts, and `retry: false` for queries, so a failure shows at once: the two defaults TanStack
+Query's testing guide gives. Vitest does not wait on the timer, and `web` uses the same helper so that one rule
+holds in both.
+
+**`web` turns route code splitting off under Vitest**, in `vite.config.ts`. Split, a route's component is a module
+Vite transforms the first time a test renders it, inside the one second a `find*` query waits, and on a loaded CI
+runner the first page of a test file missed it. The wait is not the problem and is not raised: with the transform
+gone the same load passes, and past that load a longer wait fails the same tests anyway. **What it costs:** the
+tests never load a route's lazy chunk; the build and its preview do.
 
 A coverage threshold turns a proxy into a target. Whoever is below writes tests to raise the number rather
 than to check anything; whoever is above stops thinking. With no database mocks a test costs more to write,

package/README.md

@@ -60,7 +60,9 @@ committed, so the first commit is yours and the diff shows everything Prumo wrot
 writes into the current directory instead, which must be empty, and names the project after it. If
 anything fails or is interrupted, Prumo removes what it wrote, so the same command can run again.
 A project cannot be named `api`, `web`, `mobile` or `site`: those are the names its apps take inside
-a workspace.
+a workspace. Nor can it take the name of a package that pnpm's compatibility database extends, such as `ws`:
+pnpm applies the extension to the project's own `package.json` and installs what it adds. Prumo names
+the packages and suggests another name.
 
 Every question also has a flag, which is how CI runs it without a terminal. Outside an interactive
 terminal every question that applies needs its flag, the layout of a single type included: a missing
@@ -138,6 +140,7 @@ Once written, those documents belong to the team. Prumo does not come back and r
 | [`docs/structure.md`](https://github.com/stjosephworks/prumo/blob/main/docs/structure.md) | The `.prumo/` layout, and the rule deciding which areas a project receives |
 | [`docs/document-template.md`](https://github.com/stjosephworks/prumo/blob/main/docs/document-template.md) | The shape every convention document fills |
 | [`docs/maintaining-templates.md`](https://github.com/stjosephworks/prumo/blob/main/docs/maintaining-templates.md) | How a template is changed, and how the change is proved |
+| [`docs/upgrading.md`](https://github.com/stjosephworks/prumo/blob/main/docs/upgrading.md) | What each release changed in the files it generates, and how an existing project carries it over |
 
 ## Releasing
 
@@ -145,6 +148,14 @@ Once written, those documents belong to the team. Prumo does not come back and r
 registry does not have yet, the `publish` job sends it to npm through npm's trusted publishing, with provenance and
 without a token in the repository. Any other push to `main` publishes nothing.
 
+## Upgrading a project
+
+Prumo does not update a project it generated, and there is no `prumo upgrade`. For each release that changed
+the generated files, [`docs/upgrading.md`](https://github.com/stjosephworks/prumo/blob/main/docs/upgrading.md)
+lists what to copy or change and why, and gives one method: generate a reference project with the same answers
+at the old and the new version, and diff the files listed. A file your team has edited is merged by hand, never
+overwritten.
+
 ## Status
 
 Prumo is in beta: every template runs and every generated project is verified in CI, and what a generated project looks like can still change before 1.0.

package/dist/names.js

@@ -1,5 +1,6 @@
 import { readdirSync, statSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
+import { EXTENDED_BY_PNPM } from "./pnpm-extended.js";
 const PROJECT_NAME = /^[a-z][a-z0-9-]*$/;
 // npm refuses a longer package name.
 const MAX_LENGTH = 214;
@@ -15,7 +16,18 @@ export function validateProjectName(name) {
     if (RESERVED.includes(name)) {
         return 'That is the name an app takes inside a workspace; choose another.';
     }
-    return undefined;
+    return extendedByPnpm(name);
+}
+function extendedByPnpm(name) {
+    const added = Object.hasOwn(EXTENDED_BY_PNPM, name) ? EXTENDED_BY_PNPM[name] : undefined;
+    if (added === undefined) {
+        return undefined;
+    }
+    const shown = added.length > 3
+        ? `${added.slice(0, 3).join(', ')} and ${added.length - 3} more`
+        : added.join(', ');
+    return (`pnpm extends the npm package "${name}" with ${shown}, and would install them into a project of that name. ` +
+        `Choose another, such as "${name}-app".`);
 }
 // Why a directory cannot receive a project, or undefined when it can: it does not exist yet, or it is empty.
 export function targetProblem(target) {

package/dist/pnpm-extended.js

@@ -0,0 +1,159 @@
+// pnpm applies a compatibility database, @yarnpkg/extensions, to every manifest it reads: the registry's packages and
+// the project's own package.json alike. An entry matches by name and version range, and the template version 0.0.1
+// falls inside ranges like `ws@<7.2.1`. A project carrying one of these names therefore gains the dependencies the
+// entry adds, installed into its root, and a package among them with a build script stops `pnpm install` with
+// ERR_PNPM_IGNORED_BUILDS. Each name maps to the packages it would add.
+//
+// Derived from @yarnpkg/extensions, pinned in devDependencies, by test/names.spec.ts, which fails when this list and
+// the database part ways. Only names a project can take are kept, and only entries that add a package: one that sets
+// nothing but peerDependenciesMeta changes no install.
+export const EXTENDED_BY_PNPM = {
+    'apollo-upload-client': ['graphql'],
+    'auto-relay': ['reflect-metadata'],
+    'babel-plugin-graphql-tag': ['graphql'],
+    'babel-plugin-remove-graphql-queries': ['@babel/runtime', '@babel/types', 'gatsby-core-utils'],
+    'babel-plugin-transform-typescript-metadata': ['@babel/core', '@babel/traverse'],
+    'babel-preset-gatsby-package': ['@babel/runtime'],
+    'bin-links': ['mkdirp-infer-owner'],
+    'cacheable-lookup': ['@types/keyv'],
+    'clipanion-v3-codemod': ['jscodeshift'],
+    'connect-mongo': ['express-session'],
+    consolidate: [
+        'arc-templates',
+        'atpl',
+        'babel-core',
+        'bracket-template',
+        'coffee-script',
+        'dot',
+        'dust',
+        'dustjs-helpers',
+        'dustjs-linkedin',
+        'eco',
+        'ect',
+        'ejs',
+        'haml-coffee',
+        'hamlet',
+        'hamljs',
+        'handlebars',
+        'hogan.js',
+        'htmling',
+        'jade',
+        'jazz',
+        'jqtpl',
+        'just',
+        'liquid-node',
+        'liquor',
+        'lodash',
+        'marko',
+        'mote',
+        'mustache',
+        'nunjucks',
+        'plates',
+        'pug',
+        'qejs',
+        'ractive',
+        'razor-tmpl',
+        'react',
+        'react-dom',
+        'slm',
+        'squirrelly',
+        'swig',
+        'swig-templates',
+        'teacup',
+        'templayed',
+        'then-jade',
+        'then-pug',
+        'tinyliquid',
+        'toffee',
+        'twig',
+        'twing',
+        'underscore',
+        'vash',
+        'velocityjs',
+        'walrus',
+        'whiskers',
+    ],
+    'cordova-ios': ['underscore'],
+    'cordova-lib': ['underscore'],
+    'create-gatsby': ['@babel/runtime'],
+    'elm-webpack-loader': ['temp'],
+    'eslint-import-resolver-vite': ['debug', 'resolve'],
+    fdir: ['picomatch'],
+    'fork-ts-checker-webpack-plugin': ['eslint', 'typescript', 'vue-template-compiler', 'webpack'],
+    'gatsby-admin': ['@babel/runtime'],
+    'gatsby-cli': ['@babel/runtime'],
+    'gatsby-core-utils': ['@babel/runtime', 'got'],
+    'gatsby-design-tokens': ['@babel/runtime'],
+    'gatsby-legacy-polyfills': ['@babel/runtime'],
+    'gatsby-plugin-benchmark-reporting': ['@babel/runtime'],
+    'gatsby-plugin-favicon': ['webpack'],
+    'gatsby-plugin-gatsby-cloud': ['gatsby-core-utils', 'webpack'],
+    'gatsby-plugin-graphql-config': ['@babel/runtime'],
+    'gatsby-plugin-i18n': ['ramda'],
+    'gatsby-plugin-image': ['@babel/runtime'],
+    'gatsby-plugin-mdx': ['@babel/runtime', 'mkdirp'],
+    'gatsby-plugin-netlify-cms': ['@babel/runtime'],
+    'gatsby-plugin-no-sourcemaps': ['@babel/runtime'],
+    'gatsby-plugin-page-creator': ['@babel/runtime', 'fs-extra'],
+    'gatsby-plugin-preact': ['@babel/runtime'],
+    'gatsby-plugin-preload-fonts': ['@babel/runtime'],
+    'gatsby-plugin-schema-snapshot': ['@babel/runtime'],
+    'gatsby-plugin-sharp': ['debug'],
+    'gatsby-plugin-styletron': ['@babel/runtime'],
+    'gatsby-plugin-subfont': ['@babel/runtime'],
+    'gatsby-plugin-utils': ['@babel/runtime', 'fastq', 'graphql'],
+    'gatsby-react-router-scroll': ['prop-types'],
+    'gatsby-recipes': ['@babel/runtime'],
+    'gatsby-remark-prismjs': ['lodash'],
+    'gatsby-source-apiserver': ['babel-polyfill'],
+    'gatsby-source-shopify': ['@babel/runtime'],
+    'gatsby-source-wikipedia': ['@babel/runtime'],
+    'gatsby-transformer-screenshot': ['@babel/runtime'],
+    'gatsby-worker': ['@babel/runtime'],
+    'git-node-fs': ['js-git'],
+    got: ['@types/keyv', '@types/responselike'],
+    'http-link-dataloader': ['graphql'],
+    'ink-select-input': ['react'],
+    'jest-vue-preprocessor': ['@babel/core', '@babel/template', 'pug'],
+    'jss-plugin-rule-value-function': ['tiny-warning'],
+    mqtt: ['duplexify'],
+    'query-ast': ['lodash'],
+    'rc-animate': ['react', 'react-dom'],
+    'react-bootstrap-table2-paginator': ['classnames'],
+    'react-color': ['react'],
+    'react-dev-utils': ['typescript', 'webpack'],
+    'react-draggable': ['react', 'react-dom'],
+    'react-github-btn': ['react'],
+    'react-instantsearch-core': ['algoliasearch'],
+    'react-instantsearch-dom': ['react-fast-compare'],
+    'react-live': ['react', 'react-dom'],
+    'react-portal': ['react-dom'],
+    'react-rnd': ['react', 'react-dom'],
+    'react-scripts': ['eslint', 'react'],
+    reactcss: ['react'],
+    rebass: ['react'],
+    'redux-persist': ['react'],
+    'redux-thunk': ['redux'],
+    'rollup-plugin-polyfill-node': ['rollup'],
+    'scss-parser': ['lodash'],
+    skypack: ['tar'],
+    snowpack: ['magic-string'],
+    terser: ['acorn'],
+    testcafe: ['@babel/plugin-transform-for-of', '@babel/runtime'],
+    'testcafe-legacy-api': ['read-file-relative', 'testcafe-hammerhead'],
+    'typescript-language-server': ['vscode-jsonrpc', 'vscode-languageserver-protocol'],
+    unified: ['@types/unist'],
+    'unplugin-vue2-script-setup': ['@vue/composition-api', '@vue/runtime-dom'],
+    'vite-plugin-vuetify': ['vue'],
+    'volar-service-typescript': ['typescript'],
+    'volar-service-typescript-twoslash-queries': ['typescript'],
+    'vue-cli-plugin-vuetify': ['null-loader', 'semver'],
+    'vue-i18n': ['vue'],
+    'vue-loader': ['@vue/compiler-sfc', 'webpack'],
+    'vue-router': ['vue'],
+    'vue-template-babel-compiler': ['vue-template-compiler'],
+    'webpack-plugin-vuetify': ['vue'],
+    'winston-transport': ['logform'],
+    ws: ['bufferutil', 'utf-8-validate'],
+    xo: ['webpack'],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
   "keywords": [
     "scaffolding",
@@ -48,6 +48,9 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.13",
     "@types/node": "24.13.4",
+    "@types/semver": "7.8.0",
+    "@yarnpkg/extensions": "2.0.7",
+    "semver": "7.8.5",
     "typescript": "6.0.3",
     "vitest": "4.1.11"
   },

package/templates/mobile/test/features/auth/authenticated-layout.spec.tsx

@@ -1,6 +1,7 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
 import { memoryTokenStore } from '@test/support/memory-token-store'
+import { createTestQueryClient } from '@test/support/query-client'
 import { renderRouter, screen } from 'expo-router/testing-library'
 import type { ReactNode } from 'react'
 import { Text } from 'react-native'
@@ -23,7 +24,7 @@ async function renderAt(getSession: () => Response | Promise<Response>) {
     tokens: memoryTokenStore(TOKENS),
   })
   const clients = { auth, api: createClient({ baseUrl: API_URL, fetch: auth.fetch }) }
-  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  const queryClient = createTestQueryClient()
 
   function Providers({ children }: { children: ReactNode }) {
     return (

package/templates/mobile/test/features/auth/email-flows.spec.tsx

@@ -1,6 +1,7 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
 import { memoryTokenStore } from '@test/support/memory-token-store'
+import { createTestQueryClient } from '@test/support/query-client'
 import { userEvent } from '@testing-library/react-native'
 import { renderRouter, screen } from 'expo-router/testing-library'
 import type { ReactNode } from 'react'
@@ -18,7 +19,7 @@ async function renderAt(initialUrl: string, routes: Parameters<typeof fakeTransp
   const transport = fakeTransport(routes)
   const auth = createAuthClient({ baseUrl: API_URL, fetch: transport, tokens: memoryTokenStore() })
   const clients = { auth, api: createClient({ baseUrl: API_URL, fetch: auth.fetch }) }
-  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  const queryClient = createTestQueryClient()
 
   function Providers({ children }: { children: ReactNode }) {
     return (

package/templates/mobile/test/features/auth/sign-in-form.spec.tsx

@@ -1,6 +1,7 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
 import { memoryTokenStore } from '@test/support/memory-token-store'
+import { createTestQueryClient } from '@test/support/query-client'
 import { render, screen, userEvent } from '@testing-library/react-native'
 import { createAuthClient } from '@/api-contract'
 import { SignInForm } from '@/features/auth/sign-in-form'
@@ -23,7 +24,7 @@ describe('SignInForm', () => {
     const user = userEvent.setup()
 
     await render(
-      <QueryClientProvider client={new QueryClient()}>
+      <QueryClientProvider client={createTestQueryClient()}>
         <SignInForm auth={auth} onSignedIn={onSignedIn} />
       </QueryClientProvider>,
     )

package/templates/mobile/test/features/auth/sign-out-button.spec.tsx

@@ -1,6 +1,7 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport } from '@test/support/fake-transport'
 import { memoryTokenStore } from '@test/support/memory-token-store'
+import { createTestQueryClient } from '@test/support/query-client'
 import { render, screen, userEvent, waitFor } from '@testing-library/react-native'
 import { createAuthClient } from '@/api-contract'
 import { SignOutButton } from '@/features/auth/sign-out-button'
@@ -10,7 +11,7 @@ import { clearUserData } from '@/features/storage/storage'
 jest.mock('@/features/storage/storage', () => ({ clearUserData: jest.fn() }))
 
 async function signOutWith(signOut: () => Response | Promise<Response>) {
-  const queryClient = new QueryClient()
+  const queryClient = createTestQueryClient()
   const onSignedOut = jest.fn()
   const auth = createAuthClient({
     baseUrl: API_URL,

package/templates/mobile/test/features/auth/social-buttons.spec.tsx

@@ -1,6 +1,7 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
 import { memoryTokenStore } from '@test/support/memory-token-store'
+import { createTestQueryClient } from '@test/support/query-client'
 import { render, screen, userEvent, waitFor } from '@testing-library/react-native'
 import * as WebBrowser from 'expo-web-browser'
 import { createAuthClient } from '@/api-contract'
@@ -28,7 +29,7 @@ async function renderButtons(exchange: () => Response) {
   })
 
   await render(
-    <QueryClientProvider client={new QueryClient()}>
+    <QueryClientProvider client={createTestQueryClient()}>
       <SocialButtons auth={auth} onSignedIn={onSignedIn} />
     </QueryClientProvider>,
   )

package/templates/mobile/test/features/profile/profile-form.spec.tsx

@@ -1,5 +1,6 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
+import { createTestQueryClient } from '@test/support/query-client'
 import { render, screen, userEvent, within } from '@testing-library/react-native'
 import { createClient, type Profile } from '@/api-contract'
 import { ProfileForm } from '@/features/profile/profile-form'
@@ -36,9 +37,7 @@ describe('ProfileForm', () => {
       }),
     })
 
-    // A mutation left without an observer starts a five-minute garbage-collection timer, and Jest's worker would wait
-    // it out. Infinity schedules none, as TanStack Query's testing guide advises.
-    const queryClient = new QueryClient({ defaultOptions: { mutations: { gcTime: Infinity } } })
+    const queryClient = createTestQueryClient()
 
     await render(
       <QueryClientProvider client={queryClient}>

package/templates/mobile/test/support/query-client.ts

@@ -0,0 +1,14 @@
+import { QueryClient } from '@tanstack/react-query'
+
+// Every test builds its QueryClient here, with the defaults TanStack Query's testing guide gives. A failed query
+// fails at once instead of retrying three times with backoff. And gcTime Infinity schedules no garbage-collection
+// timer: once a test unmounts, a query or mutation left without an observer would otherwise start a real five-minute
+// setTimeout, and Jest's worker waits on it until it is force-exited.
+export function createTestQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, gcTime: Infinity },
+      mutations: { gcTime: Infinity },
+    },
+  })
+}

package/templates/web/test/features/oauth/consent-form.spec.tsx

@@ -1,5 +1,6 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
+import { createTestQueryClient } from '@test/support/query-client'
 import { renderApp } from '@test/support/render-app'
 import { render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
@@ -26,7 +27,7 @@ function renderForm(routes: Parameters<typeof fakeTransport>[0]) {
   const auth = createAuthClient({ baseUrl: API_URL, fetch: fakeTransport(routes) })
 
   render(
-    <QueryClientProvider client={new QueryClient()}>
+    <QueryClientProvider client={createTestQueryClient()}>
       <ConsentForm auth={auth} requestId={REQUEST} leave={leave} />
     </QueryClientProvider>,
   )

package/templates/web/test/features/profile/profile-form.spec.tsx

@@ -1,5 +1,6 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
+import { createTestQueryClient } from '@test/support/query-client'
 import { render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { describe, expect, it } from 'vitest'
@@ -40,7 +41,7 @@ describe('ProfileForm', () => {
     })
 
     render(
-      <QueryClientProvider client={new QueryClient()}>
+      <QueryClientProvider client={createTestQueryClient()}>
         <ProfileForm api={api} profile={profile} />
       </QueryClientProvider>,
     )

package/templates/web/test/support/query-client.ts

@@ -0,0 +1,14 @@
+import { QueryClient } from '@tanstack/react-query'
+
+// Every test builds its QueryClient here, with the defaults TanStack Query's testing guide gives. A failed query
+// fails at once instead of retrying three times with backoff. And gcTime Infinity schedules no garbage-collection
+// timer: once a test unmounts, a query or mutation left without an observer would otherwise start a real five-minute
+// setTimeout, and Jest's worker waits on it until it is force-exited.
+export function createTestQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, gcTime: Infinity },
+      mutations: { gcTime: Infinity },
+    },
+  })
+}

package/templates/web/test/support/render-app.tsx

@@ -1,6 +1,6 @@
-import { QueryClient } from '@tanstack/react-query'
 import { createMemoryHistory } from '@tanstack/react-router'
 import { API_URL } from '@test/support/fake-transport'
+import { createTestQueryClient } from '@test/support/query-client'
 import { render } from '@testing-library/react'
 import { createAuthClient, createClient, type Transport } from '@/api-contract'
 import { App } from '@/app'
@@ -8,7 +8,7 @@ import { App } from '@/app'
 export function renderApp(path: string, transport: Transport) {
   const auth = createAuthClient({ baseUrl: API_URL, fetch: transport })
   const context = {
-    queryClient: new QueryClient({ defaultOptions: { queries: { retry: false } } }),
+    queryClient: createTestQueryClient(),
     api: createClient({ baseUrl: API_URL, fetch: auth.fetch }),
     auth,
   }

package/templates/web/vite.config.ts

@@ -3,8 +3,15 @@ import { tanstackRouter } from '@tanstack/router-plugin/vite'
 import react from '@vitejs/plugin-react'
 import { defineConfig } from 'vitest/config'
 
-export default defineConfig({
-  plugins: [tanstackRouter({ target: 'react', autoCodeSplitting: true }), react(), tailwindcss()],
+// Under Vitest (mode `test`) every route is imported with the route tree. Split, each route's component is a
+// virtual module Vite transforms the first time a test renders it, inside the one second Testing Library waits for
+// the page, and on a loaded machine that transform alone outlasted the wait.
+export default defineConfig(({ mode }) => ({
+  plugins: [
+    tanstackRouter({ target: 'react', autoCodeSplitting: mode !== 'test' }),
+    react(),
+    tailwindcss(),
+  ],
   resolve: {
     alias: { '@': `${import.meta.dirname}/src`, '@test': `${import.meta.dirname}/test` },
   },
@@ -15,4 +22,4 @@ export default defineConfig({
     setupFiles: ['./test/support/setup.ts'],
     coverage: { provider: 'v8', include: ['src/**'] },
   },
-})
+}))