Migrating Your Angular Applications to React Using AWS Transform Custom

Moving an Angular application to React can require changes across components, state management, routing, build tooling, and tests. Teams may consider the migration when Angular expertise is harder to staff, third-party libraries stop supporting older versions, or maintenance costs increase. AWS Transform custom automates this migration process by analyzing the Angular codebase, creating a migration plan, and generating the React implementation. It records its work as Git commits so developers can review and refine the changes.

AWS Transform custom is available through the CLI and a web experience. The AWS-managed Angular-to-React transformation is currently available in early access. It addresses changes across component architecture, state management, routing, build tooling, and validation, and it can reuse lessons learned from earlier executions.

The Angular to React migration transformation

The transformation takes an Angular application and produces React 18+ with TypeScript. A separate Angular version upgrade transformation handles applications that need to remain on Angular and move to a newer version.

An Angular-to-React migration touches nearly every layer of a frontend codebase. The transformation covers the following areas:

• Codebase analysis – Detects the Angular version, build system, routes, state management, UI framework, and API surface, and enumerates the app’s components. The result is written to .a2r/pre-analysis.json before any code changes.
• Dependency mapping – Removes Angular packages and adds React equivalents while preserving integrations
• Build migration – Replaces the Angular CLI build with Vite.
• Component and template conversion – Converts each Angular component into a React function component and its template into JSX.
• Behavioral verification – Builds an Express mock of the app’s backend API and a Playwright scenario suite, then re-runs those scenarios against the migrated React app.
• Visual verification – Screenshots every route before and after and compares them pixel-for-pixel.
• Documentation – Generates .a2r/migration-report.html with the behavioral and visual results.

In this post, we:

• Walk through running the transformation against a single Angular application with the AWS Transform CLI.
• Review what you get: version-controlled commits, the migrated React code, and a migration report backed by behavioral and visual checks.
• Review how the transformation captures and reuses learnings across runs.

The walkthrough shows how the Angular-to-React transformation works and what evidence it produces to evaluate whether the migration preserved application behavior.

The sample application

The walkthrough uses amplify-angular-sample-app, based on aws-samples/amplify-angular-template. It is a small Angular 17 Todo application with an AWS Amplify Gen 2 backend: an AWS AppSync GraphQL API over Amazon DynamoDB, accessed through the Amplify Data client.

Prerequisites

Before you begin, verify the following prerequisites. This walkthrough was run on an Amazon Elastic Compute Cloud (Amazon EC2) instance with Ubuntu Linux. The steps are similar on other Linux distributions and macOS.

• An AWS account with credentials configured on the machine, plus the AWS Identity and Access Management (IAM) permissions for AWS Transform custom (Getting started with AWS Transform).
• The AWS Transform CLI, installed and authenticated (also covered in Getting started).
• Node.js 22 or later and Git.
• The Angular toolchain (Angular CLI and npm), which installs with the project’s dependencies. The transformation accepts Angular 14 or later.

Running the transformation on a single application

Estimated time to complete: approximately 50–60 minutes.

Step 1: Prepare the sample project

Clone or copy the app into a working directory, install the dependencies, and confirm that it builds. AWS Transform custom writes changes as Git commits, so run the transformation from a Git repository. For this walkthrough, use a working branch or local copy rather than the main branch.

git clone https://github.com/aws-samples/amplify-angular-template.git amplify-angular-sample-app

Figure: 1 Clone the sample repository

Next, enter the project directory and install its dependencies:

cd amplify-angular-sample-app

npm install -s

Figure: 2 Download required external code packages

The sample imports amplify_outputs.json, which is normally generated by the Amplify backend and is not included in a fresh clone. Because this walkthrough focuses on the framework migration, create a placeholder instead of deploying a backend. The Angular build and the transformation’s mock backend do not require live AWS resources. Then confirm the Angular app builds:

echo '{}' > amplify_outputs.json

npx ng build

Figure: 3 The Angular sample app builds successfully

This walkthrough uses the placeholder configuration, so Step 1 does not provision AWS resources. To run the app against a real backend instead, deploy an Amplify Gen 2 sandbox with npx ampx sandbox; see Set up your AWS account for Amplify.

Step 2: Discover available transformations

List the transformations in your account’s registry. AWS-managed transformations are shown first, followed by any you’ve authored.

atx custom def list | grep angular

The Angular-to-React entry appears as AWS/early-access-angular-to-react-migration .

Figure: 4 The Angular-to-React transformation in the registry

Step 3: Run the transformation

The transformation can be run interactively or non-interactively:

1. Interactive mode: Start the AWS Transform CLI:

atx

At the atx > prompt, enter the transformation name:

AWS/early-access-angular-to-react-migration

Figure: 5 Launching atx and selecting the transformation

Because this is an AWS-managed transformation, you cannot view or modify its full definition. In interactive mode, you can still provide additional context such as a target React version, a state-management preference, and integrations to preserve. The agent pauses for approval before it proceeds. Changes remain as local Git commits and are not pushed to the remote repository unless you push them.

2. Non-interactive mode: For the sample run shown below, we used non-interactive mode so the agent could detect the codebase and run end to end without prompts:

atx custom def exec -p . --non-interactive --trust-all-tools -n "AWS/early-access-angular-to-react-migration" -c "npm run build"

Figure: 6 Starting the transformation in non-interactive mode

The -c “npm run build” argument gives the agent a build command to validate against.

The –trust-all-tools option allows the agent to run tools, including builds, file edits, and commits, without prompting at each step. Changes remain local Git commits unless you push them to a remote repository. Use this option only in environments where unattended tool execution is acceptable, and review the generated commits before merging.

Step 4: Review the analysis

The transformation begins with a pre-analysis phase and records its findings in .a2r/pre-analysis.json.

For the sample app:

Figure: 7 The pre-analysis result for the angular sample app

It identifies the standalone components, records the app architecture, and writes its exit criteria before changing anything.

Before changing the application code, the transformation captures a behavioral baseline. It creates an Express mock of the backend and a Playwright test suite, then captures screenshots for each route. After migrating the code, it reruns the same scenarios and compares the React screenshots with the Angular baseline. These checks form a characterization baseline for comparing the Angular and React implementations. The transformation records its validation criteria in .a2r/exit-criteria.md:

Figure: 8 The transformation’s exit criteria

Step 5: Monitor progress and phases

After the baseline is captured, the transformation runs the migration as a sequence of phases and commits changes as it progresses. The terminal shows each phase while the agent reads files, runs commands, and applies the migration.

For this sample run, the detailed worklog was stored at ~/.aws/atx/custom/<execution-timestamp>/artifacts/worklog.log. Replace <execution-timestamp> with the folder created for the run, for example 20260730_133825_f29e1300.

Figure 9 shows the phases recorded in the sample run:

Figure: 9 Phases recorded in worklog.log

In this sample run, the CLI reported 60 files changed and approximately 130 agent-minutes. Agent minutes measure active agent work rather than wall-clock time and are the pricing unit for AWS Transform custom. Because usage depends on both the codebase and transformation complexity, treat this run as an example rather than a benchmark. See AWS Transform pricing for details.

With the run complete, the next step is to review the generated branch, transformed code, and validation artifacts.

What you get after the transformation

A version-controlled staging branch

The transformation writes its changes to a dedicated staging branch (atx-result-staging-<timestamp>), leaving the source branch unchanged. The commit history shows how the work was grouped across phases:

cd amplify-angular-sample-app
git log --oneline

Figure: 10 Commit history in each phase

The transformed code

In this sample, Angular components become React function components that use hooks. Routing uses React Router v6, and the app entry point configures Amplify and TanStack Query. Angular services become React hooks or a Zustand store for shared state. Route guards become React Router guard components with lazy loading. HTTP interceptors become a fetch wrapper. Reactive forms become React Hook Form. The amplify/ backend folder is unchanged, so the React app continues to use the same backend and can be deployed to AWS Amplify Hosting.

The migration report and artifacts

The transformation writes its validation evidence to the .a2r/ directory:

• .a2r/migration-report.html – the primary report, with a Business Logic section (each scenario and its pass/fail status) and a UI Comparison section (per-route pixel-diff ratios against the Angular baseline).
• .a2r/validation-summary.md – the exit-criteria checklist with verification method and evidence for each.
• .a2r/scenario-results.json – machine-readable results for every scenario.
• .a2r/coverage-report.json – line/branch coverage for the characterization suite.
• .a2r/screenshots/ – home.angular.png, home.react.png, and home.diff.png per route.

ls -lth amplify-angular-sample-app/.a2r/

Figure: 11 Migration reports and Artifacts

What requires manual review

The automated checks provide a baseline, but some patterns still benefit from targeted developer review. These issues can appear as failing scenarios or higher pixel-diff ratios in .a2r/migration-report.html:

• Third-party Angular UI libraries: Angular Material, PrimeNG, and NG-Bootstrap do not have 1:1 React equivalents. A substituted library such as MUI or Radix may not match the Angular baseline pixel-for-pixel.
• NgRx and complex RxJS: Complex state patterns and advanced operators can require additional validation. Include these paths in a pilot before broader rollout.
• Route resolvers and canDeactivate: These route behaviors should be reviewed after migration.
• Internationalization: Angular i18n maps to a different React library landscape, such as react-i18next, so the target library should be chosen deliberately.
• Server-side rendering: Angular Universal applications require an explicit target architecture, such as Next.js, Remix, or Vite SSR. The transformation does not select that target automatically.

Review learnings from previous runs

After a transformation run completes, AWS Transform custom continual learning extracts lessons from the execution, developer feedback, and code fixes. Active lessons are applied automatically to later runs of the same transformation.

In our sample run, worklog.log recorded “Learnings applied from previous runs of this transformation.” The applied lessons included starting the servers before screenshot capture and stopping them afterward, and using fullPage: true so the React screenshots matched the Angular full-page baseline.

To review the lessons associated with the Angular-to-React transformation, run:

atx custom def learnings -n "AWS/early-access-angular-to-react-migration"

Figure: 12 Knowledge items

The viewer groups lessons by category and shows which lessons are active. From here, you can inspect a lesson, archive it so it is not applied to future runs, restore an archived lesson, or delete it. This lets you review what the transformation learned before those lessons are reused on later runs.

Clean up

If you used the placeholder from Step 1, no AWS resources were created. To discard the migration output locally, delete the Git branch and the sample app source code folder. If you chose to deploy a real Amplify sandbox instead of the placeholder, tear it down with npx ampx sandbox delete, and remove any Amplify Hosting app you created from the Amplify console.

Conclusion

The Angular-to-React transformation in AWS Transform custom combines code conversion with validation artifacts that make the result easier to review. In the sample run, it migrated the application to React 18 with Vite and TypeScript, reran the behavioral scenarios, and compared React screenshots with the Angular baseline. The transformation wrote its changes to a separate staging branch and generated reports that capture the validation results. These artifacts give developers a concrete basis for reviewing the migration before deciding what to merge or refine.

To get started, install the AWS Transform CLI and follow Getting started with AWS Transform. For pricing details and at-scale planning, see the AWS Transform pricing page.