Configuration

This document describes every configuration file, environment variable, and per-package override used by the xmachines-js monorepo.

Environment Variables

The monorepo itself has no application runtime that reads environment variables. The only variables are for the dev container tooling and the CI/CD release pipeline.

Dev Container Variables

The dev container currently defines no workspace-specific environment variables; .devcontainer/.env (loaded via env_file in .devcontainer/compose.yaml) is available for local overrides if a future tool needs one. Copy .devcontainer/.env.sample to .devcontainer/.env to get started.

CI / Release Pipeline Variable

Variable	Required	Default	Description
`SEMREL_SKIP_STEPS`	Optional	`""` (empty — run all steps)	A single RegExp string matched against every semantic-release plugin step ID. Use `\|` for alternation to skip multiple steps. Set via the GitLab “Run pipeline” UI or API trigger.

Defined in: .gitlab-ci.yml, consumed by release.config.mjs.

Examples:

# Skip one package publish
SEMREL_SKIP_STEPS="@semantic-release/npm:packages/play-xstate"

# Skip all demo publish steps
SEMREL_SKIP_STEPS="examples/demo"

# Skip all exec steps (build, typedoc, etc.)
SEMREL_SKIP_STEPS="@semantic-release/exec"

# Publish-only retry (skip build + demos)
SEMREL_SKIP_STEPS="@semantic-release/exec|examples/demo"

# Skip git commit and GitLab release
SEMREL_SKIP_STEPS="@semantic-release/git|@semantic-release/gitlab"

Configuration Files

TypeScript — `tsconfig.json` (root)

Location: /tsconfig.json

The root TypeScript config is a build coordinator only — it compiles nothing itself. It lists every package and example via references, and that array is the whole build order: TypeScript does not inherit references through extends, so a package declares none of its own. tests/tsconfig-reference-graph.test.ts fails when the array misses a project or lists a package before something it imports.

{
  "files": [],
  "references": [
    // Layer 0 — no internal deps
    { "path": "./packages/docs" },
    { "path": "./packages/play" },
    { "path": "./packages/shared" },
    // Layer 1 — depends on Layer 0
    { "path": "./packages/play-signals" },
    // Layer 2
    { "path": "./packages/play-actor" },
    // Layer 3
    { "path": "./packages/play-router" }
    // ...etc.
  ]
}

Every package must be listed here and must have composite: true in its own tsconfig.json.

Test build coordinator: /tsconfig.test.json — identical structure but references each package’s tsconfig.test.json for type-checking tests without emitting output.

TypeScript — Shared Base Config (`@xmachines/shared/tsconfig`)

Location: packages/shared/config/tsconfig.json Exported as: @xmachines/shared/tsconfig

All packages extend this base. Key compiler settings:

Setting	Value	Notes
`target`	`ESNext`	Latest ECMAScript output. See the two passes below
`module`	`NodeNext`	ESM with `.js` extension imports required
`moduleResolution`	`NodeNext`	Matches `module` setting
`customConditions`	`["source"]`	Resolves `@xmachines/*` to TypeScript source in dev/test
`strict`	`true`	Full strict mode
`noUnusedLocals`	`true`	Error on unused variables
`noUnusedParameters`	`true`	Error on unused parameters
`noFallthroughCasesInSwitch`	`true`
`noImplicitReturns`	`true`
`noImplicitOverride`	`true`
`exactOptionalPropertyTypes`	`true`
`declaration`	`true`	Emits `.d.ts` files
`declarationMap`	`true`	Emits `.d.ts.map` for IDE go-to-source
`sourceMap`	`true`
`verbatimModuleSyntax`	`true`	Preserves `import type`
`isolatedModules`	`true`
`removeComments`	`false`	Preserves JSDoc in output

Two passes emit, and emitDeclarationOnly decides which one ships. build is vite build && tsc --build, so tsc runs last.

Fourteen publishable packages let tsc emit JavaScript. tsc overwrites the Vite pass, and compilerOptions.target above is what governs the published dist/*.js.
Five — play-vue, play-svelte, play-solid, play-solid-router, play-tanstack-solid-router — set emitDeclarationOnly, so tsc emits only .d.ts and the Vite pass is the published JavaScript. build.target governs theirs.

Vite inherits no target from the tsconfig. It reads compilerOptions.target for one purpose: to pick the useDefineForClassFields default that it gives the transform. The syntax level of the Vite pass comes from build.target, which packages/shared/config/vite.ts sets — "esnext" for a publishable package, and an explicit browser list for a demo app.

Leave both stated, and keep both at ESNext for a library. A package that inherits the Vite default builds against a browser baseline, which is a second and lower ceiling than the one this table declares — and it is the ceiling that ships for those five.

A demo states an explicit browser list, and not baseline-widely-available. A target controls syntax and adds no method. baseline-widely-available of Vite 8 names firefox114, the demos bundle play-router, and play-router calls toSorted(), which shipped in Firefox 115. The list in vite.ts therefore raises that one entry, so the declared floor is the floor the bundle runs on.

Per-package tsconfig.json pattern:

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

A package declares no references. Its dependencies live in package.json, and the root array orders the build.

Test tsconfig (@xmachines/shared/tsconfig-test):

Location: packages/shared/config/tsconfig.test.json

Test builds add noEmit: true, allowImportingTsExtensions: true, and vitest/globals types. Used by pnpm run test:build to type-check test files without emitting output. That script passes --force, so the check covers every project of the solution on every run.

Linting — `oxlint.config.ts` (root)

Location: /oxlint.config.ts Tool: oxlint ^1.62.0 Run: pnpm run lint / pnpm run lint:fix

The root config extends the shared base (@xmachines/shared/oxlint) and adds workspace-level ignore patterns:

export default defineConfig({
  extends: [sharedConfig],
  ignorePatterns: [
    ".opencode",
    "node_modules",
    "dist",
    "build",
    "coverage",
    "docs/api/_media",
    "*.min.js",
    "CHANGELOG.md",
  ],
});

Shared base rules (packages/shared/config/oxlint.config.ts):

Plugin	Category	Severity
`typescript`	`correctness`	`error`
`unicorn`	`suspicious`	`warn`
`import`	`perf`	`warn`
`import/no-cycle`	—	`error`
`typescript/no-explicit-any`	—	`error`
`typescript/no-unused-vars`	—	`error` (ignores `_` prefixed names)
`unicorn/filename-case`	—	`off`
`unicorn/no-array-sort`	—	`error`
`no-underscore-dangle`	—	`off`

unicorn/no-array-sort is an error and not the warning of its category. The workspace targets ESNext, and Node 22 — the lowest runtime a published package supports — has toSorted(), so the method is always available. As a warning the rule kept the lint job green while the Code Quality report showed the degradation, and sort() stayed behind a suppression for a ceiling that had already gone.

no-underscore-dangle is off because it contradicts typescript/no-unused-vars, which declares ^_ as the mark of a binding that exists on purpose and that nothing reads. A using declaration is the case that makes the contradiction concrete: the scope reads the binding through Symbol.dispose, the linter sees no read, and the _ that answers one rule trips the other.

Per-package override pattern:

// packages/<name>/oxlint.config.ts
import sharedConfig from "@xmachines/shared/oxlint";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [sharedConfig],
  // add package-specific rules here
});

Formatting — `oxfmt.config.ts` (root)

Location: /oxfmt.config.ts Tool: oxfmt ^0.47.0 Run: pnpm run format / pnpm run format:check

The root config extends the shared base and adds workspace-level ignore patterns:

export default defineConfig({
  ...sharedConfig,
  ignorePatterns: [
    ...(sharedConfig.ignorePatterns ?? []),
    ".opencode",
    ".agents",
    ".githuman",
    ".devcontainer",
    "CHANGELOG.md",
    "Thumbs.db",
  ],
});

Shared base format settings (packages/shared/config/oxfmt.config.ts):

Setting	Value
`printWidth`	`100`
`tabWidth`	`4`
`useTabs`	`true`
`semi`	`true`
`singleQuote`	`false`
`trailingComma`	`"all"`
`insertFinalNewline`	`true`

JSON / YAML override (applied via overrides):

Setting	Value
`useTabs`	`false`
`tabWidth`	`2`

Editor — `.editorconfig`

Location: /.editorconfig

Setting	`[*]`	`[*.{json,yml,yaml}]`	`[*.md]`
`indent_style`	`tab`	`space`	—
`indent_size`	`4`	`2`	—
`end_of_line`	`lf`	—	—
`charset`	`utf-8`	—	—
`trim_trailing_whitespace`	`true`	—	`false`
`insert_final_newline`	`true`	—	—

Testing — `vitest.config.ts` (root)

Location: /vitest.config.ts Tool: Vitest ^4.1.5 Run: pnpm test / pnpm run test:coverage

Root Vitest config is a workspace coordinator that lists all per-package configs under test.projects. It sets conservative monorepo-wide defaults:

Setting	Value	Notes
`pool`	`"forks"`	Process-isolated workers
`maxWorkers`	`4`	Root default; per-project configs may override
`isolate`	`true`
`fileParallelism`	`false`	Conservative default; safe packages opt in with `true`
`teardownTimeout`	`30000` ms
`hookTimeout`	`30000` ms
`testTimeout`	`10000` ms

Coverage thresholds (monorepo aggregate — vitest run --coverage):

Type	Threshold
Lines	80%
Functions	80%
Branches	75%
Statements	80%

Coverage provider: v8. Individual packages may declare higher per-package thresholds in their own vitest.config.ts.

Browser test config: /vitest.browser.config.ts Run with pnpm run test:browser. Uses Playwright Chromium via Vitest browser mode. testTimeout is 20000 ms; maxWorkers is 2 (default; demo integration projects override with pool: "threads" + maxWorkers: 2).

Per-Package Vitest Config — `@xmachines/shared/vitest`

Location: packages/shared/config/vitest.ts Exported as: @xmachines/shared/vitest

Packages use defineXmVitestConfig(import.meta.url, overrides) to create their config. It automatically injects:

resolve.alias via xmAliases() so @xmachines/* imports resolve to TypeScript source without a prior build.
vitest.node.setup.ts for non-browser projects (if not already present).
vitest.setup.ts for all projects (if not already present).

Typical per-package usage:

// packages/<name>/vitest.config.ts
import { defineXmVitestConfig } from "@xmachines/shared/vitest";

export default defineXmVitestConfig(import.meta.url, {
  test: {
    name: "play-example",
    include: ["test/**/*.test.ts"],
  },
});

Vite Source Aliases — `@xmachines/shared/vite-aliases`

Location: packages/shared/config/vite-aliases.ts Exported as: @xmachines/shared/vite-aliases

Provides two helpers used in all vitest.config.ts and vite.config.ts files:

xmAliases(import.meta.url) — returns a Record<string, string> mapping every @xmachines/* package to its TypeScript source entry. Enables tests and dev servers to run without a prior pnpm run build.
xmResolve(import.meta.url) — returns a full Vite resolve config with xmAliases plus preserveSymlinks: true and conditions: ["source"].
xmCacheDir(import.meta.url, name) — returns a shared Vite cache path under node_modules/.vite/<name> to prevent redundant dep optimizer runs across projects.
xmOptimizeDeps(include?) — returns an optimizeDeps.include list holding exactly the specifiers passed in. Nothing is pre-bundled by default, and every entry has to be a package the calling project declares: pnpm gives each package its own node_modules, so Vite cannot resolve an undeclared specifier — it warns on stderr and carries on, which reads as a failure in a passing job.

Release — `release.config.mjs`

Location: /release.config.mjs Tool: semantic-release via @semantic-release/* plugins

Defines the release branches and plugin chain used by the GitLab CI semantic-release job.

Release branches:

Branch	Channel	Pre-release
`main`	(default)	No
`rc`	`rc`	`rc`
`beta`	`beta`	`true`
`alpha`	`alpha`	`alpha`
`pre`	`pre`	`pre`

Only main is a protected branch today. That works because GITLAB_TOKEN — which the release needs, since CI_JOB_TOKEN can push neither the release commit nor the tag — is an unprotected group variable and so reaches every one of these refs. If it is ever made protected, each of these branches has to be protected too, or the release fails in verify-conditions with EGITNOPERMISSION rather than at the registry.

Tag format: v${version}

Plugin order:

@semantic-release/commit-analyzer — determines version bump from conventional commits
@semantic-release/release-notes-generator — builds release notes
@semantic-release/changelog — writes CHANGELOG.md
@semantic-release/exec steps (in order):
- corepack — corepack enable
- install — pnpm install --frozen-lockfile
- set-workspace-versions — updates all package.json files to the new version
- build — pnpm run build
- typedoc — pnpm --filter @xmachines/docs run typedoc
- format-docs — pnpm --filter @xmachines/docs run format
@semantic-release/npm — one entry per published package (20 packages) + pack-only for demo apps
@semantic-release/git — commits CHANGELOG.md, updated package.json files, and generated API docs
@semantic-release/gitlab — creates a GitLab release with tarball assets

Any step can be skipped via the SEMREL_SKIP_STEPS CI variable (see Environment Variables).

Per-Environment Overrides

This monorepo has no application-level config with per-environment overrides (no .env.development / .env.production files). All configuration is tool-level (TypeScript, linter, formatter, test runner) and is environment-agnostic.

The only environment-specific distinction is between local development (dev container with .devcontainer/.env) and CI (GitLab CI with pipeline variables), described in the sections above.

Required vs Optional Settings Summary

Config	Required to Work	Optional / Has Default
`SEMREL_SKIP_STEPS`	No	Default: `""` (run all steps)
Root `tsconfig.json` `references`	Yes — the whole build order	—
Per-package `references`	No — TypeScript drops them on `extends`	—
Per-package `composite: true`	Yes — required for project references	—
`@xmachines/shared/tsconfig` extends	Yes — all packages must extend it	—
`@xmachines/shared/oxlint` extends	Yes — all packages must extend it	—
`@xmachines/shared/oxfmt` extends	Yes — all packages must extend it	—

Adding a New Package

When adding a new package, update these configuration files:

/tsconfig.json — add a { "path": "./packages/<name>" } entry in the correct dependency layer.
/tsconfig.test.json — add a { "path": "./packages/<name>/tsconfig.test.json" } entry.
/vitest.config.ts — add "packages/<name>/vitest.config.ts" to test.projects.
/vitest.browser.config.ts (if the package has browser tests) — add the browser config path to test.projects.
/release.config.mjs — add an entry to NPM_PACKAGES array with the package’s pkgRoot.

See AGENTS.md for the full new-package checklist.

Configuration

Environment Variables

Dev Container Variables

CI / Release Pipeline Variable

Configuration Files

TypeScript — tsconfig.json (root)

TypeScript — Shared Base Config (@xmachines/shared/tsconfig)

Linting — oxlint.config.ts (root)

Formatting — oxfmt.config.ts (root)

Editor — .editorconfig

Testing — vitest.config.ts (root)

Per-Package Vitest Config — @xmachines/shared/vitest

Vite Source Aliases — @xmachines/shared/vite-aliases

Release — release.config.mjs