@xmachines/shared

API / @xmachines/shared

Shared configurations for the XMachines packages: TypeScript, linting, formatting, and the Vitest setup that the monorepo uses.

Installation

This package is an internal dependency of the monorepo. An external user must not install it.

In the monorepo, each package refers to it by 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 (it ignores a name with a _ prefix)

Formatting (oxfmt)

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

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

The main formatting rules are a tab width of 4 with real tab characters, a print width of 100 characters, double quotes, a trailing comma, and a final newline. A JSON file and a YAML file use an indentation of 2 spaces.

Vitest Configuration

Use defineXmVitestConfig for the Vitest config of a package. It adds the shared setup files and the @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 — the Node.js runtime guard (the browser mode skips it)
• 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

In a Vite demo package or app package, resolve every @xmachines/* package to its TypeScript source. A build first is not necessary:

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 the aliases alone. Use xmResolve for a resolve config that adds preserveSymlinks (false by default) and your other resolve options to the aliases. For example, give conditions yourself if you need it.

In a browser test project, use xmOptimizeDeps to bundle the packages in advance. The optimizer then does not restart during a run. Use xmCacheDir to share one Vite dependency 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" — xmAliases uses it to resolve a package to its TypeScript source in development and in a test

Testing

# Run tests for this package
pnpm --filter @xmachines/shared test

# Or from the package directory
pnpm test

License

MIT — see LICENSE.

Modules

• vite-aliases
• vitest