Migrate `nx` imports to `@nx/devkit`

@nx/devkit is the package that exports programmatic utils when working with Nx. The nx package is the CLI. It isn't a stable import surface.

In a future major version, the nx package will stop exporting these symbols. Any code that imports from nx, whether from the package root or from deep paths like nx/src/..., will break. Migrating now is a one-line-per-import change and keeps your code forward-compatible.

What goes where

Browse the full DevKit API here.

Before and after

Project graph

// ❌ Before: imports from the CLI package
import { createProjectGraphAsync } from 'nx/src/project-graph/project-graph';
import type { ProjectGraph } from 'nx/src/config/project-graph';

export async function listProjects(): Promise<string[]> {
  const graph: ProjectGraph = await createProjectGraphAsync();
  return Object.keys(graph.nodes);
}

// ✅ After: imports from the public devkit API
import { createProjectGraphAsync, ProjectGraph } from '@nx/devkit';

export async function listProjects(): Promise<string[]> {
  const graph: ProjectGraph = await createProjectGraphAsync();
  return Object.keys(graph.nodes);
}

Generator

// ❌ Before
import type { Tree } from 'nx/src/generators/tree';
import {
  addProjectConfiguration,
  readProjectConfiguration,
} from 'nx/src/generators/utils/project-configuration';
import { readNxJson } from 'nx/src/generators/utils/project-configuration';

export default async function (tree: Tree, schema: { project: string }) {
  const nxJson = readNxJson(tree);
  const project = readProjectConfiguration(tree, schema.project);
  // ...
}

// ✅ After
import {
  Tree,
  addProjectConfiguration,
  readProjectConfiguration,
  readNxJson,
  formatFiles,
} from '@nx/devkit';

export default async function (tree: Tree, schema: { project: string }) {
  const nxJson = readNxJson(tree);
  const project = readProjectConfiguration(tree, schema.project);
  // ...
  await formatFiles(tree);
}

Executor

// ❌ Before
import type { ExecutorContext } from 'nx/src/config/misc-interfaces';
import { workspaceRoot } from 'nx/src/utils/workspace-root';

export default async function runExecutor(
  options: { script: string },
  context: ExecutorContext
) {
  console.log(`Running from ${workspaceRoot}`);
  // ...
  return { success: true };
}

// ✅ After
import { ExecutorContext, workspaceRoot } from '@nx/devkit';

export default async function runExecutor(
  options: { script: string },
  context: ExecutorContext
) {
  console.log(`Running from ${workspaceRoot}`);
  // ...
  return { success: true };
}

JSON utilities and logging

// ❌ Before
import { readJsonFile, writeJsonFile } from 'nx/src/utils/fileutils';
import { logger } from 'nx/src/utils/logger';

// ✅ After
import { readJsonFile, writeJsonFile, logger } from '@nx/devkit';

Common symbols you should move

All of the following are part of the @nx/devkit public API. If you are importing them from nx today, move them.

This is not exhaustive. The authoritative list lives in the devkit API reference.

Testing utilities

If you import test helpers like createTreeWithEmptyWorkspace or readProjectConfiguration in tests, use the @nx/devkit/testing entry point:

// ✅
import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';

Angular adapter

If you have a plugin that bridges the Angular CLI, use the @nx/devkit/ngcli-adapter entry point instead of reaching into nx/src/adapter/...:

// ✅
import { NxScopedHost } from '@nx/devkit/ngcli-adapter';

Add @nx/devkit as a dependency

Run the package manager command for your workspace:

npm install --save-dev @nx/devkit

yarn add --dev @nx/devkit

pnpm add --save-dev @nx/devkit

bun add --dev @nx/devkit

For published plugins, declare @nx/devkit as a peerDependency so it resolves against the consumer's installed Nx version.

What if the symbol isn't in @nx/devkit?

Some nx exports are intentionally private. The nx/src/devkit-internals module is an example: it exists to let @nx/devkit bridge to internal Nx code, and it is not part of the public API. If a symbol you use lives there (or in any other nx/src/... path that isn't re-exported by @nx/devkit), don't move it to @nx/devkit and don't keep depending on the deep path long-term. It can change between minor versions.

Instead, open an issue on GitHub describing:

• the symbol you need
• the nx subpath you're importing it from today
• the use case (plugin, script, migration, etc.)

We'll decide whether to promote it to the public API.