Auto Route Finder

A VSCode extension that helps Flutter developers easily jump to the definition of classes generated by the AutoRoute package.

Features

• Automatic Route Detection: Monitors Dart files for *Route class names (e.g., HomeRoute, SettingsRoute)
• Inline CodeLens (smart): Displays "Jump to Definition" only when the corresponding widget file can be resolved from routes.gr.dart
• Indexed Discovery (no hardcoding): Uses VS Code’s workspace index to discover routes.gr.dart anywhere in the workspace (no hardcoded paths)
• Multi-file Support: Handles multiple routes.gr.dart files; the correct file is resolved by searching all indexed results
• Smart Navigation: Converts widget names to snake_case, resolves imports from routes.gr.dart, maps package:… to file paths (supports nested structures), and opens the widget file
• Conflict Detection: Automatically hides CodeLens when multiple widgets match the same route to prevent ambiguity
• Real-time Updates: Refreshes automatically when any routes.gr.dart file is saved
• Zero Configuration: Works out of the box with standard AutoRoute setups

How It Works

1. Discover AutoRoute configuration

   • Scans .dart files for @AutoRouterConfig(...) and extracts replaceInRouteName, e.g. 'Screen|Page,Route'.
   • Supports multiple source suffixes before the comma (e.g., Screen|Page|View) and a generated suffix after the comma (e.g., Route).
   • From the annotation file name (e.g., app_router.dart), derives the paired generated file (e.g., app_router.gr.dart).

2. Index generated imports

   • Reads imports from the paired *.gr.dart file.
   • Converts package:foo/bar.dart → lib/bar.dart and verifies files exist locally.

3. Detect route classes in editors

   • Detects route tokens with the generated suffix (e.g., HomeRoute).
   • CodeLens only appears on route classes, not on widget classes (e.g., HomePage, HomeScreen).
   • Skips AutoRoute itself.

4. Resolve targets

   • For HomeRoute, computes base Home and tries all source suffixes (e.g., HomeScreen, HomePage) against imports from the paired *.gr.dart file(s).
   • Conflict detection: If multiple widgets match (e.g., both HomePage and HomeScreen exist), CodeLens is hidden to avoid ambiguity.
   • Shows CodeLens only when exactly one widget file is found and resolvable.

5. Navigate

   • Opens the resolved file and focuses the widget class.

If no generated route files are found, a notification is shown on activation.

Requirements

• Flutter project using AutoRoute
• At least one generated route file (.gr.dart extension) containing the // AutoRouterGenerator comment

Usage

1. Install the extension
2. Open a Dart file containing route references (e.g., CompaniesRoute())
3. Look for the CodeLens button above the route class (e.g., "🔗 Jump to CompaniesScreen")
4. Click the button to navigate to the corresponding widget file

Example

// In your Dart file
context.router.push(const CompaniesRoute());

// The extension will:
// 1. Detect CompaniesRoute
// 2. Show "🔗 Jump to CompaniesScreen" button
// 3. When clicked, find this import in routes.gr.dart:
//    import 'package:myapp/features/companies/screens/companies_screen.dart' as _i4;
// 4. Convert to: lib/features/companies/screens/companies_screen.dart
// 5. Open the file and focus on the CompaniesScreen class

File Structure Support

The extension automatically handles various project structures by reading import paths from routes.gr.dart:

lib/
├── routes.gr.dart
├── features/
│   ├── companies/
│   │   └── screens/
│   │       └── companies_screen.dart
│   └── profile/
│       └── screens/
│           └── profile_detail_screen.dart
└── main.dart

Troubleshooting

No CodeLens Buttons Appear

1. Ensure generated route files exist: The extension shows a notification if no .gr.dart files with // AutoRouterGenerator are found.
2. Verify AutoRoute generation: Make sure your routes are generated and imports exist for your widgets.
3. Open the correct workspace root: Discovery runs from the VS Code workspace folder(s).

"No file path found" Error

1. Check import statements in your routes.gr.dart for the target widget (snake_case match).
2. Verify file naming: Widget files should be in snake_case (e.g., companies_screen.dart).
3. Confirm file exists at the path resolved from the import (package:… → lib/…).

Multi-root or multiple generated route files

• The extension scans all discovered .gr.dart files containing // AutoRouterGenerator and uses the first matching import.
• If you have multiple apps/packages, ensure imports are unambiguous.

Limitations

• Multi-project workspaces: Project scoping is experimental. In multi-project/mono-repo setups, route resolution can cross project boundaries or miss matches. For now, opening a single project (one pubspec.yaml) yields the most reliable results.
• The extension will only work when widgets are in their own file, and widget names must be unique. If you have two widgets with the same name, the extension will hide CodeLens to avoid conflicts.
• CodeLens only appears on route classes (e.g., HomeRoute), not on widget classes (e.g., HomePage, HomeScreen). This ensures navigation always goes from route → widget, following AutoRoute's generation pattern. Example:

// file name: home_screen.dart

@RoutePage()
class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Container();
  }
}

Debugging

• Open Help > Toggle Developer Tools to view logs.
• Look for messages prefixed with "Auto Route Finder:" when resolving imports and opening files.

Release Notes

See CHANGELOG.md for detailed release notes.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - see LICENSE file for details.