How does Atlas handle Flutter widgets and state during migration?

Atlas indexes your Flutter codebase using tree-sitter, understanding AST declarations for widgets, state management (like `Provider` or `Bloc`), and other Dart constructs. This allows its `lsp` tool to accurately find references within your `StatefulWidget`s, `StatelessWidget`s, and state classes, ensuring migrations are semantically correct across your Flutter application.

Can Atlas integrate with my existing `pubspec.yaml` dependencies in Flutter?

Yes, Atlas is designed to operate within your existing Flutter project structure. It reads your `pubspec.yaml` and understands your `pub` dependencies. While Atlas focuses on code migration, it respects your project's configuration and can help identify if a deprecated API is tied to a specific package version, guiding you to update your `pubspec.yaml` as part of the migration.

What if a deprecated Flutter API is used dynamically or via strings?

Atlas employs a hybrid approach for enumeration. Its `lsp` tool provides precise, semantic references from the language server. To catch dynamic or string-based usages that the language server might miss, Atlas cross-checks the results with a `grep` command, ensuring a comprehensive sweep of your Flutter codebase for all potential calls to the deprecated API.

How does Atlas ensure my Flutter tests pass after a migration?

Atlas integrates directly with the `flutter test` runner. After each individual file modification during a migration, Atlas uses the `bash` tool to execute `flutter test` for the affected test files. A `todowrite` entry is only marked complete once its corresponding tests pass, providing immediate feedback and guaranteeing the functional integrity of your Flutter application throughout the process.

Is Atlas compatible with `dart format` for Flutter code?

Yes, Atlas is fully compatible with `dart format`. While Atlas focuses on the migration logic, it operates on your Dart source files. After Atlas applies changes, you can run `dart format .` as usual to ensure your Flutter codebase maintains consistent formatting, or integrate it into your pre-commit hooks, as Atlas can stage and create commits on your behalf.

How does Atlas prevent accidental changes to my Flutter project?

Atlas incorporates several safety mechanisms. It drafts a plan in a read-only agent and asks for approval before executing. Every tool call is permission-gated. For file edits, Atlas computes a unified diff and surfaces it for your approval before writing. Additionally, `apply_patch` fails explicitly if the file context has drifted, preventing misapplications in your Flutter codebase.

Migrate a Deprecated API Across Every Callsite in Flutter with Atlas in 2026

In 2026, migrating a deprecated API across every callsite in a Flutter application is streamlined with Atlas, which leverages the `lsp` tool to enumerate all usages, tracks progress with `todowrite`, and applies changes with `apply_patch`, all while integrating with `flutter test` for immediate verification and ensuring your `pubspec.yaml` dependencies remain consistent.

How Atlas Finds All Deprecated API Calls in Flutter

Atlas identifies every callsite of a deprecated Flutter API using its `lsp` tool, which queries the language server for a complete reference list. This method, powered by tree-sitter AST declarations, ensures that in 2026, no usage within your Flutter project's widgets, state, or utility functions is overlooked.

When you embark on a migration in a Flutter codebase, the first critical step is a comprehensive enumeration of all calls to the deprecated symbol. Atlas achieves this by leveraging its `lsp` tool, which connects to the language server protocol. This allows Atlas to perform a `findReferences` operation on the specific deprecated symbol, yielding a complete and accurate set of callers. Unlike simple text searches, Atlas's indexing, built on AST declarations using tree-sitter, understands the code's structure, ensuring semantic accuracy. For instance, if you're deprecating a function within a `StatefulWidget` or a specific `Provider` method, Atlas will precisely locate every instance where that function is invoked. After the `lsp` tool provides its list, Atlas cross-checks with `grep` to catch any dynamic or string-based usages that might evade the language server, providing a robust, two-pronged approach to enumeration across your Flutter project's `lib/` directory and beyond.

Tracking Deprecated Flutter API Migrations with Atlas

Atlas ensures no deprecated Flutter API callsite is silently skipped during migration by creating a `todowrite` entry for each identified usage. This system provides visible, granular progress, allowing Flutter developers in 2026 to track every change from `pubspec.yaml` updates to widget refactors.

Once Atlas has enumerated all calls to the deprecated Flutter API, it transforms this list into actionable work items using the `todowrite` tool. For every identified callsite, Atlas generates a distinct `todowrite` entry. This approach is crucial for large Flutter codebases where a migration might span dozens or even hundreds of files, affecting various parts of your widget tree or state management logic. By creating individual entries, Atlas makes partial progress visible, preventing the common pitfall of missing a callsite or losing track of completed work. As you or Atlas address each entry, its status can be updated, providing a clear audit trail of the migration's progress. This ensures that whether you're updating a `MaterialApp` configuration or refactoring a `ChangeNotifier` method, every step is accounted for.

Safely Migrating Flutter Code with Atlas's apply_patch

Atlas migrates each deprecated Flutter API callsite using its `apply_patch` tool, which generates context-anchored patches. This method, vital for Flutter projects in 2026, ensures that changes are applied precisely, failing explicitly rather than misapplying if the file has drifted from its expected state.

The core of the migration process in Flutter with Atlas lies in the `apply_patch` tool. For each `todowrite` entry, Atlas drafts a specific patch designed to replace the deprecated API call with its modern equivalent. These patches are not blind text replacements; they are context-anchored, meaning they rely on the surrounding lines (`hunk's context`) and the exact `old_lines` to ensure a precise application. If the target file has been modified since the patch was generated, causing the expected context or old lines to no longer match, `apply_patch` will explicitly throw a 'Failed to find expected lines' error. This robust safety mechanism prevents misapplications that could introduce subtle bugs into your Flutter application's `lib/` directory. Before any changes are written, Atlas computes a unified diff for every file edit and surfaces it for your approval, giving you complete control over the modifications to your `pubspec.yaml`, widget files, or any other Dart source.

Verifying Flutter API Migrations with `flutter test`

After each file modification during a deprecated Flutter API migration, Atlas immediately runs affected tests using the `bash` tool and the `flutter test` command. This rapid feedback loop, a cornerstone of safe development in 2026, ensures that every change to your Flutter codebase maintains functional integrity.

A critical safety measure in Atlas's migration workflow for Flutter is the immediate verification of changes. After Atlas applies a patch to a file, it doesn't just move on; it uses the `bash` tool to execute the `flutter test` command for the affected tests. This ensures that any unintended side effects of the migration are caught instantly. For example, if migrating a deprecated `setState` pattern inadvertently breaks a widget test in `test/widget_test.dart`, Atlas will report the failure. Only once the tests pass for that specific file's changes is the corresponding `todowrite` entry marked as complete. This iterative testing approach, integrated directly into the migration workflow, provides a high degree of confidence that your Flutter application remains stable and functional throughout the entire process, from updating `pub` dependencies to refactoring complex `Bloc` or `Riverpod` logic.

Ensuring Complete Deprecated API Removal in Flutter

To guarantee a complete migration, Atlas concludes the process by performing a final `grep` for the deprecated Flutter symbol across the entire codebase. This crucial step, essential for maintaining clean code in 2026, confirms zero remaining hits before the old implementation is safely deleted from your project.

The final stage of migrating a deprecated Flutter API with Atlas is to confirm its complete eradication from the codebase. After all `todowrite` entries have been addressed and their respective tests passed, Atlas performs a comprehensive `grep` for the deprecated symbol. This final sweep acts as a double-check, ensuring that no obscure or dynamically referenced instances were missed during the initial enumeration or subsequent patching. If the `grep` command returns zero hits, it provides definitive proof that the deprecated API has been entirely removed from your Flutter project. Only then does Atlas proceed to delete the old implementation file, ensuring your `lib/` directory is clean and free of legacy code. This meticulous approach guarantees that your Flutter application, its `pubspec.yaml` dependencies, and its entire structure are fully updated to the new API, ready for future development.

Step by step

01Run Atlas in your Flutter application directory, ensuring a `pubspec.yaml` is present and Atlas has indexed your widget tree and `pub` dependencies.
02Enumerate every callsite of the deprecated Flutter symbol using `atlas lsp findReferences <deprecated_symbol_name>` and cross-check with `atlas grep <deprecated_symbol_name>` for dynamic usages.
03Create a `todowrite` entry for each identified Flutter callsite: `atlas todowrite "Migrate <description_of_callsite_in_file.dart>"`.
04For each `todowrite` entry, use Atlas to draft and `apply_patch` the migration, ensuring the patch context matches the current Flutter file state.
05After each file modification, run affected tests using `bash -c "flutter test <path_to_affected_test_file>"` to verify the change.
06Mark the `todowrite` entry as complete only after the `flutter test` command passes for that specific migration: `atlas todowrite complete <todo_id>`.
07Once all `todowrite` entries are complete, perform a final verification with `atlas grep <deprecated_symbol_name>` to confirm zero remaining hits in your Flutter codebase.
08Delete the old implementation file of the deprecated API using `bash -c "rm <path_to_old_implementation.dart>"`.

Frequently asked questions

How does Atlas handle Flutter widgets and state during migration?: Atlas indexes your Flutter codebase using tree-sitter, understanding AST declarations for widgets, state management (like `Provider` or `Bloc`), and other Dart constructs. This allows its `lsp` tool to accurately find references within your `StatefulWidget`s, `StatelessWidget`s, and state classes, ensuring migrations are semantically correct across your Flutter application.
Can Atlas integrate with my existing `pubspec.yaml` dependencies in Flutter?: Yes, Atlas is designed to operate within your existing Flutter project structure. It reads your `pubspec.yaml` and understands your `pub` dependencies. While Atlas focuses on code migration, it respects your project's configuration and can help identify if a deprecated API is tied to a specific package version, guiding you to update your `pubspec.yaml` as part of the migration.
What if a deprecated Flutter API is used dynamically or via strings?: Atlas employs a hybrid approach for enumeration. Its `lsp` tool provides precise, semantic references from the language server. To catch dynamic or string-based usages that the language server might miss, Atlas cross-checks the results with a `grep` command, ensuring a comprehensive sweep of your Flutter codebase for all potential calls to the deprecated API.
How does Atlas ensure my Flutter tests pass after a migration?: Atlas integrates directly with the `flutter test` runner. After each individual file modification during a migration, Atlas uses the `bash` tool to execute `flutter test` for the affected test files. A `todowrite` entry is only marked complete once its corresponding tests pass, providing immediate feedback and guaranteeing the functional integrity of your Flutter application throughout the process.
Is Atlas compatible with `dart format` for Flutter code?: Yes, Atlas is fully compatible with `dart format`. While Atlas focuses on the migration logic, it operates on your Dart source files. After Atlas applies changes, you can run `dart format .` as usual to ensure your Flutter codebase maintains consistent formatting, or integrate it into your pre-commit hooks, as Atlas can stage and create commits on your behalf.
How does Atlas prevent accidental changes to my Flutter project?: Atlas incorporates several safety mechanisms. It drafts a plan in a read-only agent and asks for approval before executing. Every tool call is permission-gated. For file edits, Atlas computes a unified diff and surfaces it for your approval before writing. Additionally, `apply_patch` fails explicitly if the file context has drifted, preventing misapplications in your Flutter codebase.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Migrate a Deprecated API Across Every Callsite with Atlas (2026 Workflow)

How to migrate a deprecated API across every callsite with Atlas in 2026: the lsp tool's findReferences enumerates callers, todowrite tracks them, apply_patch migrates each one.

Atlas for Flutter in 2026

Discover Atlas for Flutter in 2026. This terminal-native AI coding agent helps Flutter developers build apps faster and safer, integrating with widgets, state, and the Dart toolchain.

Onboard to an Unfamiliar Flutter Codebase with Atlas in 2026

Master unfamiliar Flutter codebases quickly in 2026 with Atlas. Leverage semantic search, `pub` dependencies, and `flutter test` to build a mental model without reading every file.

Diagnose a Hanging or Long-Running Command in Flutter with Atlas in 2026

In 2026, Flutter developers use Atlas to diagnose hanging or slow `flutter test` and `pub` commands. Quickly identify if a process is blocked on input or genuinely slow, and get unstuck.

Automate GitHub Issue and Pull Request Triage in Flutter with Atlas in 2026

Streamline Flutter project maintenance in 2026. Atlas automates GitHub issue and pull request triage, integrating with `pub` and `flutter test` to keep your Dart codebase pristine and secure.

Run Atlas Headless in CI for Flutter Applications in 2026

Automate Flutter development in 2026 CI pipelines with Atlas. Run Atlas headless to get machine-readable output, integrate with `flutter test`, and manage `pub` dependencies safely.

Add a Regression Test for a Flutter Bug Fix with Atlas in 2026

Lock in Flutter bug fixes with robust regression tests using Atlas. Learn how to write failing tests, apply fixes, and validate with `flutter test` in 2026.

Audit a Flutter Repo with Parallel Subagents in Atlas, 2026

In 2026, Flutter developers use Atlas to sweep entire repositories for code problems. Leverage parallel subagents to audit pubspec.yaml dependencies, widget trees, and Dart code without blowing your main context window.

Browse this resource hub