2026-04-05 5 MIN READ

Surgical Refactoring: Migrating Legacy React to Next.js with Gemini CLI

We’ve all been there: staring at a legacy/ directory filled with 2021-era React components, .scss files with specific absolute positioning, and window.location.href hacks. You want the performance of Next.js 15 and the type safety of TypeScript, but the thought of manually remapping hundreds of CSS classes to Tailwind is enough to make any dev procrastinate.

In my recent portfolio update, I faced this exact hurdle. The goal wasn't a total rewrite—it was a surgical refactoring. I wanted to keep the proven logic but modernize the implementation.

Here is how I used Gemini CLI to automate the most painful part of the migration: remapping legacy styles.

1. The Context Injection

The secret to a successful "surgical" update is providing the AI with enough local context. Instead of just asking it to "make this a Next.js component," I fed the CLI both the legacy .js file and its corresponding .scss styles.

Take my legacy Logo component:

  • Logo.js: Managed navigation via window.location.href.
  • logo.scss: Contained complex absolute positioning like left: 1361px and specific media queries for mobile responsiveness.

By reading both files into the CLI's context, the agent understood not just the structure of the component, but the intent of its design.

2. Intelligent Style Remapping

The biggest time-saver was the automated CSS-to-Tailwind translation. Manual remapping usually involves:

  1. Identifying the pixel value.
  2. Finding the nearest Tailwind equivalent (e.g., 32px -> top-8).
  3. Handling media queries (e.g., @media only screen and (max-width: 600px) -> sm:flex).

Gemini CLI performed this mapping instantly. It converted the absolute left: 1361px into a more modern responsive layout while preserving the border-radius: 70px and hover states.

The result? A clean Logo.tsx that utilized the next/image component for optimized loading and next/link for client-side navigation—all while maintaining the exact visual identity of the original site.

3. The Validation Loop

A refactor is only "surgical" if it doesn't break the surrounding body. Because Gemini CLI has access to my shell, it didn't just write the code and walk away. It:

  1. Generated the Types: It inferred the props and defined the TypeScript interfaces.
  2. Fixed Imports: It updated the image import path to work with the Next.js public/ directory structure.
  3. Ran the Build: It executed npm run build to ensure no "missing module" or "type mismatch" errors were introduced.

Why This Matters

For developers, time is the most valuable currency. By offloading the mechanical task of "translating" styles and boilerplate to an agent that understands your codebase, you free yourself up for higher-level architectural decisions.

We’re moving toward a world where "legacy debt" isn't a permanent weight on a project. With the right tools and a surgical approach, we can keep our applications modern, fast, and maintainable without losing a week to manual refactoring.

Ready to try it? Start with your smallest component. Inject the context, let the CLI remap the styles, and watch your legacy code transform into a modern Next.js powerhouse in seconds.