@xmachines/shared

API / @xmachines/shared

Shared configurations for XMachines packages — TypeScript, linting, formatting, and Vitest setup used across the monorepo.

Part of the xmachines-js monorepo.

Installation

This package is an internal monorepo dependency. It is not intended for installation by external consumers.

Within the monorepo it is referenced by package name:

{
  "dependencies": {
    "@xmachines/shared": "*"
  }
}

Exports

Export	File	Description
@xmachines/shared/tsconfig	config/tsconfig.json	Base TypeScript configuration for all packages
@xmachines/shared/tsconfig-test	config/tsconfig.test.json	TypeScript configuration for test files (no emit, allowImportingTsExtensions, Vitest globals)
@xmachines/shared/oxlint	config/oxlint.config.ts	Shared oxlint configuration
@xmachines/shared/oxfmt	config/oxfmt.config.ts	Shared oxfmt formatter configuration
@xmachines/shared/vite-aliases	config/vite-aliases.ts	Vite resolve aliases for all @xmachines/* workspace packages
@xmachines/shared/vitest	config/vitest.ts	defineXmVitestConfig helper for per-package Vitest configs
@xmachines/shared/vitest-setup	config/vitest.setup.ts	Shared Vitest setup — extends matchers with @testing-library/jest-dom
@xmachines/shared/vitest-node-setup	config/vitest.node.setup.ts	Node.js runtime guard — asserts Node.js >= 22
@xmachines/shared/vitest-urlpattern-setup	config/vitest.urlpattern.setup.ts	Optional URLPattern polyfill setup for route-matching tests

Usage

TypeScript Configuration

Extend the base TypeScript config in any package:

{
  "extends": "@xmachines/shared/tsconfig",
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

For test-specific TypeScript settings (no emit, allowImportingTsExtensions, Vitest globals), extend:

{
  "extends": "@xmachines/shared/tsconfig-test",
  "include": ["src/**/*", "test/**/*"]
}

Linting (oxlint)

Reference the shared oxlint config from a package’s oxlint.config.ts:

import sharedConfig from "@xmachines/shared/oxlint";
export default sharedConfig;

The shared config enables the typescript, unicorn, and import plugins with:

• correctness rules as errors
• suspicious and perf rules as warnings
• import/no-cycle and typescript/no-explicit-any as errors
• typescript/no-unused-vars as an error (ignoring _-prefixed names)

Formatting (oxfmt)

Reference the shared oxfmt config from a package’s oxfmt.config.ts:

import sharedConfig from "@xmachines/shared/oxfmt";
export default sharedConfig;

Key formatting rules: 4-space tab width using actual tabs, 100-character print width, double quotes, trailing commas, final newline. JSON/YAML files use 2-space indentation.

Vitest Configuration

Use defineXmVitestConfig for per-package Vitest configs. It automatically injects shared setup files and wires @xmachines/* source aliases:

vitest.config.ts

import { defineXmVitestConfig } from "@xmachines/shared/vitest";

export default defineXmVitestConfig(import.meta.url, {
  test: {
    globals: true,
  },
});

What defineXmVitestConfig applies automatically:

• resolve.alias from xmAliases(import.meta.url) — resolves @xmachines/* to TypeScript source
• config/vitest.node.setup.ts — Node.js runtime guard (skipped in browser mode)
• config/vitest.setup.ts — @testing-library/jest-dom matcher extensions

For packages that test URL routing, add the URLPattern polyfill setup:

export default defineXmVitestConfig(import.meta.url, {
  test: {
    globals: true,
    setupFiles: ["@xmachines/shared/vitest-urlpattern-setup"],
  },
});

Vite Aliases

For Vite-based demo or app packages, resolve all @xmachines/* packages to TypeScript source (no prior build required):

vite.config.ts

import { defineConfig } from "vite";
import { xmResolve } from "@xmachines/shared/vite-aliases";

export default defineConfig({
  resolve: xmResolve(import.meta.url),
});

Use xmAliases for alias-only setup, or xmResolve for the full resolve config including conditions: ["source"] and preserveSymlinks: true.

For browser test projects, use xmOptimizeDeps to pre-bundle packages and avoid mid-run optimizer restarts, and xmCacheDir to share a single Vite dep cache across the workspace:

import { xmResolve, xmOptimizeDeps, xmCacheDir } from "@xmachines/shared/vite-aliases";

export default defineConfig({
  cacheDir: xmCacheDir(import.meta.url, "my-project"),
  resolve: xmResolve(import.meta.url),
  optimizeDeps: xmOptimizeDeps(["my-framework-package"]),
});

Key TypeScript Settings

The base config/tsconfig.json configures:

• Target: ESNext, Module: NodeNext with moduleResolution: NodeNext
• Strict mode: full strict, noUnusedLocals, noUnusedParameters, exactOptionalPropertyTypes, noImplicitReturns, noImplicitOverride
• Emit: declaration, declarationMap, sourceMap enabled
• Interop: verbatimModuleSyntax, isolatedModules
• Custom condition: "source" — used by xmAliases to resolve packages to TypeScript source in dev/test

Testing

# Run tests for this package
npm test -w packages/shared

# Or from the package directory
npm test

License

MIT — see LICENSE.

Modules

• vite-aliases
• vitest