TypeScript Security Best Practices: A Practical Guide for Engineering Teams

A legacy React application rarely becomes difficult overnight. The decline is gradual: upgrades get postponed, familiar workarounds turn into permanent architecture, build times creep upward, and a few sensitive areas become dangerous to change.

At that point, a rewrite can look cleaner than another round of patches. It offers an appealing promise: rebuild the product on the current React stack without carrying old decisions forward.

The problem is that the existing application does not stop moving while its replacement is being built. Features, bug fixes, compliance requirements, and customer requests continue to accumulate. The new system must chase a target that keeps changing while reproducing years of behavior — some of it undocumented.

For many functioning React applications, modernization is the safer option. The work can be divided into small releases, old and new code can coexist, and each change can have a defined rollback path. The harder question is not whether every old component should be replaced. It is which parts are creating enough technical and business friction to justify touching them.

Why a full rewrite should not be the default

When a codebase appears unsalvageable, teams may start budgeting a rebuild or interviewing the best React development companies to deliver it.

That decision deserves more scrutiny than it often receives. In 2000, Joel Spolsky described rewriting software from scratch as the single worst strategic mistake a software company could make. His example was Netscape, whose multi-year rewrite coincided with the company losing its position in the browser market.

A rewrite creates two related problems.

First, the replacement is always behind. While one team rebuilds the functionality the product had when the project began, the live application continues to change. The specification is not fixed, so the new system repeatedly absorbs work that has already been completed elsewhere.

Second, the replacement tends to expand. Fred Brooks described this as the second-system effect: once developers are released from the constraints of the original product, they are tempted to correct every architectural compromise and include every deferred idea. A replacement that began as a cleaner implementation becomes a larger and more ambitious system.

Rewrites also discard knowledge hidden in the existing code. An awkward conditional may represent a tax exception, a customer-specific permission rule, or a retry strategy added after a production incident. If that behavior is not documented, the new implementation may omit it without anyone noticing until release.

There are situations in which a rewrite is justified. The framework may no longer be maintained. The security model may be impossible to retrofit. Core architectural assumptions may no longer match the product. A small application may also be cheap enough to replace safely.

Those are decisions to reach through evidence, not frustration. An aging application that still works and continues to generate value is usually a better candidate for incremental modernization.

Does the React codebase actually need modernization?

Old code is not automatically bad code. A stable component written several years ago may require no attention if it still works, remains secure, and rarely changes.

Modernization becomes necessary when age starts restricting delivery, maintenance, or upgrades.

Version and dependency constraints

React 19.3 is the current React release as of September 2026. Applications still using APIs removed in React 19 cannot move to the current version without first replacing them.

The React 19 upgrade guide identifies several relevant changes, including the removal of legacy Context and string refs, the end of propTypes and defaultProps support for function components, and the removal of ReactDOM.render.

A project may be blocked even if its own code does not use those APIs directly. An abandoned dependency can impose the same restriction when it has no compatible release. The practical question is therefore not simply, "Which React version are we running?" It is, "What prevents us from moving forward?"

Declining development velocity

Version numbers are easy to measure. Delivery friction is less visible but often costs more.

Common warning signs include:

• Routine changes taking progressively longer

• Bugs clustering in the same parts of the application

• Engineers avoiding specific modules because the consequences are unpredictable

• New developers needing weeks to understand undocumented patterns

• Small UI changes requiring work across several tightly coupled components

• Releases depending on manual checks that only one or two people know how to perform

A component that looks dated but causes none of these problems is mostly a cosmetic concern. A checkout flow that requires a week of defensive work for every change is a business constraint.

Tooling that slows everyone down

Legacy build infrastructure can impose a small cost on every developer, several times a day. Slow startup, long hot reloads, missing code splitting, brittle Webpack configuration, and pipelines that nobody feels safe changing all belong in the modernization discussion.

The distinction to maintain is simple: some old code is merely unfashionable; other old code prevents the team from shipping safely. Modernize the second category first.

Audit the codebase before refactoring it

Modernization should begin with a map of the system. Without one, teams tend to refactor whichever files are most visibly unpleasant rather than the ones creating the greatest cost.

Start with dependencies:

npm outdated
npm audit

These commands will not produce a modernization plan on their own, but they expose outdated packages, known vulnerabilities, and upgrade chains. Pay particular attention to libraries that are unmaintained or have not released versions compatible with the React version you intend to adopt. Those dependencies can determine the sequence of the entire project.

Next, identify technical hotspots.

Complexity alone is a weak prioritization signal. A difficult module that has not changed in four years may be less important than a moderately complex module edited every week. Behavioral code analysis combines complexity with churn — the frequency with which a file changes in version-control history.

That intersection matters. A high-complexity, high-churn file repeatedly exposes developers to the riskiest parts of the system. CodeScene's research suggests that 1–2% of files may account for a large share of development activity, although the distribution will differ between repositories.

Static analysis tools such as SonarQube can identify complexity. Git history shows whether that complexity is actually affecting current work. Used together, they provide a more credible priority list than either source alone.

The audit should also locate seams: boundaries where one implementation can be replaced without forcing immediate changes elsewhere. Michael Feathers uses the term "seam" for places where behavior can be altered without editing the surrounding system. In a React application, a seam might be a route, module export, context provider, API adapter, or component interface.

Then document behavior that currently exists only in code. Legacy logic often contains rules that are absent from tickets and product documentation. Before changing that logic, capture what it does — including behavior that appears incorrect but may have downstream dependencies.

React modernization patterns that support gradual migration

There is no single architecture for incremental modernization. The right pattern depends on how the application is divided, who owns its parts, and how quickly a change must be reversible.

Strangler Fig

The Strangler Fig pattern places a routing layer or facade in front of the existing system. Requests assigned to modernized areas go to the new implementation; everything else continues to use the legacy application.

In a single-page React application, the router often becomes that boundary. A migrated route renders a new feature tree while untouched routes continue through the old one. Ownership moves route by route rather than during one final cutover.

This pattern works especially well when product areas already have clear URL and domain boundaries. Rollback is relatively simple: return the affected route to the legacy implementation.

Module Federation

Webpack 5 introduced Module Federation as a way for separately built applications to expose and consume modules at runtime. It is commonly used in micro-frontend architectures where teams need independent build and deployment cycles.

A modern shell can load both legacy and newer remotes, allowing one product area to move without requiring a simultaneous release across the whole frontend. The trade-off is operational complexity: teams must manage shared dependency versions, runtime failures, deployment compatibility, and cross-application observability.

Vite implementations require their own evaluation. Projects such as @originjs/vite-plugin-federation and @module-federation/vite differ in runtime design, compatibility, and maintenance. Earlier analysis of the Vite federation ecosystem can provide context, but repository activity and release status should be checked when the architecture is selected.

Module Federation is useful when organizational independence matters enough to justify the extra runtime and deployment surface. It is unnecessary for many single-team applications.

Component islands

A component island is a new React tree mounted inside an existing page. With createRoot, a team can replace one widget without converting the surrounding application.

This approach is particularly useful when React is being introduced into a server-rendered or jQuery-based product. It can also isolate a modern component inside an older React shell, provided the boundary does not require extensive shared state.

Islands are inexpensive to introduce and easy to remove. They become less attractive when components need to coordinate closely across several islands, because state synchronization and duplicated dependencies can erase the original simplicity.

A monorepo as a migration workspace

A monorepo is not a runtime migration pattern. It is a way to keep old and new implementations close enough to share tooling, types, tests, and build infrastructure.

During a long migration, this can be easier than coordinating changes across several repositories. Both implementations remain independently buildable, but compatibility work can be reviewed and tested in one place.

Migrating class components to hooks gradually

Class components and function components can remain in the same React tree. There is no technical requirement to convert the application in one pass — or to convert every class component eventually.

That makes class-to-hooks migration a prioritization problem rather than a prerequisite for all other modernization work.

Use codemods for mechanical changes. The react-codemod project, maintained with support from the React and Codemod.com teams, automates many repetitive API replacements. React's current migration recipe can be run with:

npx codemod@latest react/19/migration-recipe

Codemods cannot infer what a lifecycle method means to the product. A stateful class component may spread related behavior across componentDidMount, componentDidUpdate, and componentWillUnmount. Moving those lines into one or more effects without reconsidering their dependencies can produce code that compiles but behaves differently.

Treat automated output as a draft. Effects, subscriptions, cleanup logic, timers, data fetching, and state derived from props require manual review and tests.

For complicated components, extracting business behavior before rewriting the view often reduces the risk. Data fetching, subscriptions, and state transitions can move behind a stable service or into a carefully designed custom hook. Once that behavior has been isolated and tested, changing the rendering layer becomes a smaller operation.

Do not migrate stable class components simply to make the repository look consistent. If a component is rarely edited, does not rely on removed APIs, and blocks no planned work, conversion provides little return. Start with components that change often or prevent an upgrade the team actually needs.

Modernizing state, routing, and build tooling

A React codebase includes more than its component model. State management, routing, and build infrastructure can usually be modernized on separate timelines.

State management

Legacy Redux does not have to disappear before a newer state model can be introduced. Existing features can continue using the current store while new or migrated areas adopt Redux Toolkit slices or more local state where appropriate.

Context and hooks may be enough for state that belongs to a limited subtree. They are not automatic replacements for every global store. Frequently updated shared state, complex server data, and cross-feature coordination may still need dedicated tooling.

Migrate state according to feature boundaries. A repository-wide "state cleanup" project often changes many consumers without producing a visible product improvement. Moving one feature at a time keeps the scope testable.

Routing

Router upgrades frequently include breaking API and data-loading changes. A route boundary can provide a practical migration seam, but running old and new routing approaches together requires deliberate isolation.

Where the architecture permits it, introduce the new router for a contained set of routes or a controlled traffic segment. Feature flags can then manage exposure. The rollback plan should be tested before the new route receives meaningful traffic.

Build tooling

Build infrastructure is often a high-leverage target because every developer feels its cost.

The React team deprecated Create React App in February 2025, recommending frameworks for new applications and documenting build-tool options for projects that do not need a framework.

For a client-rendered application, migration from Create React App and Webpack to Vite can be relatively contained. It is not always a configuration-only change: environment variables, asset handling, test setup, browser compatibility, and custom Webpack behavior may need attention. Still, the change can often be isolated from the product's component architecture and rolled back independently.

A sensible sequence is to begin with a tooling change that removes daily friction, then modernize state and routing as relevant features are touched. Component migration can follow the same feature boundaries. The exact order should come from the audit rather than from a generic checklist.

Protecting existing behavior during the refactor

Incremental work is safer than a rewrite only when the team can detect unintended changes. Smaller releases reduce the blast radius; tests and rollback mechanisms make that reduction meaningful.

Characterization tests

Characterization tests record what the software currently does before its implementation changes. They do not claim that the behavior is correct. Their purpose is to distinguish deliberate changes from accidental ones.

These tests are especially valuable around undocumented business rules. If a legacy pricing function handles a particular customer type differently, a characterization test preserves that behavior until the team explicitly decides whether to keep or remove it.

Focus on observable inputs and outputs. Tests coupled too closely to the old implementation may become another obstacle to modernization.

Visual regression testing

Unit and integration tests may pass while a layout shifts, text overflows, or an interactive state disappears. Visual regression tools such as Chromatic, Percy, and Playwright screenshot comparisons can detect rendered differences between the old and new versions.

Pixel-level comparison also produces noise when fonts, rendering environments, animations, or dynamic data are unstable. Control those inputs and set review thresholds deliberately. The goal is not to reject every changed pixel; it is to make unintended UI changes visible.

Feature flags

A feature flag separates deployment from release. The new implementation can be shipped without exposing it, enabled for internal users, expanded to a small traffic segment, and disabled without another deployment.

Flags work particularly well with route-level strangulation and other changes that preserve an old implementation behind the same interface.

They also require maintenance. Every migration flag should have an owner and a removal condition. Otherwise, temporary branches become permanent architecture.

A tested rollback path

Before a migration step ships, the team should know how to reverse it. That may mean disabling a flag, restoring a route, pinning an earlier remote, or reverting a contained build configuration.

"Revert the pull request" is not always sufficient once schemas, persistent state, APIs, or deployment contracts have changed. Rollback must be designed around the real boundary of the release.

How to decide what to modernize first

Churn and complexity identify technical pain. They do not establish business priority.

A complicated internal module may be unpleasant to maintain but largely irrelevant to revenue or core workflows. A simpler component in the signup or billing flow may deserve attention first because small improvements there affect more users and more releases.

A useful prioritization model compares two dimensions:

• Business value: contribution to revenue, conversion, retention, compliance, or a core customer workflow

• Technical risk and coupling: complexity, change frequency, test coverage, dependency depth, and the potential blast radius of a change

Consider a SaaS dashboard. A self-contained widget used on every visit may be a quick win. The billing flow may be high-value but tightly coupled after years of patches, making it a strategic bet. An infrequently used settings page could be deferred. A brittle export tool that almost nobody uses may belong in the leave-alone quadrant unless it creates a security or support problem.

The distribution will be different for every product. The matrix is not a benchmark and should not be populated with assumed percentages.

Its value is in forcing an explicit decision. Some work should happen now, some should be scheduled with stronger safeguards, and some should not be done at all.

Staffing a React modernization project

Incremental modernization requires two kinds of knowledge at once. Engineers need to understand current React patterns, but they must also be able to read the older patterns being replaced.

That combination is not guaranteed by general React experience. The 2025 Stack Overflow Developer Survey reported React usage among roughly 45% of respondents, yet many developers entered the ecosystem after hooks became standard. A large React talent pool does not necessarily translate into deep experience with class lifecycles, legacy Context, older Redux architecture, or customized Webpack builds.

Teams usually have three staffing options.

Upskilling preserves institutional knowledge, but training competes with feature delivery. Permanent hiring makes sense when modernization skills will remain useful after the initial project, though recruitment and onboarding take time.

Staff augmentation can add experience for a bounded phase. Teams that need this capability temporarily may choose to hire experienced React.js developers instead of building permanent capacity for work with a defined end.

External execution should not mean external ownership of every decision. Keep architectural records, migration criteria, and the reasoning behind trade-offs accessible to the internal team. Pair external engineers with existing maintainers and include knowledge transfer in the work itself.

When evaluating a partner, ask for evidence of incremental migrations. A portfolio of greenfield React applications or complete rewrites does not demonstrate that a team can change a live legacy system without interrupting delivery.

How incremental modernization turns into an accidental rewrite

The most common failures begin with reasonable intentions and gradually expand beyond their original boundary.

"While we are here" work

An engineer opens a component to replace one deprecated API and notices several adjacent problems. Fixing them together appears efficient, but each extra change expands the test surface and makes failures harder to isolate.

Improvements outside the agreed scope should enter the backlog. They can be evaluated separately rather than folded into the current pull request.

Missing boundaries between old and new code

Without a stable interface, changes spread into neighboring modules. One component migration requires a store change, which requires a routing change, which affects several unrelated screens.

That expansion usually means the migration seam is in the wrong place. Stop and find a boundary that can contain the change instead of continuing until half the application is involved.

Refactoring by instinct

Developers naturally notice code that frustrates them. That does not make it the best business target.

A quarter spent cleaning aesthetically unpleasant but rarely changed modules may produce no improvement in delivery time, reliability, or upgrade readiness. Complexity, churn, business value, and dependency constraints provide a better basis for prioritization.

No definition of improvement

A modernization project should state what each phase is expected to change. Useful measures may include:

• Development-server startup and reload time

• Lead time for changes in a known hotspot

• Escaped defects in the migrated area

• Time required to onboard a developer

• Removal of a blocking dependency

• Completion of a React 19 upgrade

• Reduction in manual regression effort

Choose metrics that match the problem. Do not collect every available number or claim success because the new code uses newer syntax.

The first migration should prove the operating model: identify a meaningful target, protect its existing behavior, ship the replacement through a controlled path, measure the result, and remove the temporary migration machinery. Once that loop works, the team has evidence for deciding whether the next modernization step is worth funding.

Frequently asked questions

How long does it take to modernize a legacy React codebase without a rewrite?

There is no standard duration. It depends on the size of the application, the number and severity of its hotspots, dependency constraints, test coverage, and how much modernization work can run alongside product development.

An incremental program does not need one distant release date. Each completed phase should provide an independent improvement, such as removing a blocking dependency or reducing delivery time in a frequently changed area. Use the audit to define the scope instead of selecting an arbitrary calendar deadline.

Can class components be migrated to hooks gradually?

Yes. Class and function components can coexist in the same React tree, so migration can happen one component at a time.

Codemods are useful for mechanical API changes, but effects, data fetching, subscriptions, and lifecycle-dependent behavior need manual review. A stable class component that does not block an upgrade may not need conversion at all.

Is it safe to keep old and new React patterns in the same application?

Usually, provided that the boundaries are explicit and the combinations are supported by the React and tooling versions in use.

The main risk is not stylistic inconsistency. It is unclear ownership, duplicated state, incompatible dependencies, or undocumented routing between implementations. Record which path owns each feature and define when transitional architecture will be removed.

What is the difference between refactoring and modernizing a React codebase?

Refactoring changes the internal structure of code while preserving its observable behavior. Modernization is broader: it may include current React APIs, dependency upgrades, new build tooling, routing changes, revised state architecture, and improved test infrastructure.

Refactoring can be one part of modernization, but the terms are not interchangeable. A team can clean the structure of an old implementation without adopting newer technology, or upgrade tooling without rewriting application logic.

How can stakeholders be persuaded to fund incremental modernization instead of a rewrite?

Connect each phase to a measurable product or delivery constraint.

A rewrite asks the business to fund a large upfront project whose value may not arrive until the final cutover. Incremental modernization can target a slow build, a fragile revenue-critical workflow, an unsupported dependency, or a blocked React upgrade and deliver that improvement independently.

Begin with a contained, high-value area. If the team can modernize it without disrupting releases and demonstrate a measurable result, the case for the next phase becomes much easier to make.