@xmachines/shared 1.0.0-beta.5 → 1.0.0-beta.7

package/README.md

@@ -6,7 +6,7 @@ Centralized config enabling composite build system with project references.
 
 ## Overview
 
-`@xmachines/shared` provides shared configuration files for all XMachines packages, establishing consistent TypeScript compilation, linting rules, and code formatting across the monorepo.
+`@xmachines/shared` provides shared configuration files for all XMachines packages, establishing consistent TypeScript compilation, linting rules, formatting, and Vitest setup across the monorepo.
 
 **Enhancement:** Added TypeScript composite build system with project references enabling correct build order, incremental compilation, and IDE source navigation via declaration maps.
 
@@ -21,6 +21,10 @@ Configuration files in `config/` directory:
 - **`config/tsconfig.json`** - TypeScript compiler settings with composite project support
 - **`config/oxlint.json`** - Linting rules and plugins
 - **`config/oxfmt.json`** - Code formatting preferences
+- **`config/vitest.ts`** - Shared Vitest config helper (`defineXmVitestConfig`)
+- **`config/vitest.setup.ts`** - Shared cross-runtime Vitest setup (polyfills, jest-dom matchers)
+- **`config/vitest.node.setup.ts`** - Node-only Vitest setup (Node runtime/version preflight)
+- **`config/vite-aliases.ts`** - Workspace alias mapping for `@xmachines/*`
 
 ## Usage
 
@@ -74,6 +78,93 @@ Configuration files in `config/` directory:
 }
 ```
 
+### Vite Alias Configuration
+
+Use the shared alias helper in Vite and Vitest configs so workspace packages resolve to source files without requiring `dist/` builds:
+
+```ts
+import { defineConfig } from "vite";
+import { xmAliases } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({
+	resolve: {
+		alias: xmAliases(import.meta.url),
+	},
+});
+```
+
+This is especially important after `npm run clean`, where package `exports` targeting `dist/` are temporarily unavailable until rebuild.
+
+### Vitest Configuration
+
+Use the shared helper so package configs inherit common aliasing and runtime setup:
+
+```ts
+import { defineXmVitestConfig } from "@xmachines/shared/vitest";
+
+export default defineXmVitestConfig(import.meta.url, {
+	test: {
+		environment: "node",
+		include: ["test/**/*.test.ts"],
+		exclude: ["node_modules/**"],
+	},
+});
+```
+
+**Browser project example:**
+
+```ts
+import { defineXmVitestConfig } from "@xmachines/shared/vitest";
+import { playwright } from "@vitest/browser-playwright";
+
+export default defineXmVitestConfig(import.meta.url, {
+	test: {
+		name: "my-demo-browser",
+		browser: {
+			enabled: true,
+			provider: playwright(),
+			headless: true,
+			instances: [{ browser: "chromium" }],
+		},
+		include: ["test/browser/**/*.browser.test.ts"],
+		exclude: ["node_modules/**"],
+	},
+});
+```
+
+What the shared Vitest layer provides automatically:
+
+- `resolve.alias` for all `@xmachines/*` packages via `xmAliases(...)`
+- Shared setup injection (`config/vitest.setup.ts`) unless already present
+- Node setup injection (`config/vitest.node.setup.ts`) for non-browser projects
+- Runtime preflight:
+    - Node.js runtime/version check (`>=22`) in node setup
+    - `urlpattern-polyfill` load in shared setup
+    - `URLPattern` availability assertion in shared setup
+- DOM matcher extension via `@testing-library/jest-dom/vitest`
+
+### Vitest Setup Injection Rules
+
+`defineXmVitestConfig(...)` applies setup files predictably:
+
+1. It normalizes `test.setupFiles` into an array.
+2. It injects `config/vitest.setup.ts` if missing.
+3. It injects `config/vitest.node.setup.ts` only when `test.browser.enabled !== true`.
+4. It avoids duplicates by checking filenames (suffix match).
+5. Injected setup files run before user-provided setup files.
+
+This gives a safe default for Node package tests while keeping browser projects compatible.
+
+### Vitest Exports
+
+`@xmachines/shared` exports these Vitest entry points:
+
+- `@xmachines/shared/vitest` → `config/vitest.ts`
+- `@xmachines/shared/vitest-setup` → `config/vitest.setup.ts`
+- `@xmachines/shared/vitest-node-setup` → `config/vitest.node.setup.ts`
+
+Use `@xmachines/shared/vitest` for package config files; direct setup exports are for advanced customization only.
+
 ## Configuration Details
 
 ### TypeScript (`config/tsconfig.json`)
@@ -107,6 +198,48 @@ import { foo } from "./bar"; // ❌ Wrong
 - **Style:** Double quotes, semicolons, trailing commas
 - **Final Newline:** Always insert
 
+### Vitest (`config/vitest.ts`, `config/vitest.setup.ts`, `config/vitest.node.setup.ts`)
+
+- **Helper API:** `defineXmVitestConfig(importMetaUrl, overrides)` merges shared defaults with package-specific Vitest config
+- **Auto-aliasing:** `resolve.alias` is wired to `xmAliases(importMetaUrl)` so workspace packages resolve to source
+- **Cross-runtime setup (`config/vitest.setup.ts`):**
+    - loads `urlpattern-polyfill`
+    - extends `expect` with `@testing-library/jest-dom/vitest`
+    - asserts `URLPattern` availability
+- **Node-only setup (`config/vitest.node.setup.ts`):**
+    - asserts Node runtime (`process.release.name === "node"`)
+    - enforces Node version `>=22`
+- **Browser behavior:** Browser projects do not receive node-only setup injection
+- **Override model:** Package-level config still controls test environment, includes/excludes, plugins, coverage, and browser provider
+
+### Vite Aliases (`config/vite-aliases.ts`)
+
+- **Helper API:** `xmAliases(importMetaUrl)` returns a complete `resolve.alias` map for all `@xmachines/*` workspace packages
+- **Root discovery:** Walks upward from `import.meta.url` until it finds the workspace root (`package.json` with `workspaces`)
+- **Source-first resolution:** Maps package imports to `packages/*/src/index.ts` for fast local dev without prebuild
+- **Extra aliases:** Includes `@xmachines/play-router-shared` and `@xmachines/play-router-shared/index.css` for demo shared assets
+- **Primary use cases:** `vite.config.ts`, `vitest` browser configs, and any local tooling relying on Vite resolver semantics
+
+### Vite Alias Troubleshooting
+
+- **`[xmAliases] Could not find workspace root`**
+    - Ensure `xmAliases` receives `import.meta.url` from the calling config file.
+    - Ensure the config file lives somewhere under the monorepo root.
+- **Workspace package import resolves to missing `dist/` files**
+    - Ensure config includes `resolve.alias: xmAliases(import.meta.url)`.
+    - Re-run after cleaning caches when lockfile/deps changed.
+
+### Vitest Troubleshooting
+
+- **`URLPattern is unavailable after setup`**
+    - Ensure `test.setupFiles` is not replacing shared setup unexpectedly.
+    - Ensure config is created via `defineXmVitestConfig(...)`.
+- **`Node runtime is required for this Vitest configuration`**
+    - This indicates node-only setup loaded in a browser project.
+    - Set `test.browser.enabled: true` in that project config.
+- **Workspace import resolution failures (e.g. `@xmachines/play-signals`)**
+    - Confirm config uses `defineXmVitestConfig(import.meta.url, ...)` so aliases are injected.
+
 ## TypeScript Composite Build System
 
 This package introduced TypeScript project references for proper build-order management in the monorepo.
@@ -228,11 +361,9 @@ To add a new shared configuration (e.g., for Jest, Vitest, etc.):
 3. Document in this README with usage examples
 4. Note whether the tool supports package exports or requires relative paths
 
-## Links
-
-- [XMachines Monorepo](../../README.md)
-- Agent Guidelines: `AGENTS.md`
-
 ## License
 
-MIT
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.

package/config/vite-aliases.ts

@@ -19,9 +19,6 @@ import { fileURLToPath } from "url";
  *
  * @param importMetaUrl - Pass `import.meta.url` from the calling config file.
  *   Used to locate the workspace root (the directory containing `packages/`).
- * @internal
- * @hidden
- * @ignore
  */
 export function xmAliases(importMetaUrl: string): Record<string, string> {
 	const configDir = fileURLToPath(new URL(".", importMetaUrl));

package/config/vitest.node.setup.ts

@@ -0,0 +1,15 @@
+const isNodeRuntime =
+	typeof process !== "undefined" &&
+	process.release?.name === "node" &&
+	typeof process.versions?.node === "string";
+
+if (!isNodeRuntime) {
+	throw new Error("Node runtime is required for this Vitest configuration");
+}
+
+const [nodeMajorRaw] = process.versions.node.split(".");
+const nodeMajor = Number.parseInt(nodeMajorRaw ?? "0", 10);
+
+if (!Number.isFinite(nodeMajor) || nodeMajor < 22) {
+	throw new Error(`Vitest runtime requires Node.js >=22.0.0, received ${process.versions.node}`);
+}

package/config/vitest.setup.ts

@@ -4,41 +4,10 @@
  * @internal
  */
 // eslint-disable-next-line import/no-unassigned-import
-import "@testing-library/jest-dom/vitest";
-// eslint-disable-next-line import/no-unassigned-import
 import "urlpattern-polyfill";
-import { afterAll } from "vitest";
-
-if (!(globalThis as { URLPattern?: unknown }).URLPattern) {
-	throw new Error("URLPattern polyfill failed to load in Vitest setup");
-}
-
-let originalEmit: typeof process.emit | undefined;
-
-if (typeof process !== "undefined") {
-	type ProcessWithEmit = NodeJS.Process & {
-		emit: (event: string, error: unknown, ...args: unknown[]) => boolean;
-	};
-
-	originalEmit = process.emit.bind(process);
-	const processWithEmit = process as ProcessWithEmit;
-
-	processWithEmit.emit = function (event: string, error: unknown, ...args: unknown[]) {
-		if (
-			event === "uncaughtException" &&
-			error instanceof Error &&
-			(error.message.includes("Unable to evaluate guard") ||
-				error.message.includes("Cannot read properties of null"))
-		) {
-			return false;
-		}
+// eslint-disable-next-line import/no-unassigned-import
+import "@testing-library/jest-dom/vitest";
 
-		return originalEmit!(event, error, ...args);
-	};
+if (typeof (globalThis as { URLPattern?: unknown }).URLPattern !== "function") {
+	throw new Error("URLPattern is unavailable after setup");
 }
-
-afterAll(() => {
-	if (typeof process !== "undefined" && originalEmit) {
-		process.emit = originalEmit;
-	}
-});

package/config/vitest.ts

@@ -0,0 +1,87 @@
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { defineConfig, mergeConfig } from "vitest/config";
+import { xmAliases } from "./vite-aliases.js";
+
+const configDir = dirname(fileURLToPath(import.meta.url));
+const nodeSetupFile = resolve(configDir, "vitest.node.setup.ts");
+const setupFile = resolve(configDir, "vitest.setup.ts");
+
+/**
+ * Normalize Vitest `test.setupFiles` into a string array.
+ */
+function normalizeSetupFiles(setupFiles: unknown): string[] {
+	if (!setupFiles) return [];
+	if (Array.isArray(setupFiles)) {
+		return setupFiles.filter((entry): entry is string => typeof entry === "string");
+	}
+	return typeof setupFiles === "string" ? [setupFiles] : [];
+}
+
+/**
+ * True when Vitest browser mode is explicitly enabled.
+ */
+function isBrowserEnabled(browserConfig: unknown): boolean {
+	if (!browserConfig || typeof browserConfig !== "object") return false;
+	return (browserConfig as { enabled?: unknown }).enabled === true;
+}
+
+/**
+ * Checks whether setup files already include a file by suffix.
+ *
+ * This supports both absolute and relative setup file entries and normalizes
+ * Windows separators for cross-platform matching.
+ */
+function hasSetupFile(setupFiles: string[], fileName: string): boolean {
+	const normalizedSuffix = `/${fileName}`;
+	return setupFiles.some((entry) => entry.replaceAll("\\", "/").endsWith(normalizedSuffix));
+}
+
+/**
+ * Create a Vitest config with XMachines workspace defaults.
+ *
+ * What this applies automatically:
+ * - `resolve.alias` from `xmAliases(importMetaUrl)` so `@xmachines/*` imports
+ *   resolve to source in local/dev test runs.
+ * - `config/vitest.setup.ts` when missing.
+ * - `config/vitest.node.setup.ts` for non-browser projects when missing.
+ *
+ * Setup injection is additive and preserves caller-provided ordering after
+ * required shared setup files.
+ *
+ * @param importMetaUrl Pass `import.meta.url` from the calling config file.
+ * @param overrides Package/project-specific Vitest config overrides.
+ * @returns Merged Vitest configuration object.
+ */
+export function defineXmVitestConfig(importMetaUrl: string, overrides: Record<string, unknown>) {
+	const merged = mergeConfig(
+		defineConfig({
+			resolve: {
+				alias: xmAliases(importMetaUrl),
+			},
+		}),
+		defineConfig(overrides),
+	);
+
+	const testConfig = merged.test ?? {};
+	const setupFiles = normalizeSetupFiles(testConfig.setupFiles);
+	const browserEnabled = isBrowserEnabled(testConfig.browser);
+	const hasNodeSetup = hasSetupFile(setupFiles, "vitest.node.setup.ts");
+	const hasSharedSetup = hasSetupFile(setupFiles, "vitest.setup.ts");
+	const injectedSetupFiles: string[] = [];
+
+	if (!browserEnabled && !hasNodeSetup) {
+		injectedSetupFiles.push(nodeSetupFile);
+	}
+	if (!hasSharedSetup) {
+		injectedSetupFiles.push(setupFile);
+	}
+
+	return {
+		...merged,
+		test: {
+			...testConfig,
+			setupFiles: [...injectedSetupFiles, ...setupFiles],
+		},
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/shared",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "description": "Shared configurations for XMachines packages",
   "keywords": [
     "config",
@@ -25,10 +25,14 @@
     "./oxlint": "./config/oxlint.json",
     "./oxfmt": "./config/oxfmt.json",
     "./vite-aliases": "./config/vite-aliases.ts",
+    "./vitest": "./config/vitest.ts",
+    "./vitest-node-setup": "./config/vitest.node.setup.ts",
     "./vitest-setup": "./config/vitest.setup.ts",
     "./config/tsconfig.json": "./config/tsconfig.json",
     "./config/oxlint.json": "./config/oxlint.json",
     "./config/oxfmt.json": "./config/oxfmt.json",
+    "./config/vitest.ts": "./config/vitest.ts",
+    "./config/vitest.node.setup.ts": "./config/vitest.node.setup.ts",
     "./config/vitest.setup.ts": "./config/vitest.setup.ts"
   },
   "publishConfig": {