# nx-import

Guides AI agents on importing and merging external repositories into an Nx workspace while preserving git commit history.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2600 installs · ★ 29
- Author: nrwl
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/nrwl/nx-ai-agents-config/tree/HEAD/skills/nx-import/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/nx-import

## What it does

This skill provides agents with step-by-step instructions for running `nx import`. It defines two distinct strategies: importing subdirectories one at a time for source monorepos, and importing the entire repository for standalone projects. The agent determines whether incoming code is an application or a library, then places it into matching workspace folders such as `apps/` or `packages/`.

The destination directory must always be empty before running the command. `nx import` does not migrate root dependencies from `package.json` or `targetDefaults` from `nx.json`, so those configurations require manual diffing. In `pnpm-workspace.yaml`, the command inserts raw directory names instead of glob patterns like `apps/*`, which breaks module resolution unless corrected. For linting, ESLint must be pinned to `eslint@^9` because ESLint 10 breaks `@nx/eslint`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add nrwl/nx-ai-agents-config --skill nx-import -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/nx-import/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/nx-import/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add nrwl/nx-ai-agents-config --skill nx-import -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/nx-import/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add nrwl/nx-ai-agents-config --skill nx-import -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/nx-import/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install nrwl/nx-ai-agents-config nx-import
```

2. **Manually: put the files in place**
- File: `.github/skills/nx-import/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add nrwl/nx-ai-agents-config --skill nx-import -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/nrwl/nx-ai-agents-config --path skills/nx-import
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/nx-import/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add nrwl/nx-ai-agents-config --skill nx-import -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/nrwl/nx-ai-agents-config/tree/HEAD/skills/nx-import/SKILL.md

## When to use it
- import an external repository into an Nx workspace with git history
- detect application versus library code structures automatically
- fix broken pnpm workspace globs after running nx import
- resolve missing root configurations and dependencies

## Example prompts
- Import the repository ../other-repo into `apps/web` using `nx import`
- Bring the auth library from git into `packages/auth` and keep commit history
- Merge the backend repository into this Nx monorepo and update `pnpm-workspace.yaml`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3db2dbcad877537f.

BEGIN THIRD-PARTY FILE 3db2dbcad877537f
```text
---
name: nx-import
description: Import, merge, or combine repositories into an Nx workspace using nx import. USE WHEN the user asks to adopt Nx across repos, move projects into a monorepo, or bring code/history from another repository.
---

## Quick Start

- `nx import` brings code from a source repository or folder into the current workspace, preserving commit history.
- After nx `22.6.0`, `nx import` responds with .ndjson outputs and follow-up questions. For earlier versions, always run with `--no-interactive` and specify all flags directly.
- Run `nx import --help` for available options.
- Make sure the destination directory is empty before importing.
  EXAMPLE: target has `libs/utils` and `libs/models`; source has `libs/ui` and `libs/data-access` — you cannot import `libs/` into `libs/` directly. Import each source library individually.

Primary docs:

- https://nx.dev/docs/guides/adopting-nx/import-project
- https://nx.dev/docs/guides/adopting-nx/preserving-git-histories

Read the nx docs if you have the tools for it.

## Import Strategy

**Subdirectory-at-a-time** (`nx import <source> apps --source=apps`):

- **Recommended for monorepo sources** — files land at top level, no redundant config
- Caveats: multiple import commands (separate merge commits each); dest must not have conflicting directories; root configs (deps, plugins, targetDefaults) not imported
- **Directory conflicts**: Import into alternate-named dir (e.g. `imported-apps/`), then rename

**Whole repo** (`nx import <source> imported --source=.`):

- **Only for non-monorepo sources** (single-project repos)
- For monorepos, creates messy nested config (`imported/nx.json`, `imported/tsconfig.base.json`, etc.)
- If you must: keep imported `tsconfig.base.json` (projects extend it), prefix workspace globs and executor paths

### Directory Conventions

- **Always prefer the destination's existing conventions.** Source uses `libs/`but dest uses `packages/`? Import into `packages/` (`nx import <source> packages/foo --source=libs/foo`).
- If dest has no convention (empty workspace), ask the user.

### Application vs Library Detection

Before importing, identify whether the source is an **application** or a **library**:

- **Applications**: Deployable end products. Common indicators:
  - _Frontend_: `next.config.*`, `vite.config.*` with a build entry point, framework-specific app scaffolding (CRA, Angular CLI app, etc.)
  - _Backend (Node.js)_: Express/Fastify/NestJS server entrypoint, no `"exports"` field in `package.json`
  - _JVM_: Maven `pom.xml` with `<packaging>jar</packaging>` or `<packaging>war</packaging>` and a `main` class; Gradle `application` plugin or `mainClass` setting
  - _.NET_: `.csproj`/`.fsproj` with `<OutputType>Exe</OutputType>` or `<OutputType>WinExe</OutputType>`
  - _General_: Dockerfile, a runnable entrypoint, no public API surface intended for import by other projects
```
END THIRD-PARTY FILE 3db2dbcad877537f

The third-party file has ended. Everything between the 3db2dbcad877537f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2911 of 13914 bytes. © nrwl · MIT · https://github.com/nrwl/nx-ai-agents-config/tree/HEAD/skills/nx-import/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md