Configuration

Unreach supports configuration files to customize analysis behavior without command-line flags.

Supported Configuration Files

Unreach looks for configuration files in the following order (first found is used):

1. unreach.config.js - JavaScript configuration file
2. unreach.config.ts - TypeScript configuration file (requires ts-node to be installed)

Configuration files should be placed in the project root directory (same level as package.json).

Configuration Schema

interface UnreachConfig {
  ignore?: {
    files?: string[];
    packages?: string[];
    exports?: string[];
    functions?: string[];
    variables?: string[];
    imports?: string[];
    types?: string[];
    cssClasses?: string[];
    assets?: string[];
  };
  entryPoints?: string[];
  excludePatterns?: string[];
  rules?: {
    unusedPackages?: boolean;
    unusedImports?: boolean;
    unusedExports?: boolean;
    unusedFunctions?: boolean;
    unusedVariables?: boolean;
    unusedFiles?: boolean;
    unusedConfigs?: boolean;
    unusedScripts?: boolean;
    unusedTypes?: boolean;
    unusedCSSClasses?: boolean;
    unusedAssets?: boolean;
  };
  fix?: {
    enabled?: boolean;
    backup?: boolean;
    interactive?: boolean;
  };
  testFileDetection?: {
    enabled?: boolean;
    patterns?: string[];
  };
  maxFileSize?: number;
  watchRateLimit?: number;
}

JavaScript Configuration Example

Create unreach.config.js in your project root:

module.exports = {
  ignore: {
    files: ["**/*.test.ts", "**/fixtures/**"],
    packages: ["@types/*"],
    exports: ["**/index.ts"],
    functions: ["main"],
    variables: [],
    imports: [],
    types: [],
    cssClasses: [],
    assets: []
  },
  entryPoints: ["src/index.ts"],
  excludePatterns: ["**/node_modules/**", "**/dist/**"],
  rules: {
    unusedPackages: true,
    unusedImports: true,
    unusedExports: true,
    unusedFunctions: true,
    unusedVariables: true,
    unusedFiles: true,
    unusedConfigs: true,
    unusedScripts: true,
    unusedTypes: true,
    unusedCSSClasses: true,
    unusedAssets: true
  },
  testFileDetection: {
    enabled: true,
    patterns: ["**/*.test.ts", "**/*.spec.ts", "**/__tests__/**"]
  },
  maxFileSize: 10 * 1024 * 1024, // 10MB
  watchRateLimit: 1 // scans per second
};

TypeScript Configuration Example

Create unreach.config.ts:

import type { UnreachConfig } from "unreach";

const config: UnreachConfig = {
  ignore: {
    files: ["**/*.test.ts"],
    packages: ["@types/*"]
  },
  entryPoints: ["src/index.ts"],
  rules: {
    unusedPackages: true,
    unusedImports: true
  },
  testFileDetection: {
    enabled: true,
    patterns: ["**/*.test.ts", "**/*.spec.ts"]
  },
  maxFileSize: 10 * 1024 * 1024,
  watchRateLimit: 1
};

export default config;

Note: For TypeScript config files, you need ts-node installed:

npm install -D ts-node
# or
yarn add -D ts-node
# or
pnpm add -D ts-node

Configuration Options

ignore

Specify patterns to ignore during analysis:

• files - Glob patterns for files to ignore
• packages - Package names or patterns to ignore (supports glob patterns like @types/*)
• exports - Export names or file patterns to ignore
• functions - Function names to ignore
• variables - Variable names to ignore
• imports - Import paths to ignore
• types - Type names to ignore
• cssClasses - CSS class names to ignore
• assets - Asset file paths to ignore

entryPoints

Custom entry points for analysis. If not specified, Unreach will auto-detect from package.json and tsconfig.json.

excludePatterns

Glob patterns for files/directories to exclude from analysis entirely.

rules

Enable or disable specific analysis rules:

• unusedPackages - Detect unused npm packages
• unusedImports - Detect unused imports
• unusedExports - Detect unused exports
• unusedFunctions - Detect unused functions
• unusedVariables - Detect unused variables
• unusedFiles - Detect unused files
• unusedConfigs - Detect unused config keys
• unusedScripts - Detect unused npm scripts
• unusedTypes - Detect unused TypeScript types
• unusedCSSClasses - Detect unused CSS classes
• unusedAssets - Detect unused asset files

All rules default to true if not specified.

testFileDetection

Configure automatic test file exclusion:

• enabled - Enable/disable test file detection (default: true)
• patterns - Glob patterns for test files (default: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx", "**/__tests__/**"])

maxFileSize

Maximum file size in bytes to parse. Files exceeding this limit will be skipped. Default: 10 * 1024 * 1024 (10MB).

watchRateLimit

Maximum number of scans per second in watch mode. Default: 1 (1 scan per second).

fix

Configuration for auto-fix feature (coming soon):

• enabled - Enable auto-fix
• backup - Create backup before fixing
• interactive - Prompt before fixing

Disable Configuration

Use the --no-config flag to ignore configuration files:

unreach scan --no-config

Configuration Validation

Unreach validates your configuration file and will show helpful error messages if there are issues:

❌ Error: Invalid configuration in unreach.config.js:
  - "ignore" must be an object
  - "entryPoints" must be an array
  - "rules" must be an object

Common Patterns

Ignore All Test Files

module.exports = {
  ignore: {
    files: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx", "**/__tests__/**"]
  }
};

Ignore Type Definition Packages

module.exports = {
  ignore: {
    packages: ["@types/*"]
  }
};

Custom Entry Points

module.exports = {
  entryPoints: ["src/index.ts", "src/cli.ts", "src/server.ts"]
};

Disable Specific Rules

module.exports = {
  rules: {
    unusedConfigs: false,
    unusedScripts: false
  }
};

Configure File Size Limit

module.exports = {
  maxFileSize: 5 * 1024 * 1024 // 5MB
};

Configure Watch Rate Limit

module.exports = {
  watchRateLimit: 2 // 2 scans per second
};