How do you do an Angular to Nx migration?
An Angular to Nx migration starts with npx nx@latest init in your Angular CLI workspace. It keeps your folders, adds nx.json, splits angular.json into one project.json per project, and installs the Nx version that matches your Angular version.
npx nx@latest init keeps your file structure, creates nx.json and splits angular.json into a project.json per project. Adding --integrated moves apps into apps/ and libraries into libs/, and switches package.json scripts from ng to nx.
From my work
The Merchant Engine, my self-hostable e-commerce platform, is an Nx monorepo: a NestJS and Prisma API on PostgreSQL, an Angular 21 admin dashboard and an Analog.js storefront with server rendering. Jest, Vitest, Playwright and Lighthouse CI run in the same workspace.
Standalone or integrated
- Standalone (npx nx@latest init): your layout stays and you run the same app through nx. The safe first step.
- Integrated (npx nx@latest init --integrated): apps move to apps/, libraries to libs/, e2e suites to apps/<name>-e2e. Pick this when you plan more than one app.
- Other Angular CLI repos can join later with nx import, which keeps their git history.
Why teams move to Nx
One app rarely needs it. The case starts when a second app shows up, such as an admin next to a storefront, or an API in the same language, and they share code. Nx then lets you put shared code in libraries and stop copying it between repos.
What breaks in an Angular to Nx migration
- Custom builders in angular.json. Check each one by hand after nx init, before you trust the build.
- Scripts and CI jobs that call ng directly, after an integrated move. The CI ones announce themselves on the next push.
- Import paths, once code moves into libs and gets path aliases.
- Module boundaries you never had. Nx can enforce them with tags and the @nx/enforce-module-boundaries lint rule, and the first run usually fails on imports nobody planned.
Keeping it current after the move
nx migrate updates package versions and writes a migrations.json file. nx migrate --run-migrations then updates your config and source code across breaking changes. Commit, and delete the file once old branches are merged. Angular majors now come every 12 months, so this becomes a yearly routine. Like the dentist, it is shorter if you go on time.
When not to
A single Angular app with one team gains little, and I would leave it on the Angular CLI. Nx adds config you must keep up to date, and config is code nobody enjoys reviewing. Wait until you have a second project that shares code.
Read next
Sources
- Nx, migrate an Angular CLI workspace to Nx, read 17 Nov 2026
- Nx, automate updating dependencies, read 17 Nov 2026
- Nx, enforce module boundaries, read 17 Nov 2026
- Angular, versioning and releases, read 17 Nov 2026