Phased React Decommissioning & Pipeline Retirement

Welcome to the final lesson of our module on incremental migration. In our last session, we established the technical foundation for running React and HTMX side-by-side, using patterns like the "Islands of Interactivity" to mount React components within server-rendered HTML. You now have the tools for coexistence.

Today, we move from technical implementation to strategic planning. Coexistence is a means to an end, not the final goal. This lesson is about defining that endgame. Your learning outcome is to plan the strategic decommissioning of React from the project, including sequencing of component removals and retirement of the React build pipeline.

We will outline a structured process for identifying which parts of your React application to replace first, which to save for last, and how to methodically dismantle the React-specific infrastructure until the migration is complete.

The Strategic Goal: Why Decommission React?

Before diving into the "how," it's crucial to anchor our plan in the "why." A migration isn't just a technology swap; it's a strategic move to achieve specific benefits. The ultimate goal is to simplify your architecture, reduce code complexity, and improve performance and development velocity.

In the previous lesson, you watched a talk detailing a real-world migration. Let's briefly revisit the powerful outcomes that team achieved, as this is the destination your strategic plan should aim for.

These results—faster development, a simpler stack, a drastically smaller codebase, and improved performance—are the prizes. A clear decommissioning plan is the map to get there.

A Framework for Decommissioning: The Strangler Fig Pattern

The most reliable strategy for replacing a legacy system is the Strangler Fig Pattern. You've heard this term before; it involves wrapping the old system and gradually replacing its functionality piece by piece until the old system is "strangled" and can be removed. This avoids the high risk of a "big bang" rewrite.

While this pattern is often discussed for large, monolithic backends, its principles are perfectly suited for a frontend migration. The following video provides a robust, five-step process for applying this pattern, which we can adapt for our React-to-HTMX migration.

Let's adapt that five-step framework to our specific goal of decommissioning React:

1. Define Value & Target Picture: Decide what "done" looks like. Will 100% of React be gone, or will some complex "islands" remain?
2. Analyze the Current State: Audit your React application to create an inventory of components and their complexity.
3. Prioritize & Sequence: Create a component-by-component removal plan based on complexity and value.
4. Execute Incrementally: Perform the migration route by route, using the coexistence patterns we've already learned.
5. Finalize Decommissioning: Once the migration is complete, formally retire the React build pipeline and dependencies.

Step 1 & 2: Auditing and Analyzing Your React Application

Before you can create a plan, you need a map of the territory. This involves auditing your existing React components to understand their function and complexity.

A great place to start is by categorizing your components, as suggested in the article "htmx in 2026".

Based on this, you can create an inventory of your React components and classify them into three main buckets:

• Low-Interaction / "Read-Only" Components: These mainly display data fetched from an API. Examples include user profiles, lists of items, dashboards with static charts, and content pages. These are your prime initial targets.
• Simple Interaction Components: These are primarily forms (create, edit, search) that follow a straightforward submission-response cycle. These are excellent second-wave targets.
• High-Interaction / Complex State Components: These involve significant client-side logic that doesn't map cleanly to a server request-response model. Examples include rich text editors, drag-and-drop interfaces, or highly interactive data visualizations. These should be migrated last, if at all.

For a more rigorous analysis, you can borrow techniques from backend system analysis.

Even on a solo project, these concepts are valuable. You can quickly assess:

• Code Complexity: Which components are the largest or have the most convoluted logic?
• Behavioral Hotspots: Use git log --stat or a tool like git-quick-stats on a component's directory to see how often it changes. High churn can indicate either a complex area or a core, valuable part of your app.

This analysis provides the raw data for the next, most crucial step: prioritization.

Step 3: Creating a Prioritization and Sequencing Plan

With your component inventory in hand, you can now build a sequence for the migration. The key is to tackle components in an order that maximizes momentum and minimizes risk. The best way to do this is by prioritizing quick wins: features that are low in complexity but high in value.

The following article provides an excellent framework for this, the "Migration Priority Matrix."

Here is how you can apply that matrix to your component audit:

1. Start Here (Low Complexity, High Value): These are your low-interaction, "read-only" components. Migrating a user profile page or a simple data table from React to a server-rendered template with hx-get is a fast, satisfying win.
2. Next Up (Medium Complexity, High Value): This is where most of your CRUD forms will land. The patterns for creating, editing, and deleting items with HTMX are straightforward but involve more server-side logic (e.g., validation) than simple data display.
3. Do Later (Low Complexity, Low Value): These might be obscure settings pages or components that are rarely used. Their migration doesn't provide a big impact, so they can wait.
4. Do Last or Never (High Complexity): These are the components you identified as having complex, client-heavy state. The strategy here is twofold:
   • Postpone: Leave them as React "islands" for the final phase of the migration.
   • Re-evaluate: Ask if the complexity is truly necessary. Could a simpler, server-driven interaction achieve 80% of the value with 20% of the complexity?
   • Keep: It is a perfectly valid outcome to permanently keep a few complex components as React islands within your otherwise HTMX-driven application.

The output of this step should be a sequenced backlog: a list of React components and routes, ordered from the first to the last one you plan to replace.

Step 4 & 5: Execution and Final Decommissioning

Step 4, the incremental execution, is the day-to-day work of the migration, using the techniques you've learned throughout this course.

Step 5 is the final lap. Once you've worked through your prioritized list and either replaced or consciously decided to keep the last of your React components, you can officially retire React from your project. This is a critical step that solidifies the benefits of the migration.

The "Migration Strategy" article provides a useful checklist for the final phase.

Here is a concrete decommissioning checklist for your project:

1. Confirm No Full-Page React Renders: Ensure your Express router handles all page requests, serving full HTML documents. The React router should be completely gone.
2. Validate React Islands (If Any): If you kept any React components as islands, ensure they are stable and mounting correctly via your htmx.onLoad or Web Component mechanism.
3. Remove React Dependencies from package.json: Run npm uninstall react react-dom react-router and any other React-ecosystem libraries (state management, component libraries, etc.).
4. Retire the Frontend Build Pipeline:
   • Delete your vite.config.js or webpack.config.js.
   • Clean up the scripts section of package.json. Your build and dev scripts for React will be replaced by a simple start script using nodemon for your Express server.
   • If you have any remaining client-side JS (for your React islands or vanilla JS enhancements), you may only need a very simple bundler or even just serve them as ES modules.
5. Delete Legacy Source Code: This is the most satisfying step. Delete the entire React source tree (/src/components, /src/hooks, /src/pages, etc.). Your project structure will now be centered around your Express routes and view templates.
6. Update CI/CD and Testing: Remove steps related to the React build from your deployment pipeline. Your testing strategy will shift away from component unit tests (e.g., with React Testing Library) toward integration tests that verify the HTML fragments returned by your Express endpoints.

Completing this checklist signifies the end of the migration. You will have successfully transformed your application, leaving you with a simpler, more maintainable, and often faster project.

Conclusion

This lesson has provided a strategic roadmap for moving beyond mere coexistence to the complete, planned decommissioning of React. You now have a framework for methodically dismantling a client-side application and replacing it with a server-centric one.

Key Takeaways:

• Start with Why: The goal of decommissioning is tangible: a smaller codebase, improved performance, and faster development, as seen in real-world case studies.
• Use a Structured Framework: Adapt the Strangler Fig pattern by auditing, analyzing, prioritizing, and then executing your migration. Don't attempt a "big bang" rewrite.
• Prioritize with a Matrix: Use the Complexity vs. Value matrix to identify quick wins (Low Complexity, High Value) and sequence your work effectively.
• Decommissioning is a Process: The final retirement of the build pipeline and dependencies is a deliberate, multi-step process that marks the true completion of the migration.

With the migration plan now in place, our focus shifts to ensuring the new application is robust and secure. In the next module, Application Security, we will tackle critical topics like preventing Cross-Site Scripting (XSS) and implementing Cross-Site Request Forgery (CSRF) protection for your new HTMX-powered endpoints.