Playbook · Migrations

Updated

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.
Source: Nx, read 17 Nov 2026

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

Start

Tell me where the product is stuck.

In 30 minutes we look at where things stand, what you need from a CTO right now, and which option fits. Either way, you leave with a clear next step.

How the call goes

  1. 01You tell me about the product, the team and the next 6 months.
  2. 02I ask about the code, the stack and what keeps breaking.
  3. 03We pick the option that fits, or agree that none does.

09:00 to 20:00 CET

Founding rate: the first 3 clients get 20% off, in return for a named testimonial and a case study. On a monthly plan, the 20% applies to the first month.