@xmachines/shared 1.0.0-beta.4

package/README.md

@@ -0,0 +1,238 @@
+# @xmachines/shared
+
+**Shared TypeScript, linting, and formatting configurations for XMachines monorepo**
+
+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.
+
+**Enhancement:** Added TypeScript composite build system with project references enabling correct build order, incremental compilation, and IDE source navigation via declaration maps.
+
+## Installation
+
+This package is automatically available to all workspace packages via npm workspaces.
+
+## Contents
+
+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
+
+## Usage
+
+### TypeScript Configuration
+
+**Recommended (short alias):**
+
+```json
+{
+	"extends": "@xmachines/shared/tsconfig",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	}
+}
+```
+
+**Alternative (full path):**
+
+```json
+{
+	"extends": "@xmachines/shared/config/tsconfig.json",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	}
+}
+```
+
+> **Note:** Both import styles work. The short alias is recommended for cleaner config files.
+
+### Oxlint Configuration
+
+**Recommended:**
+
+```json
+{
+	"extends": ["@xmachines/shared/oxlint"]
+}
+```
+
+### Oxfmt Configuration
+
+**Recommended:**
+
+```json
+{
+	"extends": ["@xmachines/shared/oxfmt"]
+}
+```
+
+## Configuration Details
+
+### TypeScript (`config/tsconfig.json`)
+
+- **Target:** ESNext (Node.js 22+)
+- **Module:** NodeNext (ESM with `.js` extensions required)
+- **Strict:** Full strict mode enabled
+- **Output:** Colocated `.d.ts` files with source maps
+- **Composite:** Enabled for project references ()
+
+**Important:** You must use `.js` extensions in imports:
+
+```typescript
+import { foo } from "./bar.js"; // ✅ Correct
+import { foo } from "./bar"; // ❌ Wrong
+```
+
+### Oxlint (`config/oxlint.json`)
+
+- **Plugins:** TypeScript, Unicorn, Import
+- **Categories:** Correctness (error), Suspicious (warn), Performance (warn)
+- **Key Rules:**
+    - Circular dependency detection (`import/no-cycle`)
+    - Unused variables (allow `_` prefix)
+    - TypeScript-specific checks
+
+### Oxfmt (`config/oxfmt.json`)
+
+- **Line Width:** 100 characters
+- **Indentation:** Tabs (4 spaces)
+- **Style:** Double quotes, semicolons, trailing commas
+- **Final Newline:** Always insert
+
+## TypeScript Composite Build System
+
+This package introduced TypeScript project references for proper build-order management in the monorepo.
+
+### What This Means
+
+- **Root `tsconfig.json`** coordinates all packages via `references` array
+- **Each package** has `composite: true` enabling incremental builds
+- **Packages with dependencies** declare `references` to their deps
+- **TypeScript builds in correct order automatically** (no manual sequencing needed)
+
+### Building
+
+```bash
+npm run build          # Root-level tsc --build handles everything
+npm run build -w <pkg> # Automatically builds dependencies first
+```
+
+The root build command uses `tsc --build` which:
+
+- Understands the dependency graph
+- Builds packages in correct order
+- Only rebuilds changed packages (incremental)
+- Produces `.d.ts.map` files for IDE navigation
+
+### Declaration Maps
+
+The base config enables **declaration maps** (`declarationMap: true`) for better IDE experience in composite projects.
+
+When TypeScript compiles with `declarationMap: true`, it produces `.d.ts.map` files that map type definitions back to source. This enables:
+
+- **Go to Definition** jumps to `.ts` source files (not compiled `.d.ts`)
+- **Rename refactoring** works across package boundaries
+- **Error messages** reference source locations
+
+**Cost:** Slightly larger `dist/` output (~10% more)  
+**Benefit:** Dramatically better IDE experience
+
+### Project References
+
+Packages with internal dependencies should declare `references` in their `tsconfig.json`:
+
+```json
+{
+	"extends": "@xmachines/shared/tsconfig",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"references": [{ "path": "../dependency-package" }]
+}
+```
+
+The root `tsconfig.json` maintains the full package reference graph, enabling TypeScript to:
+
+- Build packages in correct dependency order
+- Support incremental builds (only rebuild what changed)
+- Enable cross-package type checking and navigation
+
+### Adding New Packages
+
+When creating a new package:
+
+1. **Add to root tsconfig.json references:**
+
+    ```json
+    {
+    	"references": [{ "path": "./packages/your-new-package" }]
+    }
+    ```
+
+2. **Enable composite in package tsconfig.json:**
+
+    ```json
+    {
+    	"extends": "@xmachines/shared/tsconfig",
+    	"compilerOptions": {
+    		"composite": true,
+    		"rootDir": "./src",
+    		"outDir": "./dist"
+    	}
+    }
+    ```
+
+3. **Declare dependencies (if any):**
+    ```json
+    {
+    	"references": [{ "path": "../dependency-package" }]
+    }
+    ```
+
+### IDE Benefits
+
+With `declarationMap: true` in the base config:
+
+- **Go to Definition** jumps to source files (not compiled `.d.ts`)
+- **Real-time errors** across package boundaries
+- **Refactoring works** across the entire monorepo
+
+No build required for IDE features - TypeScript understands the source graph directly.
+
+See `AGENTS.md` (section: TypeScript Composite Build System) for complete composite build documentation.
+
+## Adding New Configurations
+
+To add a new shared configuration (e.g., for Jest, Vitest, etc.):
+
+1. Create `config/<tool>.json` (or `.js`, `.ts` as appropriate)
+2. Add exports to `package.json` exports field:
+    ```json
+    {
+    	"exports": {
+    		"./<tool>": "./config/<tool>.json",
+    		"./config/<tool>.json": "./config/<tool>.json"
+    	}
+    }
+    ```
+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

package/config/oxfmt.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 100,
+  "tabWidth": 4,
+  "useTabs": true,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "insertFinalNewline": true
+}

package/config/oxlint.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "../../../node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn", "import"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "pedantic": "off",
+    "perf": "warn",
+    "style": "off"
+  },
+  "rules": {
+    "unicorn/filename-case": "off",
+    "import/no-cycle": "error",
+    "typescript/no-explicit-any": "warn",
+    "typescript/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }
+    ]
+  },
+  "env": {
+    "es2025": true,
+    "node": true
+  }
+}

package/config/tsconfig.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    /* Language and Environment */
+    "target": "ESNext",
+    "lib": ["ESNext"],
+
+    /* Modules */
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+
+    /* Type Checking */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+
+    /* Emit */
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": false,
+    "importHelpers": false,
+
+    /* Interop Constraints */
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+
+    /* Completeness */
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "**/*.spec.ts", "**/*.test.ts"]
+}

package/config/vite-aliases.ts

@@ -0,0 +1,87 @@
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Vite resolve.alias entries for all @xmachines/* workspace packages.
+ *
+ * Maps every package to its TypeScript source entry so that `npm run dev`
+ * works without a prior `npm run build`. Required because `npm run clean`
+ * removes all dist/ directories — including transitive dependencies —
+ * leaving Vite unable to resolve package.json `exports` that point to dist/.
+ *
+ * Usage in a demo vite.config.ts:
+ *
+ *   import { xmAliases } from "@xmachines/shared/vite-aliases";
+ *
+ *   export default defineConfig({
+ *     resolve: { alias: xmAliases(import.meta.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));
+
+	// Walk up from the config file's directory until we find the folder that
+	// contains a `packages/` subdirectory — that's the workspace root.
+	let root = configDir;
+	while (!isWorkspaceRoot(root)) {
+		const parent = resolve(root, "..");
+		if (parent === root)
+			throw new Error(`[xmAliases] Could not find workspace root from ${configDir}`);
+		root = parent;
+	}
+
+	const p = (pkg: string) => resolve(root, "packages", pkg, "src/index.ts");
+
+	return {
+		"@xmachines/play": p("play"),
+		"@xmachines/play-actor": p("play-actor"),
+		"@xmachines/play-catalog": p("play-catalog"),
+		"@xmachines/play-signals": p("play-signals"),
+		"@xmachines/play-router": p("play-router"),
+		"@xmachines/play-xstate": p("play-xstate"),
+		"@xmachines/play-react": p("play-react"),
+		"@xmachines/play-react-router": p("play-react-router"),
+		"@xmachines/play-solid": p("play-solid"),
+		"@xmachines/play-solid-router": p("play-solid-router"),
+		"@xmachines/play-vue": p("play-vue"),
+		"@xmachines/play-vue-router": p("play-vue-router"),
+		"@xmachines/play-tanstack-react-router": p("play-tanstack-react-router"),
+		"@xmachines/play-tanstack-solid-router": p("play-tanstack-solid-router"),
+		"@xmachines/play-router-shared/index.css": resolve(
+			root,
+			"packages",
+			"play-router",
+			"examples",
+			"shared",
+			"src/index.css",
+		),
+		"@xmachines/play-router-shared": resolve(
+			root,
+			"packages",
+			"play-router",
+			"examples",
+			"shared",
+			"src",
+		),
+	};
+}
+
+import { existsSync, readFileSync } from "fs";
+
+function isWorkspaceRoot(dir: string): boolean {
+	const pkgPath = resolve(dir, "package.json");
+	if (!existsSync(pkgPath)) return false;
+	try {
+		const raw = readFileSync(pkgPath, "utf8");
+		const pkg = JSON.parse(raw) as { workspaces?: unknown };
+		return Array.isArray(pkg.workspaces);
+	} catch {
+		return false;
+	}
+}

package/config/vitest.setup.ts

@@ -0,0 +1,44 @@
+/**
+ * Vitest setup shared across packages.
+ * Extends matchers with @testing-library/jest-dom.
+ * @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;
+		}
+
+		return originalEmit!(event, error, ...args);
+	};
+}
+
+afterAll(() => {
+	if (typeof process !== "undefined" && originalEmit) {
+		process.emit = originalEmit;
+	}
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@xmachines/shared",
+  "version": "1.0.0-beta.4",
+  "description": "Shared configurations for XMachines packages",
+  "keywords": [
+    "config",
+    "shared",
+    "xmachines"
+  ],
+  "license": "MIT",
+  "author": "Mikael Karon <mikael@karon.se>",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/xmachin-es/xmachines-js.git",
+    "directory": "packages/shared"
+  },
+  "files": [
+    "config",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./tsconfig": "./config/tsconfig.json",
+    "./oxlint": "./config/oxlint.json",
+    "./oxfmt": "./config/oxfmt.json",
+    "./vite-aliases": "./config/vite-aliases.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.setup.ts": "./config/vitest.setup.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@testing-library/jest-dom": "^6.9.1"
+  }
+}