Library Exclusions

Refractor’s exclusion system lets you skip obfuscation for specific files or patterns. This is essential for generated code, platform-specific files, or libraries that must remain readable.

Overview

Exclusions are configured in the refractor section using glob patterns:

refractor:
  exclude:
    - "**/*.g.dart"
    - "**/*.freezed.dart"
    - "**/generated/**"

Excluded libraries are:

✅ Compiled normally
❌ Skipped by all obfuscation passes
✅ Included in the final binary

Exclusions apply only to project libraries. External dependencies (packages from pub.dev) are never obfuscated, regardless of exclusion rules.

Configuration

Syntax

refractor:
  exclude:
    - "pattern1"
    - "pattern2"

Type: List<String> (glob patterns)
Default: [] (no exclusions)

Example

refractor:
  exclude:
    - "**/*.g.dart"           # JSON serialization
    - "**/*.freezed.dart"     # Freezed models
    - "**/*.gr.dart"          # Auto Route
    - "**/generated/**"       # Generated directory
    - "lib/config/*.dart"     # Config files

Glob Pattern Syntax

Refractor uses glob patterns to match file paths.

Basic Patterns

*

Match any characters except /

"lib/*.dart"  # lib/main.dart ✓
               # lib/foo/bar.dart ✗

**

Match any characters including /

"**/*.dart"   # lib/main.dart ✓
               # lib/foo/bar.dart ✓

?

Match exactly one character

"lib/?.dart"  # lib/a.dart ✓
               # lib/ab.dart ✗

[abc]

Match one character from set

"lib/[abc].dart"  # lib/a.dart ✓
                   # lib/d.dart ✗

Pattern Examples

Exclude all .g.dart files

refractor:
  exclude:
    - "**/*.g.dart"

Matches:

lib/models/user.g.dart ✓
lib/api/response.g.dart ✓
test/fixtures/data.g.dart ✓

Doesn’t match:

lib/models/user.dart ✗
lib/g.dart ✗

Exclude a specific directory

refractor:
  exclude:
    - "lib/generated/**"

Matches:

lib/generated/routes.dart ✓
lib/generated/api/client.dart ✓

Doesn’t match:

lib/routes.dart ✗
lib/api/generated.dart ✗

Exclude multiple extensions

refractor:
  exclude:
    - "**/*.g.dart"
    - "**/*.freezed.dart"
    - "**/*.gr.dart"

Matches:

lib/user.g.dart ✓
lib/model.freezed.dart ✓
lib/routes.gr.dart ✓

Exclude specific files

refractor:
  exclude:
    - "lib/main.dart"
    - "lib/config/env.dart"

Matches:

lib/main.dart ✓
lib/config/env.dart ✓

Doesn’t match:

lib/app.dart ✗
lib/config/settings.dart ✗

Exclude test files

refractor:
  exclude:
    - "test/**"
    - "**/*_test.dart"

Matches:

test/widget_test.dart ✓
lib/utils_test.dart ✓

Test files are usually not included in production builds, so this is typically unnecessary.

Common Exclusion Patterns

Here are patterns for popular Dart code generation tools:

json_serializable

refractor:
  exclude:
    - "**/*.g.dart"

Excludes JSON serialization generated by json_serializable.

Freezed

refractor:
  exclude:
    - "**/*.freezed.dart"

Excludes union types and copyWith generated by freezed.

Auto Route

refractor:
  exclude:
    - "**/*.gr.dart"

Excludes route definitions generated by auto_route.

Moor/Drift

refractor:
  exclude:
    - "**/*.g.dart"
    - "**/*.drift.dart"

Excludes database code generated by drift.

Complete Example

For a typical Flutter project:

refractor:
  symbol_map: build/refractor_map.json
  exclude:
    # Code generation
    - "**/*.g.dart"
    - "**/*.freezed.dart"
    - "**/*.gr.dart"
    - "**/*.drift.dart"
    
    # Generated directories
    - "**/generated/**"
    - "lib/l10n/**"
    
    # Config files (if they contain sensitive patterns)
    - "lib/config/env.*.dart"

How Exclusions Work

Matching Process

Load configuration

Refractor reads exclude patterns from refractor.yaml.

Compile globs

Each pattern is compiled into a Glob matcher.

Filter libraries

During obfuscation, each library URI is checked against all patterns.

Skip if matched

If any pattern matches, the library is excluded from all passes.

Scope Rules

Exclusions only apply to project libraries. External packages are never obfuscated.

Project libraries include:

Files under the working directory
Libraries with URIs matching the pubspec.yaml package name

Example: If your pubspec.yaml has:

name: myapp

Then project libraries are:

✅ package:myapp/main.dart
✅ file:///path/to/project/lib/utils.dart
❌ package:flutter/widgets.dart (external)
❌ package:http/http.dart (external)

Pass Interaction

Excluded libraries are skipped by all obfuscation passes:

Rename

Classes, methods, fields keep original names

String Encrypt

String literals remain unencrypted

Dead Code

No dead code blocks inserted

Excluded libraries can reference obfuscated symbols from non-excluded libraries. Only the excluded file itself remains unchanged.

Why Exclude Files?

Generated Code

Code generators often rely on reflection, naming conventions, or JSON structure matching:

// user.g.dart (generated by json_serializable)
Map<String, dynamic> _$UserToJson(User instance) => <String, dynamic>{
  'name': instance.name,    // ← Must match JSON key
  'email': instance.email,  // ← Must match JSON key
};

Obfuscating field names breaks JSON serialization.

Always exclude generated files to avoid runtime errors.

Platform Channels

Flutter platform channels require exact method names:

// lib/platform/battery.dart
class BatteryPlugin {
  static const channel = MethodChannel('com.example/battery');
  
  Future<int> getBatteryLevel() {
    return channel.invokeMethod('getBatteryLevel');  // ← Must match native code
  }
}

Obfuscating method names breaks native communication.

Configuration Files

Files with string patterns that match encryption exclusions:

// lib/config/api.dart
class ApiConfig {
  static const baseUrl = 'https://api.example.com';  // ← Excluded from string_encrypt
}

You might exclude these to keep URLs readable in debugging.

Debugging & Inspection

Exclude files you need to inspect during development:

refractor:
  exclude:
    - "lib/debug/**"  # Keep debug tools readable

Verification

To verify which files are excluded:

Enable verbose logging:

refractor:
  verbose: true
  exclude:
    - "**/*.g.dart"

Run build:
```
refractor build
```

Check output:

✓ Processing lib/main.dart
✓ Processing lib/models/user.dart
⊘ Skipped lib/models/user.g.dart (excluded)
✓ Processing lib/api/client.dart
⊘ Skipped lib/api/response.g.dart (excluded)

Use verbose: true during initial setup to confirm exclusions work correctly.

Troubleshooting

Generated file is still obfuscated

Cause: Pattern doesn’t match the file path.Fix: Use verbose: true and check logs. Ensure pattern uses ** for subdirectories:

# Wrong
exclude:
  - "*.g.dart"  # Only matches root directory

# Correct
exclude:
  - "**/*.g.dart"  # Matches all directories

Exclusion pattern not working

Cause: Invalid glob syntax or typo.Fix: Test your pattern:

import 'package:glob/glob.dart';

void main() {
  final glob = Glob('**/*.g.dart');
  print(glob.matches('lib/user.g.dart'));  // true
}

External package is excluded

Cause: You’re trying to exclude a dependency.Fix: External packages are never obfuscated. Exclusions only affect project files.

Excluded file appears in symbol map

Cause: Another non-excluded file references it.Fix: This is expected. The excluded file’s symbols remain original, but they may appear in the map if referenced by obfuscated code.

Implementation Details

Exclusions are processed in RefractorConfig.toOptions() (/home/daytona/workspace/source/lib/src/config/model/refractor_config.dart:66):

PassOptions toOptions() {
  return PassOptions(
    excludeLibraryUriPatterns: refractor.exclude.map(Glob.new).toList(),
    // ...
  );
}

Each pattern is converted to a Glob instance and checked during library processing.

Best Practices

Exclude all generated code

Add patterns for every code generator you use:

exclude:
  - "**/*.g.dart"
  - "**/*.freezed.dart"
  - "**/*.gr.dart"

Use ** for subdirectories

Always use ** to match nested paths:

exclude:
  - "**/*.generated.dart"  # ✓ Matches all subdirs
  - "*.generated.dart"     # ✗ Only root

Test with verbose mode

Verify exclusions during initial setup:

refractor:
  verbose: true
  exclude:
    - "**/*.g.dart"

Document custom patterns

Add comments explaining project-specific exclusions:

exclude:
  # Platform channels - must match native method names
  - "lib/platform/**"
  
  # Code generation
  - "**/*.g.dart"

refractor.yaml

Complete configuration reference

String Encrypt Pass

Learn about string exclusion patterns

Get Started

Commands

Obfuscation

Configuration

Guides

​Overview

​Configuration

​Syntax

​Example

​Glob Pattern Syntax

​Basic Patterns

*

**

?

[abc]

​Pattern Examples

​Common Exclusion Patterns

​json_serializable

​Freezed

​Auto Route

​Moor/Drift

​Complete Example

​How Exclusions Work

​Matching Process

​Scope Rules

​Pass Interaction

Rename

String Encrypt

Dead Code

​Why Exclude Files?

​Generated Code

​Platform Channels

​Configuration Files

​Debugging & Inspection

​Verification

​Troubleshooting

​Implementation Details

​Best Practices

​Related Pages

refractor.yaml

String Encrypt Pass

Build docs developers (and LLMs) love

Overview

Configuration

Syntax

Example

Glob Pattern Syntax

Basic Patterns

Pattern Examples

Common Exclusion Patterns

json_serializable

Freezed

Auto Route

Moor/Drift

Complete Example

How Exclusions Work

Matching Process

Scope Rules

Pass Interaction

Why Exclude Files?

Generated Code

Platform Channels

Configuration Files

Debugging & Inspection

Verification

Troubleshooting

Implementation Details

Best Practices

Related Pages