Skip to main content
The refractor.yaml file is the primary configuration file for Refractor. It controls which obfuscation passes run, how they behave, and where output is written.
The configuration file is required. Refractor will fail if refractor.yaml is missing, empty, or contains invalid YAML.

​
Creating a Configuration File

Generate a starter template: 
refractor init
This creates refractor.yaml in your current directory with sensible defaults.

​
Configuration Structure

The configuration file has two main sections:

refractor

Global settings: symbol map path, exclusions, and verbosity

passes

Enable/disable obfuscation passes and configure their behavior

​
Default Template

Here’s the complete default configuration generated by refractor init: 
# Refractor configuration
# Modeled after analysis_options.yaml for Dart developer familiarity.
# See: https://github.com/yardexx/refractor

# Global tool settings.
refractor:
  # Output path for the symbol map (original → obfuscated name mapping).
  # symbol_map: build/refractor_map.json

  # Scope is fixed to the current project (pubspec package + current folder).

  # Library URI/path exclusions using glob patterns.
  # exclude:
  #   - "**/*.g.dart"
  #   - "**/*.freezed.dart"

# Pass configuration — enable/disable and configure each pass.
# Use `true` for defaults, `false` to disable, or a map for custom settings.
passes:
  rename:
    # preserve_main: true

  string_encrypt: true
  # string_encrypt:
  #   xor_key: 0x5A
  #   exclude_patterns:
  #     - "^https://"

  dead_code: false

# Verbose logging.
# verbose: false

​
Global Settings (refractor)

The refractor section configures global tool behavior.

​
symbol_map

Type: String
Default: symbol_map.json Path where the symbol map JSON file will be written. The symbol map contains the mapping of obfuscated names back to their original identifiers. 
refractor:
  symbol_map: build/refractor_map.json
See Symbol Map for details on the output format.

​
exclude

Type: List<String>
Default: [] List of glob patterns to exclude libraries from obfuscation. Useful for generated files that shouldn’t be obfuscated. 
refractor:
  exclude:
    - "**/*.g.dart"
    - "**/*.freezed.dart"
    - "**/generated/**"
Exclusions apply only to project libraries. External dependencies are never obfuscated.
See Library Exclusions for pattern syntax and examples.

​
verbose

Type: bool
Default: false Enable detailed logging during obfuscation. 
refractor:
  verbose: true
When enabled, Refractor logs:
  • Which libraries are being processed
  • Symbol rename operations
  • String encryption transformations
  • Dead code insertions

​
Obfuscation Scope

Refractor’s obfuscation scope is fixed to the current project:
  • Libraries matching the name in pubspec.yaml
  • Files under the working directory
External packages (dependencies from pub.dev or other sources) are never obfuscated, even if not explicitly excluded.

​
Pass Configuration (passes)

The passes section controls which obfuscation transformations run and how they behave.

​
Pass Syntax

Each pass supports three configuration styles:
1

Enable with defaults

Set to true to enable with default options:
passes:
  string_encrypt: true
2

Disable

Set to false to disable the pass:
passes:
  dead_code: false
3

Custom configuration

Use a map to provide custom options:
passes:
  rename:
    preserve_main: false
If a pass is missing from the configuration, it’s treated as disabled.

​
Available Passes

​
rename

Rewrites class, method, and field identifiers to short, meaningless names. Options:
  • preserve_main (bool, default: true)
    Keep the main() function name unchanged. Set to false to obfuscate it.
Example: 
passes:
  rename:
    preserve_main: true
Effect: 
// Before
class UserService {
  String getUserName() => 'Alice';
}

// After (example)
class a {
  String b() => 'Alice';
}

​
string_encrypt

Replaces string literals with XOR-encoded byte arrays and injects a runtime decoder. Options:
  • xor_key (int, default: 0x5A)
    XOR key for string encryption. Must be a valid byte value (0x00-0xFF).
  • exclude_patterns (List<String>, default: [])
    Regular expressions to exclude strings from encryption. Useful for URLs, file paths, or configuration strings.
Example: 
passes:
  string_encrypt:
    xor_key: 0x5A
    exclude_patterns:
      - "^https://"        # Don't encrypt URLs
      - "^package:"        # Don't encrypt package URIs
      - "^/data/"          # Don't encrypt absolute paths
Effect: 
// Before
final message = 'Hello World';

// After (example)
final message = _decryptString([0x32, 0x3f, 0x36, 0x36, 0x3b, ...]);
Use exclude_patterns for strings that must remain readable (e.g., API endpoints, deep links, file paths).

​
dead_code

Inserts unreachable branches and statements to hinder static analysis and decompilers. Options:
  • max_insertions_per_procedure (int, default: 2)
    Maximum number of dead code blocks to insert per function/method.
Example: 
passes:
  dead_code:
    max_insertions_per_procedure: 2
Effect: 
// Before
void processData() {
  print('Processing');
}

// After (example)
void processData() {
  if (false) {
    throw 'unreachable';
  }
  print('Processing');
  if (1 > 2) {
    return;
  }
}
Dead code insertion may increase binary size. Start with low values (1-2) and measure impact.

​
Complete Example

Production-ready configuration with all passes enabled: 
refractor:
  symbol_map: build/refractor_map.json
  verbose: false
  exclude:
    - "**/*.g.dart"
    - "**/*.freezed.dart"
    - "**/generated/**"

passes:
  rename:
    preserve_main: true

  string_encrypt:
    xor_key: 0x7F
    exclude_patterns:
      - "^https://"
      - "^http://"
      - "^package:"
      - "^dart:"
      - "^file://"

  dead_code:
    max_insertions_per_procedure: 2

​
Validation and Error Handling

Refractor validates the configuration file at startup:
1

File existence

Checks if refractor.yaml exists in the current directory.Error: Configuration file not found: refractor.yamlFix: Run refractor init to create it.
2

YAML syntax

Parses the YAML structure.Error: Invalid configuration YAMLFix: Check for syntax errors (indentation, quotes, colons).
3

Schema validation

Validates field names, types, and required values.Error: Invalid configuration at refractor.yaml: <details>Fix: Check field names (use snake_case: preserve_main, not preserveMain) and types.

​
Common Errors

The file exists but has no content.Fix: Add at least a minimal configuration:
refractor: {}
passes:
  rename: true
You referenced a pass that doesn’t exist.Fix: Valid pass names are: rename, string_encrypt, dead_code.
The file doesn’t have a proper YAML structure.Fix: Start with refractor: and passes: top-level keys.

​
Field Naming Convention

All configuration fields use snake_case (e.g., preserve_main, xor_key, symbol_map).
This follows Dart’s YAML configuration conventions (similar to analysis_options.yaml).

Symbol Map

Learn about the obfuscation mapping file

Library Exclusions

Exclude files from obfuscation

Build docs developers (and LLMs) love

Get started for freeTalk to us