CodeWalnut approach to Refactoring Front-end Applications

A real test for any frontend developer isn’t just about building new features. It’s about how well you can refactor an existing application. 

Writing fresh code is a challenge, but refactoring the code for software that customers are already using is a trickier challenge. 

You now deal with problems like legacy logic, regression risks and unpredictable side effects while getting rid of Tech Debt. 

At Codewalnut, we follow an 8-step approach whenever we refactor a frontend module. Also look up the FAQs at the end.

Guide to Refactoring:

Step 1. Understanding The Workflow: 

Before you touch the code, understand how things actually work.

Spend time exploring the application, test the main flows, click through key screens, and note what’s working (and what’s not).

Talk to your PM, QA, or any stakeholder who knows the product well. They’ll help you uncover hidden behaviors, edge cases, and the reasons why certain things exist the way they do.

The goal here is to build a clear picture of how the system behaves today.

Step 2. Testing (E2E Automation)

Once you understand how the system works, the next step is to make sure it stays that way.

Start with manual testing, go through key workflows, note bugs, and list parts that often break or behave unexpectedly.

Then, automate critical user journeys with frameworks like Playwright to prevent regressions and ensure stability.

Also we need to protect what’s already working so that future changes don’t break existing functionality. When you start refactoring, these tests will tell you if something breaks before your users do.

Step 3. Code Analysis

Once the workflows are clear, dive deep into the code.

Use tools like ESLint, SonarQube, JSCPD, Stylelint, Dev console and Lighthouse to assess code quality, duplication, complexity, and performance. These tools help you identify patterns that slow things down and areas that need cleanup.

The tools will help you uncover the hidden tech debts sitting in the codebase.

Pro tip: I have tried refactoring the entire repo using AI, but AI got confused, missed context or  gave half-baked changes. 

So I switched the gears and gave one file at a time to AI instead of the whole repo and below is the prompt I have used.

Copied to Clipboard!

You are an expert code reviewer specializing in React, TypeScript, and scalable frontend architecture.

Analyze the provided code file and recommend refactoring improvements that increase maintainability, scalability, performance, security, and user experience—without changing any existing behavior. All recommendations must follow SOLID principles and production-grade React best practices.

## 📌 Areas to Evaluate

### 1. Readability
- Improve naming, structure, and clarity.
- Suggest extraction into smaller components, hooks, or services.
- Recommend proper placement inside a clean project architecture.

### 2. Reduce Complexity
- Identify unnecessarily complex logic or deeply nested structures.
- Recommend simplifying patterns (early returns, splitting functions).
- Promote SRP-aligned separation of UI, data, state, and effects.

### 3. Eliminate Duplicate Code
- Identify repeated logic, formatting, or conditions.
- Suggest reusable utilities, hooks, or shared modules.

### 4. Performance Improvements
- Detect unnecessary re-renders.
- Recommend memoization only when it provides real value.
- Suggest splitting heavy components, lazy-loading, or code-splitting.
- Encourage modern data-fetching approaches (React Query / SWR).

### 5. Safety & Stability
- All refactor suggestions must preserve exact behavior.
- Highlight any potentially risky changes and provide safe migration paths.
- Ensure compatibility with existing tests and CI workflows.

### 6. Styling Cleanup
- Remove inline styles unless dynamic and unavoidable.
- Recommend extraction to CSS modules, styled-components, or design tokens.
- Improve styling consistency and maintainability.

### 7. Architecture & React Correctness
- Break large files into logical units (hooks, components, utils, services).
- Recommend React Context for shared state like auth/tenant.
- Suggest use of Suspense, ErrorBoundary, and AbortController when appropriate.
- Ensure correct use of effects, state, derived values, and memoization.

## 📁 Suggested Project Structure

src/
  components/
  hooks/
  services/
  contexts/
  types/
  utils/
  pages/
  features/
    customer/
      CustomerList.tsx
      useCustomerQuery.ts

Step 4. Refactor the Code

Always start refactoring in small, manageable chunks to improve code structure, readability, and maintainability without changing external behavior.

Focus on simplifying complex logic, breaking down large components, and improving naming, consistency, and modularity by following SOLID principles and scalable architecture patterns like Atomic Design.

Each change should make the codebase easier to understand, test, and extend in future.

Let me show you three code snippets that need refactoring.

Example 1:

Copied to Clipboard!

function getStatusLabel(status: string) {
  if (status === "pending") return "Pending";
  else if (status === "approved") return "Approved";
  else if (status === "rejected") return "Rejected";
  else if (status === "in_review") return "In Review";
  else if (status === "on_hold") return "On Hold";
  else return "Unknown";
}

Example 2:

Copied to Clipboard!

Example 3:

Copied to Clipboard!

Step 5. Unit Testing

Once refactoring is complete, strengthen the codebase with adequate unit tests.

Write tests for utilities, hooks, and components using  tools like Vitest or Jest with React Testing Library to simulate real user interactions and edge cases.

Unit tests give you the confidence that your changes didn’t break existing behavior and act as a safety net for future refactors.

Step 6. Post-Refactor Testing & Automation

E2E automation is your true protection against regression.

Run your full suite of automated tests to confirm that everything still works as expected and no regressions were introduced. Add or update end-to-end (E2E) tests where you found gaps during refactoring.

How do you know you have an adequate number of E2E tests?

It’s not easy to tell, a good starting point is to describe scenarios in simple English and run it by the business analyst, product owner and support team for the most critical flows.

For now you should be able to run all the test suites in your local environment to ensure no regressions were introduced.

Step 7. Merge code to main branch

There are 3 steps involved here:

1. Raise a great quality PR:

Add a clear description, screenshots, linked tickets, and make sure it checks every item in your Definition of Done PR template.

2. Code reviews using AI and Expert Peers:

Use both AI tools and expert peer reviews. AI helps catch common patterns and code smells, while peers bring domain context and architectural insight.

3. CI/CD integration integrated with quality gate checks.

Integrate CI/CD pipelines that run both unit tests and E2E tests, and use Husky pre-commit hooks to enforce linting, formatting, type checks, and test checks before code is merged.

Step 8. Engineering Metrics

Overall demonstrate how well you have reduced the tech debt.

You need to show the value and benefit of your refactor through metrics so capture the before and after engineering metrics for your refactored module.

Metrics that you can capture to showcase your work are linting errors before and after, unit test coverage, e2e tests, code complexity, duplication and performance.

These metrics show the real impact of your refactor and builds credibility with your stakeholders.

Frequently asked questions in refactoring

1. How to handle feature modification while refactoring?

If you don’t merge your refactor changes quickly, new code keeps landing in the main branch  and suddenly your refactored branch is outdated or full of conflicts.

The longer it stays open, the harder it is to merge, and you risk losing all that effort. Always refactor in small batches and merge often. 

And don’t pick up the file in case there is urgent feature addition is underway 

2. What happens when a refactor becomes too big to handle?

Big refactors slow everything down.

Huge PRs are tough to review, easy to miss bugs in, and often scare reviewers away. On top of that, if others are touching the same files, you’ll end up fighting merge conflicts.

Keep your refactors small and focused. It’s faster to review, easier to merge, and safer to ship.‍

3. What happens when you refactor in isolation ?

Refactoring in isolation is risky.

If you don’t sync with your team, you might end up working on the same files or touching overlapping areas  wasting everyone’s time.

Before you start, have a quick chat with your stakeholders/teammates. A two-minute sync can save hours of rework later.

4. Can refactoring accidentally break existing functionality?

Refactoring can easily break things that were working fine. When applications are tightly connected, even a small change can cause broken end to end flows. 

The only way around it is to test often, stakeholders collaborate and you keep your safety nets ready.

Good practices in Refactoring:

1. Collaborate with the Team Before Refactoring

Before you touch the code, talk to your team.

Check if someone’s already working in the same area or planning changes. It’ll save you from duplicate work and avoid messy conflicts later. A quick sync now is way better than untangling merge chaos later.

2. Estimate Refactoring Time

Always include refactoring in your time estimates during sprint calls. Don’t treat it as “extra” work; it’s one of the ways to make sure your code stays clean and reliable.

If you skip it, you’ll end up overloaded or missing deadlines. Setting the right expectations upfront keeps everyone aligned on what’s really getting done.

3. Start Small and Gradually Scale

Don’t start with the biggest file in the repo.

Pick something small and simple first. It helps you build confidence and reduces the chance of breaking things.

Once you get comfortable, take on bigger modules. Small wins stack up, and before you know it, your codebase feels cleaner and easier to work with.

4. Rebase Continuously and Create Small PRs

Keep your refactor up-to-date with the main branch. Rebase often so you’re not working on outdated code.

Small, focused PRs are easier to review, merge faster, and cause fewer conflicts. It’s the simplest way to keep your refactor smooth and in sync with the main branch.

5. Separate Refactoring from New Features

Don’t mix refactoring with new features in the same PR. It’s messy to review and even harder to debug later.

Keep them separate one PR for cleanup, another for feature/enhancement. Smaller, focused changes are easier to test, review, and merge without headaches.

Conclusion:

Refactoring is the heart beat of product development, when we do it right we make it easier for the next developer to add features, break less and release with more confidence.

At Codewalnut, we’ve learned that good refactors aren’t about big rewrites. They’re about small, steady improvements that keep the system simple and dependable.

Clean code doesn’t just make developers happy. It makes the whole product easier to grow. And that’s the real win.