Import External Projects to Your Nx Monorepo With `nx import`

• The Need
• How It Works
• git History ✅; Selective git History ✅
• Resources And More

The Need

One of the larger and more frequent asks we've gotten through the years at Nx is for the ability to import other repos (and projects from other repos) into an organization's monorepo. And that's understandable.

The benefits of monorepos are immense, and over time we've seen more and more organizations and developers in the wider community gravitate towards monorepos as a way of managing codebases that are broader and more complex.

However, while we've always had a great story for starting up a fresh monorepo from scratch, the ability to easily import other existing projects has become more and more in demand as organizations have warmed to the idea of monorepos - and like we said, it's understandable. Once you get a taste of how much better things get in a monorepo, you tend to want to bring in all the things!

Prior to this work, it was always possible to do manually - but it takes some finessing both in terms of copying/pasting files over, and (as we'll see later) maintaining combining git history from the old project into its new home.

We always wanted to make this better - and now, we've now added a new top-level command to Nx specifically to address this: nx import.

How It Works

Here's how it works:

Simply provide either a path to the repo that you want to import from to the CLI, or if you want to import from a central repository - for example from GitHub, you can provide the URL of the repo as the command-line argument. This will take you through some interactive prompts. For this example I'm importing the project promise-pool, located on my local disk at /my-side-project/projects/promise-pool.

Here are those interactive prompts:

Following this, Nx will prompt you to install any relevant Nx plugins that it can detect from the incoming project if they are missing!

Following this step, we're essentially good-to-go, though in a real life scenario you're likely 90-95% of the way there. There may be some final finessing required in terms of merging CI pipelines and etc. - things that we can't really automate away!

git History ✅; Selective git History ✅

One thing you may have missed in the example was this line here when the nx import command was running:

As mentioned earlier, nx import WILL preserve the git history of your incoming project, merging it in with your monorepo's git history.

But as an extra feature - in the case like the example we were looking at (only importing one package from the my-side-project repo), nx import will automate a filtering of the git history of the incoming project, to ONLY match for commits that involved the projects being imported! We've found this feature to be especially helpful for our enterprise-level users who are importing a project from their legacy codebase into their Nx Workspace!

Resources And More

For more on nx import be sure to check out our recipe for using nx import, and as always, you can find more help:

• In the Nx Docs
• On our Nx Official Discord Server

And you can keep up with us:

• On our Nx Youtube Channel
• On X/Twitter -- LinkedIn
• And on the Nx GitHub