Skip to main content

Configuration

Vipr is designed to work without a configuration file. When you do add one, it gives you a stable place to set defaults for output, thresholds, caching, ignore patterns, and plugin behavior.

Configuration file

Vipr reads vipr.config.json by walking up from the current working directory. JSON is the supported format, and vipr.config.json is the canonical filename for the CLI, VS Code extension, and Desktop app.

{
  "$schema": "https://vipr.dev/schemas/vipr-config.schema.json",
  "include": ["**/*.{ts,tsx,js,jsx,mjs,cjs,mts,cts}"],
  "exclude": ["**/*.test.{ts,tsx,js,jsx}"],
  "global": {
    "cache": true,
    "ignorePatterns": ["coverage/**", "generated/**"]
  },
  "output": {
    "format": "cli",
    "failThreshold": 70,
    "failOnCritical": true
  },
  "plugins": {
    "core": {
      "thresholds": {
        "cyclomaticComplexity": {
          "warning": 8,
          "critical": 15
        }
      }
    }
  }
}

vipr init creates vipr.config.json at the Git repository root by default. If the current directory is not inside a Git repository, it writes to the current working directory.

What you can configure

Section What it controls
include File globs eligible for analysis
exclude File globs removed after inputs expand
global Cross-cutting behavior like caching, ignore patterns, grade boundaries, and debug
output Default format, severity filtering, compact JSON, and CI failure behavior
plugins Plugin enablement, thresholds, and weights
analyses Exact analysis ID enable/disable settings and analysis-specific config
budgets Config-managed metric budgets and documented exceptions
extends Layer one or more config files together
env Environment-specific overrides activated with vipr analyze --env <name>

Discovery and overrides

Vipr walks up from the current working directory looking for vipr.config.json. You can also point at a specific file or skip config loading entirely.

Use an explicit file when needed:

vipr analyze "src/**/*.{ts,tsx}" --config ./config/vipr.config.json

Skip config loading entirely:

vipr analyze "src/**/*.{ts,tsx}" --no-config

CLI flags always win over config file values. Only explicitly passed flags count as CLI overrides; Commander defaults do not overwrite config values.

Layered configs

Use extends to compose multiple config files. Relative paths are resolved from the file that declares them.

{
  "extends": "./base.config.json",
  "output": {
    "format": "json"
  }
}

Arrays replace rather than merge, while nested objects merge deeply.

Environment overrides

The shared loader also understands env blocks. Use vipr analyze --env <name> to merge the matching environment override before explicit CLI flags are applied.

{
  "output": { "format": "cli" },
  "env": {
    "ci": {
      "output": {
        "format": "json",
        "failThreshold": 75,
        "failOnCritical": true
      }
    }
  }
}

Core properties

Key Type Default Notes
include string[] supported source-file glob Files eligible for analysis
exclude string[] [] Files removed after input expansion
global.debug boolean false Enables debug logging
global.cache boolean true Turns in-memory result caching on or off
global.cacheTTL number 3600000 Cache TTL in milliseconds
global.ignorePatterns string[] built-in list Adds paths and file patterns to skip
global.gradeBoundaries object { A: 25, B: 45, C: 65, D: 80 } Complexity cutoffs for grade letters
output.format cli | json | json-full | markdown cli Default output mode
output.minSeverity info | warning | critical info Lowest severity included in visible output
output.failThreshold number 0 Fails when any file score drops below the threshold
output.failOnCritical boolean false Fails when any critical insight is found
output.compact boolean false Minifies JSON output
plugins.<id>.enabled boolean true Disables plugin registration and execution
plugins.<id>.thresholds object plugin default Plugin-specific threshold overrides
plugins.<id>.weights object plugin default Plugin-specific scoring weight overrides
analyses.<id>.enabled boolean analysis default Enables or disables an exact analysis ID
analyses.<id>.config object analysis default Analysis-specific config
budgets array [] Config-managed budgets and exceptions

Built-in exclusions already skip dependency/build output, Storybook runtime config and builds, generated/codegen files, tests, snapshots, migrations, editor/agent config, docs, public assets, and fixtures. Add exclude or global.ignorePatterns only for project-specific noise beyond those defaults.

Plugin and analysis config

plugins is keyed by plugin ID. Each plugin owns its own schema, thresholds, and weights. analyses lets you enable or disable named analyses and pass analysis-specific config without changing the plugin-wide defaults.

Exact analysis IDs:

Plugin IDs
Core core-cyclomatic, core-cognitive, core-halstead, core-maintainability, core-functions, core-dead-code
React react-accessibility, react-anti-patterns, react-coupling, react-dataflow, react-hooks, react-identity, react-migration, react-performance, react-reliability, react-security, react-structural, react-technical-debt, react-temporal
Next.js nextjs-config, nextjs-data-fetching, nextjs-migration, nextjs-rendering, nextjs-route-structure, nextjs-security, nextjs-server-client
TypeScript ts-declaration-shape, ts-generics, ts-import-discipline, ts-module-augmentation, ts-structural-quality, ts-type-complexity, ts-type-guards, ts-type-safety, ts-utility-types

Budgets and exceptions

Budgets live under the canonical budgets key. VS Code reads and writes this key; Desktop imports config-managed budgets as deterministic read-only entries while preserving budgets created in the app.

{
  "budgets": [
    {
      "id": "complexity-limit",
      "metric": "complexity",
      "threshold": 20,
      "warningThreshold": 15,
      "scope": { "type": "pattern", "value": "src/**" },
      "exceptions": [
        {
          "filePattern": "src/legacy/**",
          "reason": "Tracked migration",
          "expiresAt": "2026-12-31"
        }
      ]
    }
  ]
}

Excepted budget violations remain visible as suppressed records with the current value, threshold, reason, and expiry so the exception stays reviewable.

Generate a starter file

Vipr can scaffold a starter config for you:

vipr init

For a non-interactive setup:

vipr init --preset strict --quiet

See CLI Commands for the full init option list.

Documentation