@xova/matrix

Configuration-driven CLI for running and packaging multi-app workspaces.

English · 简体中文

Define projects once, then run development, builds, previews, and custom commands by product and environment.

Features

• Typed configuration for projects, products, variants, and targets
• Built-in dev, build, dist, preview, and test targets
• Target dependencies with ready and completed conditions
• development, staging, and production environments
• Custom environment names such as qa and uat
• Layered environment variables with dotenv and shell overrides
• Interactive product and environment selection
• Ordered target commands and configurable artifact materialization under artifacts

Install

Requires Node.js >=22.18.0.

pnpm add -D @xova/matrix

Quick start

Create matrix.config.ts in the workspace root:

import { defineMatrixConfig, defineMatrixEnv } from '@xova/matrix'

export default defineMatrixConfig({
  projects: {
    web: {
      root: './apps/web',
      targets: {
        dev: 'vite',
        build: { command: 'vite build', artifacts: { mode: 'archive' } },
        preview: 'vite preview',
      },
    },
  },
  products: {
    app: {
      variants: { web: 'web' },
    },
  },
})

Run it from the directory containing the config file:

matrix dev app
matrix build app --env staging
matrix plan app --target preview --env production
matrix doctor

When product, target, or --env is omitted in an interactive terminal, Matrix prompts for a selection. Interactive selection follows Product → Variant → Target → Environment, and one run selects a single Product. Use --product and --target to provide explicit selections without relying on positional argument order.

See examples/basic for a self-contained example that runs without a framework dependency.

Configuration

| Concept | Purpose | | ------- | ----------------------------------------------------------------------- | | Project | An application directory and its commands | | Product | A runnable deliverable composed of variants | | Variant | A product entry bound to a project | | Target | A command such as dev, build, preview, test, or a custom target |

Multiple variants

A product can run more than one project and express dependencies per target:

export default {
  products: {
    app: {
      variants: {
        web: 'web',
        desktop: {
          project: 'desktop',
          targets: {
            dev: { dependsOn: [{ variant: 'web', condition: 'ready' }] },
            build: { dependsOn: [{ variant: 'web', condition: 'completed' }] },
          },
        },
      },
    },
  },
}

ready is useful for continuous targets such as dev; completed is useful for one-shot targets such as build.

Environments

Use top-level env and $env for values shared by all products. Put product-specific values under the product when different products assemble the same projects with different backends:

export default defineMatrixConfig({
  projects: {},
  products: {
    app: {
      appId: 'com.example.app',
      env: { VITE_API_BASE: 'http://localhost:3000' },
      $env: defineMatrixEnv({
        staging: { VITE_API_BASE: 'https://staging-api.example.com' },
        production: { VITE_API_BASE: 'https://api.example.com' },
      }),
      variants: {},
    },
  },
})

defineMatrixEnv() is syntax sugar for the c12-compatible $env.<environment>.env shape. The raw shape remains supported.

Ordinary application variables are merged from low to high precedence:

global env/$env < product env/$env < .env layers < process.env

Product identity overrides are resolved from the merged environment before suffixes are applied:

product identity < variant identity < merged identity override < environment suffix

MATRIX_PRODUCT_NAME, MATRIX_PRODUCT_SLUG, and MATRIX_PRODUCT_APP_ID may provide identity overrides through the environment. The final values, including suffixes, are written back to both task metadata and the corresponding MATRIX_PRODUCT_* variables. MATRIX_PRODUCT_ID, MATRIX_PRODUCT_KEY, execution-context variables, and NODE_ENV are generated by Matrix and cannot be overridden by the environment.

Matrix injects the following execution-context variables into every child process:

MATRIX_ENV_NAME
MATRIX_TARGET
MATRIX_PRODUCT_KEY
MATRIX_PRODUCT_ID
MATRIX_PRODUCT_NAME
MATRIX_PRODUCT_SLUG
MATRIX_PRODUCT_APP_ID
MATRIX_VARIANT
MATRIX_PROJECT
MATRIX_NODE_ENV
NODE_ENV

MATRIX_ENV_NAME is the selected Matrix configuration environment and may be a custom name such as staging or qa. NODE_ENV describes the target process mode: dev uses development, test uses test, while build and preview use production. MATRIX_NODE_ENV is the same generated value under the reserved MATRIX_ prefix so Vite's prefixed config.env can carry it into the build-time runtime module. Therefore a staging build normally receives MATRIX_ENV_NAME=staging, MATRIX_NODE_ENV=production, and NODE_ENV=production. MATRIX_PRODUCT_APP_ID is emitted only when the resolved product identity has an appId; environment suffixes are applied before it is exported.

Product-level environment values are resolved independently for each product. This lets two products reuse the same Desktop project while connecting it to different Web variants or services.

Custom environment names are supported. Define them with the same helper and pass the name explicitly to the CLI:

export default defineMatrixConfig({
  $env: defineMatrixEnv({
    qa: {
      VITE_API_BASE: 'https://qa-api.example.com',
    },
  }),
  projects: {},
  products: {},
})

matrix build app --env qa
matrix plan app --target preview --env qa

Custom environments are available through --env. When running interactively, Matrix adds names found in the top-level and product $env configuration to the selector.

Dotenv files are loaded as .env, .env.local, .env.<environment>, and .env.<environment>.local. Matrix passes variables such as VITE_* and NUXT_* to child processes; application frameworks keep ownership of their own runtime configuration.

Build tool integration

Matrix provides one Unplugin factory and host-specific entrypoints.

import matrix from '@xova/matrix/vite'

export default defineConfig({
  plugins: [matrix()],
})

The Vite adapter preserves the resolved envPrefix and adds the reserved MATRIX_ prefix. It reads the final Vite config.env and exposes the structured build context through virtual:matrix/runtime:

import { matrix } from 'virtual:matrix/runtime'

matrix.environment
matrix.product.name
matrix.product.appId
matrix.config.apiBase

matrix.isDevelopment
matrix.isProduction
matrix.isTest

The mode flags are derived from Matrix's resolved nodeEnv (development, production, or test). They are build-time snapshot values; use matrix.target for Matrix-specific targets such as dev, build, dist, and preview.

The same factory is available from @xova/matrix/rollup, @xova/matrix/webpack, and @xova/matrix/esbuild. The virtual module is a build-time snapshot, not a deployment-time runtime configuration system. Only variables already exposed by the host prefixes are mapped into matrix.config.

For multiple Electron configs, assign a scope to each build so main, preload, and renderer do not overwrite one another:

export default defineConfig({
  main: {
    plugins: [matrix({ scope: 'main' })],
  },
  preload: {
    plugins: [matrix({ scope: 'preload' })],
  },
})

Import virtual:matrix/runtime/main and virtual:matrix/runtime/preload respectively. Their declarations are generated as .matrix/types/matrix-runtime-main.d.ts and .matrix/types/matrix-runtime-preload.d.ts.

Run matrix prepare to generate .matrix/types/matrix-runtime.d.ts under every project referenced by the selected products. When a project is shared by multiple products, its declaration contains the union of their public environment keys. It derives ImportMetaEnv and matrix.config key types from VITE_* (and other configured public prefixes) without writing environment values. Build plugins also generate the matching declaration after resolving the final envPrefix by default; set types: false to disable it. Add .matrix/types to each project's include list in tsconfig.json to enable the declarations:

{
  "include": ["src", ".matrix/types"]
}

Targets and defaults

The built-in targets use these defaults:

| Target | Environment | Continuous | | --------- | ------------- | ---------- | | dev | development | Yes | | build | production | No | | dist | production | No | | preview | production | Yes | | test | development | No |

Custom targets are non-continuous by default and use development unless --env is provided. The built-in target runtime modes are development for dev, test for test, and production for build, dist, and preview. Custom targets may set nodeEnv to development, production, or test. Project roots default to ., target output directories default to dist, and artifact output defaults to artifacts. Targets may use a string array for ordered commands, such as release: ['pnpm build', 'pnpm package']. Artifact delivery defaults to move with ZIP as the archive format; set artifacts.mode to archive or both when needed. When artifact delivery is enabled, artifacts.clean defaults to true and clears the output directory before each non-continuous target runs, so materialized artifacts contain only the current execution's output. Archive mode keeps the current output directory, while move and both relocate it into the artifact directory. Artifact names use <variant>-<version>-<YYYYMMDD-HHmmss>, with five ArtifactSets retained by default per product, environment, and variant.

Interactive Variant selection comes before Target selection. Target options are derived from the common targets available to the selected Variants; use --variant to provide the scope in non-interactive runs.

Any configured target can be invoked from the CLI. test, lint, and e2e are common custom targets.

Commands

matrix [target] [product] [--variant name] [--env <environment>]
matrix --product <product> [--target <target>] [--variant name] [--env <environment>]
matrix dev [product]
matrix build [product] [--env <environment>]
matrix dist [product] [--env <environment>]
matrix preview [product] [--env <environment>]
matrix test [product] [--env <environment>]
matrix plan [product] [--target <target>] [--env <environment>]
matrix doctor
matrix prepare [product] [--env <environment>]
matrix <custom-target> [product] [--env <environment>]

Development

Dependency versions are maintained in the pnpm catalog in pnpm-workspace.yaml.

pnpm install
pnpm check
pnpm lint:fix

pnpm lint:fix formats JavaScript, TypeScript, and Markdown through ESLint. pnpm check runs lint, typecheck, tests, and the production build.

License

MIT