swx

A generic regex-based config switcher CLI. Define environments in a single JSON file and swap values across any files in your project with one command.

Installation

pnpm add -D @swx/cli
# or
npm install -D @swx/cli

Quick Start

Run the interactive setup in your project root:

swx init

This walks you through creating a swx.config.json. Once created, switch environments with:

swx switch <env>

Or you can define a command directly in your package.json scripts:

{
  "scripts": {
    "switch:dev": "swx switch dev",
    "switch:staging": "swx switch staging"
  }
}

Commands

swx init

Interactively generates a swx.config.json in the current directory. If one already exists you will be prompted to confirm before overwriting.

swx switch <env>

Applies the replacements defined for the given environment across all configured files.

swx switch dev
swx switch staging

Options:

| Flag | Description | | ------- | ----------------------------------------------- | | --dry | Preview what would change without writing files |

swx switch staging --dry

Dry run output shows a line-by-line diff per file:

src/config.ts:
- const ENV = "dev"
+ const ENV = "staging"

swx list

Opens an interactive prompt to select an environment and switch to it.

swx list

If enableDryRunInList is enabled in your config, you will also be asked whether to perform a dry run before applying changes.

Configuration

swx.config.json lives at the root of your project. swx walks up the directory tree to find it, so you can run commands from any subdirectory.

{
  "environments": {
    "dev": {
      "description": "Development environment",
      "replacements": [
        {
          "files": ["src/config.ts"],
          "regex": "/(staging|production)/",
          "value": "development"
        }
      ]
    },
    "staging": {
      "description": "Staging environment",
      "replacements": [
        {
          "files": ["src/config.ts"],
          "regex": "/(development|production)/",
          "value": "staging"
        }
      ]
    }
  },
  "enableDryRunInList": false
}

Schema

Top level

| Field | Type | Required | Description | | -------------------- | --------- | -------- | ---------------------------------------------------- | | environments | object | Yes | Map of environment name to environment config | | enableDryRunInList | boolean | No | Prompt for dry run mode when using swx list |

Environment

| Field | Type | Required | Description | | -------------- | -------- | -------- | ---------------------------------------- | | description | string | No | Human-readable label for the environment | | replacements | array | Yes | List of replacement rules (minimum 1) |

Replacement

| Field | Type | Required | Description | | ------- | ---------- | -------- | ------------------------------------------------------------------ | | files | string[] | Yes | Paths to files the replacement applies to (minimum 1) | | regex | string | Yes | Regex in /pattern/flags format, e.g. "/(dev\|staging)/" | | value | string | Yes | The string to substitute for every match |

Regex format

Regexes must be written in slash-delimited format:

/(pattern)/

Examples:

/(dev|staging)/
/^API_URL=.*/m
/(development|production)/

Requirements

• Node.js >= 20