# Refactor a legacy Vue module with Atlas in 2026 > Atlas helps Vue developers refactor legacy modules by mapping public surfaces, pinning behavior with Vitest with Vue Test Utils, and applying structural changes safely. Refactoring a legacy Vue module without introducing regressions is a critical task in 2026, and Atlas, the terminal-native AI coding agent, streamlines this process by integrating directly with your existing Vue toolchain, including Vitest with Vue Test Utils for testing and pnpm for package management, ensuring behavior remains unchanged while restructuring. ## Key takeaways - Atlas uses lsp to map all public symbols and callers in your Vue project. - Pinning behavior with Vitest with Vue Test Utils and pnpm test is central to safe Vue refactoring. - apply_patch ensures structural changes to .vue files are applied safely, preventing file drift. - Atlas iteratively runs pnpm test after each change, catching Vue-specific regressions immediately. - The todowrite tool helps manage the migration of all callers to a refactored Vue module. - Every Atlas edit to your Vue codebase requires explicit approval via a unified diff. ## How to map a Vue module's public API with Atlas? In 2026, understanding a legacy Vue module's external dependencies is the first step in any refactor. Atlas uses the lsp tool's documentSymbol operation to precisely map the public surface of your .vue components, stores, and utility files, identifying all exported symbols. This ensures no caller is overlooked. Atlas begins a Vue module refactor by thoroughly indexing the codebase. Using its lsp tool, Atlas performs a documentSymbol operation on relevant Vue files, such as src/components/LegacyWidget.vue or src/stores/legacyStore.js. This process generates a comprehensive list of all exported functions, components, and data properties. Following this, Atlas executes findReferences on each identified symbol. For instance, it might search for references to LegacyWidget across your entire project, including other .vue files, JavaScript modules, and even TypeScript files. This meticulous enumeration of every callsite is crucial for preventing silent breakage, as Atlas identifies all points of interaction before any changes are proposed. The agent then tracks these callsites, ensuring a complete migration path for your Vue application. ## How does Atlas ensure Vue module behavior remains unchanged during refactoring? Proving that a refactor of a Vue module has not altered its behavior is paramount. Atlas achieves this by first establishing a green baseline in 2026. It uses the bash tool to run your existing Vitest with Vue Test Utils test suite, recording the successful output before any code modifications begin. Before Atlas makes any structural changes to a legacy Vue module, it prioritizes behavior preservation. The agent leverages the bash tool to execute the project's test runner, which for Vue applications is typically Vitest with Vue Test Utils. A command like pnpm test or vitest is run, and Atlas captures the output, verifying that all existing tests pass. This "green baseline" serves as a critical reference point. Throughout the refactoring process, Atlas will repeatedly re-run these tests after each significant change. This iterative verification, using the same pnpm test command, immediately flags any unintended behavioral shifts, allowing for prompt correction and ensuring the refactored Vue module continues to function identically to its original state. ## How does Atlas apply structural changes to Vue files safely? Applying structural changes to .vue files requires precision to avoid file corruption or unintended side effects. Atlas employs the apply_patch tool, which anchors on context lines, ensuring that proposed changes to a Vue component like src/components/OldFeature.vue are only applied if the file's content matches the expected state, preventing conflicts in 2026. When restructuring a Vue module, Atlas uses its apply_patch tool to make modifications. This tool is designed for robust and safe code changes. Instead of simply overwriting lines, apply_patch generates a unified diff where each hunk includes context lines from the original file. For example, if Atlas needs to move a script setup block or refactor a template section within src/components/MyComponent.vue, the patch will specify the exact surrounding code. If the target file has drifted,meaning its content no longer matches the context lines specified in the patch,apply_patch will fail with a "Failed to find context" error. This mechanism prevents Atlas from applying changes to an outdated or concurrently modified file, thereby safeguarding the integrity of your Vue codebase. This ensures that refactoring operations, such as migrating a component from Options API to Composition API, are applied only when safe. ## How does Atlas manage iterative refactoring and verification in Vue projects? Iterative verification is key to successful Vue refactoring, especially when dealing with complex components or stores. Atlas ensures continuous validation by re-running Vitest with Vue Test Utils tests with pnpm test after each apply_patch operation, and it tracks remaining work with a todowrite list, preventing incomplete migrations in 2026. Atlas adopts an iterative approach to refactoring Vue modules. After each successful application of a patch using apply_patch,for instance, moving a method from methods to setup() in src/components/MyComponent.vue,Atlas immediately re-runs the project's tests. This means executing pnpm test to trigger Vitest with Vue Test Utils and confirm that the latest change has not introduced any regressions. This frequent feedback loop is critical for catching issues early. Furthermore, Atlas uses the todowrite tool to maintain a list of remaining callsites that still need to be migrated or updated. This ensures that a partially refactored module, perhaps one where some callers still use the old API while others use the new, is never mistaken for a finished one. The todowrite list provides a clear roadmap for completing the refactor, ensuring all references to src/utils/legacy-helper.js are updated to src/utils/new-helper.js, for example. ## What safety and review mechanisms does Atlas provide for Vue refactoring? Atlas provides multiple layers of safety and review for Vue refactoring tasks, ensuring developer control and preventing unintended changes. Every Atlas tool call is permission-gated, and all file edits generate a unified diff for approval, giving Vue developers confidence in 2026. Atlas is built with developer control and safety at its core, especially for sensitive tasks like refactoring Vue modules. Before any tool, such as lsp or apply_patch, is executed, Atlas checks against allow, ask, and deny rules, giving you granular control over its actions. The agent first drafts a plan in a read-only plan agent, which you must approve before it switches to a build agent to execute changes. Crucially, for every file edit, whether it's modifying src/components/UserList.vue or src/router/index.js, Atlas computes a unified diff. This diff is then surfaced for your explicit approval before any changes are written to disk. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, providing a familiar workflow. Additionally, it snapshots file changes as git patches, allowing edits to be easily diffed and rolled back if necessary, offering robust safeguards for your Vue project. ## Steps 1. Map the legacy Vue module's public surface: Use Atlas's lsp tool to identify all exported symbols from your target Vue module, such as src/components/LegacyComponent.vue. Run atlas lsp documentSymbol src/components/LegacyComponent.vue to list its public API, then atlas lsp findReferences for each symbol to enumerate all callers. 2. Pin existing behavior with Vitest with Vue Test Utils: Before any changes, establish a green baseline. Execute your Vue project's tests using Atlas's bash tool: atlas bash "pnpm test". Record the successful test output to confirm current functionality. 3. Restructure the Vue module iteratively with apply_patch: Draft and apply structural changes to your .vue files, stores, or utility modules using atlas apply_patch . For example, refactor src/stores/oldStore.js to src/stores/newStore.js. Atlas's apply_patch will verify context lines, failing if the file has drifted. 4. Verify behavior after each change: Immediately after each apply_patch operation, re-run your Vitest with Vue Test Utils tests to catch regressions early. Use atlas bash "pnpm test" to ensure the refactored Vue module still passes all existing tests. 5. Track remaining callsites with todowrite: As you migrate callers to the new module structure, use atlas todowrite "Migrate callsite in src/views/Dashboard.vue to new API" to keep a clear list of outstanding work. This prevents a partially migrated Vue module from being considered complete. 6. Review and approve all changes: Before Atlas writes any changes to your Vue project, review the unified diff it presents. Approve the changes to src/components/RefactoredComponent.vue or src/utils/new-api.js to ensure they align with your refactoring goals. ## FAQ ### How does Atlas handle Vue Single-File Components (.vue files) during refactoring? Atlas processes Vue Single-File Components (.vue files) by leveraging its AST indexing capabilities via tree-sitter. This allows it to understand the structure of template, script, and style blocks, enabling precise refactoring operations like migrating from Options API to Composition API or restructuring script setup content. ### Can Atlas help migrate Vue 2 Options API components to Vue 3 Composition API? Yes, Atlas can assist in migrating Vue 2 Options API components to Vue 3 Composition API. It can read your .vue components and, with your approval, draft and apply patches to refactor data, methods, computed, and watch options into setup() functions and reactive state, ensuring a smooth transition. ### How does Atlas integrate with Vitest with Vue Test Utils for testing? Atlas integrates direct with Vitest with Vue Test Utils by using its bash tool to execute your pnpm test command. It captures test results to establish baselines, verify behavior after changes, and ensure that refactoring a Vue module does not introduce regressions. ### What if my Vue project uses TypeScript? Atlas is fully compatible with Vue projects using TypeScript. Its lsp tool understands TypeScript declarations, allowing it to accurately find references, map symbols, and apply type-safe refactoring changes across your .ts and