#Configuration: Overview

Configuration is set by JSON. Config files can be written in TypeScript, JavaScript, JSON, or JSONC.

See Project Configuration and Workspace Configuration for more information on the purpose of each field.

#Quick Examples

#Project Configuration

The project configuration is for project-wide settings.

// path/to/your/project/pacwich.project.ts

import { defineProjectConfig } from "pacwich/config";

export default defineProjectConfig({
  defaults: {
    parallelMax: 4,
    affectedBaseRef: "my-branch"
  },
  workspacePatternConfigs: [
    {
      patterns: [
        "path:libraries/frontend/**/*"
      ],
      config: {
        tags: [
          "frontend",
          "library"
        ]
      }
    }
  ]
});

#Workspace Configuration

Workspace configurations are defined in the directory of a workspace.

// path/to/your/project/workspace/pacwich.workspace.ts

import { defineWorkspaceConfig } from "pacwich/config";

export default defineWorkspaceConfig({
  alias: "myApp",
  tags: [
    "my-tag"
  ],
  scripts: {
    start: {
      order: 10
    },
    test: {
      order: 20
    }
  },
  rules: {
    workspaceDependencies: {
      allowPatterns: [
        "my-workspace-a",
        "tag:my-tag",
        "path:my-path/**/*",
        "not:tag:my-excluded-tag"
      ]
    }
  }
});

#Config Locations / File Types

#Configuration locations

Configuration files can be read from the following location. The first to be resolved in this order will be used:

1. TypeScript file: pacwich.<name>.ts
2. JavaScript file: pacwich.<name>.js
3. JSONC file: pacwich.<name>.jsonc
4. JSON file: pacwich.<name>.json
5. package.json key: package.json["<key>"]

#Value Resolution

Values related to configuration are resolved in the following order of precedence:

1. An explicit CLI or API argument/option passed to a method/function/command
2. A value provided in a configuration file
3. A value provided via an environment variable, if applicable
4. The generic default value, if applicable

---

#Debugging Configuration

You can use the CLI command pacwich config debug to print all resolved JSON for configuration.

See the CLI reference for more information.

---

#Security and Performance of TypeScript/JavaScript configs

Keep in mind that TypeScript and JavaScript config files offer the most power and flexibility but both execute code and can affect pacwich's performance if configs are slow to resolve.

#Performance

The average pacwich project that uses config straightforwardly should not experience performance issues due to TS/JS config, unless very heavy processing or async logic is used within them. Keep in mind that slow config files will slow down all pacwich operations, including shell completions that are project-aware.

If you happen to need dynamic configs that slow down pacwich, consider using a separate process to generate JSON/JSONC configs dynamically to take the load off of pacwich's resolution.

#Security

If you may be interacting with pacwich monorepos that are untrusted, you can set environment variable PACWICH_DISABLE_EXECUTABLE_CONFIGS_DEFAULT to true to disable loading TS/JS config files altogether. There is also the CLI global flag for this. Of course, a malicious repository already has a large variety of attack vectors beyond just a pacwich config, but this exists as an optional guard against arbitrary code execution.