Module: @nx/devkit

The Nx Devkit is the underlying technology used to customize Nx to support different technologies and custom use-cases. It contains many utility functions for reading and writing files, updating configuration, working with Abstract Syntax Trees(ASTs), and more.

As with most things in Nx, the core of Nx Devkit is very simple. It only uses language primitives and immutable objects (the tree being the only exception).

Enumerations

Classes

Interfaces

Type Aliases

Variables

Functions

Enumerations

ChangeType

• ChangeType: Object

DependencyType

• DependencyType: Object

Type of dependency between projects

Classes

ProjectGraphBuilder

• ProjectGraphBuilder: Object

Workspaces

• Workspaces: Object

Interfaces

DefaultTasksRunnerOptions

• DefaultTasksRunnerOptions: Object

ExecutorContext

• ExecutorContext: Object

Context that is passed into an executor

ExecutorsJson

• ExecutorsJson: Object

FileChange

• FileChange: Object

Description of a file change in the Nx virtual file system/

FileData

• FileData: Object

Some metadata about a file

GeneratorsJson

• GeneratorsJson: Object

Hash

• Hash: Object

A data structure returned by the default hasher.

HasherContext

• HasherContext: Object

ImplicitJsonSubsetDependency

• ImplicitJsonSubsetDependency<T>: Object

Type parameters

Name	Type
`T`	`"*"` \| `string`[]

JsonParseOptions

• JsonParseOptions: Object

JsonSerializeOptions

• JsonSerializeOptions: Object

MigrationsJson

• MigrationsJson: Object

ModuleFederationConfig

• ModuleFederationConfig: Object

NxAffectedConfig

• NxAffectedConfig: Object

NxJsonConfiguration

• NxJsonConfiguration<T>: Object

Nx.json configuration

@note: when adding properties here add them to allowedWorkspaceExtensions in adapter/compat.ts

Type parameters

Name	Type
`T`	`"*"` \| `string`[]

NxPlugin

• NxPlugin: Object

A plugin for Nx

ProjectConfiguration

• ProjectConfiguration: Object

Project configuration

@note: when adding properties here add them to allowedProjectExtensions in adapter/compat.ts

ProjectFileMap

• ProjectFileMap: Object

A list of files separated by the project they belong to

ProjectGraph

• ProjectGraph: Object

A Graph of projects in the workspace and dependencies between them

ProjectGraphDependency

• ProjectGraphDependency: Object

A dependency between two projects

ProjectGraphExternalNode

• ProjectGraphExternalNode: Object

A node describing an external dependency name has as form of:

npm:packageName for root dependencies or
npm:packageName@version for nested transitive dependencies

This is vital for our node discovery to always point to root dependencies, while allowing tracking of the full tree of different nested versions

ProjectGraphProcessorContext

• ProjectGraphProcessorContext: Object

Additional information to be used to process a project graph

ProjectGraphProjectNode

• ProjectGraphProjectNode: Object

A node describing a project in a workspace

ProjectsConfigurations

• ProjectsConfigurations: Object

Projects Configurations @note: when adding properties here add them to allowedWorkspaceExtensions in adapter/compat.ts

RemoteCache

• RemoteCache: Object

SharedLibraryConfig

• SharedLibraryConfig: Object

StringDeletion

• StringDeletion: Object

StringInsertion

• StringInsertion: Object

Target

• Target: Object

TargetConfiguration

• TargetConfiguration<T>: Object

Target's configuration

Type parameters

Name	Type
`T`	`any`

TargetDependencyConfig

• TargetDependencyConfig: Object

Task

• Task: Object

A representation of the invocation of an Executor

TaskGraph

• TaskGraph: Object

Graph of Tasks to be executed

TaskHasher

• TaskHasher: Object

Tree

• Tree: Object

Virtual file system tree.

Workspace

• Workspace: Object

Deprecated

use ProjectsConfigurations or NxJsonConfiguration

Type Aliases

AdditionalSharedConfig

Ƭ AdditionalSharedConfig: (string | [libraryName: string, sharedConfig: SharedLibraryConfig] | { libraryName: string ; sharedConfig: SharedLibraryConfig })[]

CustomHasher

Ƭ CustomHasher: (task: Task, context: HasherContext) => Promise<Hash>

Type declaration

▸ (task, context): Promise<Hash>

Parameters

Name	Type
`task`	`Task`
`context`	`HasherContext`

Returns

Promise<Hash>

Executor

Ƭ Executor<T>: (options: T, context: ExecutorContext) => Promise<{ success: boolean }> | AsyncIterableIterator<{ success: boolean }>

Type parameters

Name	Type
`T`	`any`

Type declaration

▸ (options, context): Promise<{ success: boolean }> | AsyncIterableIterator<{ success: boolean }>

Implementation of a target of a project

Parameters

Name	Type
`options`	`T`
`context`	`ExecutorContext`

Returns

Promise<{ success: boolean }> | AsyncIterableIterator<{ success: boolean }>

Generator

Ƭ Generator<T>: (tree: any, schema: T) => void | GeneratorCallback | Promise<void | GeneratorCallback>

Type parameters

Name	Type
`T`	`unknown`

Type declaration

▸ (tree, schema): void | GeneratorCallback | Promise<void | GeneratorCallback>

A function that schedules updates to the filesystem to be done atomically

Parameters

Name	Type
`tree`	`any`
`schema`	`T`

Returns

void | GeneratorCallback | Promise<void | GeneratorCallback>

GeneratorCallback

Ƭ GeneratorCallback: () => void | Promise<void>

Type declaration

▸ (): void | Promise<void>

A callback function that is executed after changes are made to the file system

Returns

void | Promise<void>

Hasher

Ƭ Hasher: TaskHasher

ImplicitDependencyEntry

Ƭ ImplicitDependencyEntry<T>: Object

Type parameters

Name	Type
`T`	`"*"` \| `string`[]

Index signature

▪ [key: string]: T | ImplicitJsonSubsetDependency<T>

ModuleFederationLibrary

Ƭ ModuleFederationLibrary: Object

Type declaration

Name	Type
`name`	`string`
`type`	`string`

PackageManager

Ƭ PackageManager: "yarn" | "pnpm" | "npm"

ProjectGraphNode

Ƭ ProjectGraphNode: ProjectGraphProjectNode | ProjectGraphExternalNode

Deprecated

this type will be removed in v16. Use ProjectGraphProjectNode or ProjectGraphExternalNode instead

ProjectTargetConfigurator

Ƭ ProjectTargetConfigurator: (file: string) => Record<string, TargetConfiguration>

Type declaration

▸ (file): Record<string, TargetConfiguration>

Parameters

Name	Type
`file`	`string`

Returns

Record<string, TargetConfiguration>

ProjectType

Ƭ ProjectType: "library" | "application"

Type of project supported

Remotes

Ƭ Remotes: string[] | [remoteName: string, remoteUrl: string][]

SharedFunction

Ƭ SharedFunction: (libraryName: string, sharedConfig: SharedLibraryConfig) => undefined | false | SharedLibraryConfig

Type declaration

▸ (libraryName, sharedConfig): undefined | false | SharedLibraryConfig

Parameters

Name	Type
`libraryName`	`string`
`sharedConfig`	`SharedLibraryConfig`

Returns

undefined | false | SharedLibraryConfig

SharedWorkspaceLibraryConfig

Ƭ SharedWorkspaceLibraryConfig: Object

Type declaration

Name	Type
`getAliases`	() => `Record`<`string`, `string`>
`getLibraries`	(`eager?`: `boolean`) => `Record`<`string`, `SharedLibraryConfig`>
`getReplacementPlugin`	() => `NormalModuleReplacementPlugin`

StringChange

Ƭ StringChange: StringInsertion | StringDeletion

A change to be made to a string

TaskGraphExecutor

Ƭ TaskGraphExecutor<T>: (taskGraph: TaskGraph, options: Record<string, T>, overrides: T, context: ExecutorContext) => Promise<Record<string, { success: boolean ; terminalOutput: string }>>

Type parameters

Name	Type
`T`	`any`

Type declaration

▸ (taskGraph, options, overrides, context): Promise<Record<string, { success: boolean ; terminalOutput: string }>>

Implementation of a target of a project that handles multiple projects to be batched

Parameters

Name	Type
`taskGraph`	`TaskGraph`
`options`	`Record`<`string`, `T`>
`overrides`	`T`
`context`	`ExecutorContext`

Returns

Promise<Record<string, { success: boolean ; terminalOutput: string }>>

WorkspaceConfiguration

Ƭ WorkspaceConfiguration: Omit<ProjectsConfigurations, "projects"> & Partial<NxJsonConfiguration>

Deprecated

using NxJsonConfiguration

WorkspaceJsonConfiguration

Ƭ WorkspaceJsonConfiguration: ProjectsConfigurations

Deprecated

use ProjectsConfigurations

WorkspaceLibrary

Ƭ WorkspaceLibrary: Object

Type declaration

Name	Type
`importKey`	`string` \| `undefined`
`name`	`string`
`root`	`string`

WorkspaceLibrarySecondaryEntryPoint

Ƭ WorkspaceLibrarySecondaryEntryPoint: Object

Type declaration

Name	Type
`name`	`string`
`path`	`string`

Variables

NX_VERSION

• Const NX_VERSION: string

Description

The version of Nx used by the workspace. Returns null if no version is found.

appRootPath

• Const appRootPath: string = workspaceRoot

The root of the workspace.

Deprecated

use workspaceRoot instead

cacheDir

• Const cacheDir: string

Path to the directory where Nx stores its cache and daemon-related files.

logger

• Const logger: Object

Type declaration

Name	Type
`debug`	(...`s`: `any`[]) => `void`
`error`	(`s`: `any`) => `void`
`fatal`	(...`s`: `any`[]) => `void`
`info`	(`s`: `any`) => `void`
`log`	(...`s`: `any`[]) => `void`
`warn`	(`s`: `any`) => `void`

output

• Const output: CLIOutput

workspaceRoot

• workspaceRoot: string

The root of the workspace

Functions

addDependenciesToPackageJson

▸ addDependenciesToPackageJson(tree, dependencies, devDependencies, packageJsonPath?): GeneratorCallback

Add Dependencies and Dev Dependencies to package.json

For example:

addDependenciesToPackageJson(tree, { react: 'latest' }, { jest: 'latest' });

This will add react and jest to the dependencies and devDependencies sections of package.json respectively.

Parameters

Name	Type	Default value	Description
`tree`	`Tree`	`undefined`	Tree representing file system to modify
`dependencies`	`Record`<`string`, `string`>	`undefined`	Dependencies to be added to the dependencies section of package.json
`devDependencies`	`Record`<`string`, `string`>	`undefined`	Dependencies to be added to the devDependencies section of package.json
`packageJsonPath`	`string`	`'package.json'`	Path to package.json

Returns

GeneratorCallback

Callback to install dependencies only if necessary, no-op otherwise

addProjectConfiguration

▸ addProjectConfiguration(tree, projectName, projectConfiguration, standalone?): void

Adds project configuration to the Nx workspace.

Parameters

Name	Type	Default value	Description
`tree`	`Tree`	`undefined`	the file system tree
`projectName`	`string`	`undefined`	unique name. Often directories are part of the name (e.g., mydir-mylib)
`projectConfiguration`	`ProjectConfiguration`	`undefined`	project configuration
`standalone`	`boolean`	`true`	whether the project is configured in workspace.json or not

Returns

void

applyAdditionalShared

▸ applyAdditionalShared(sharedConfig, additionalShared, projectGraph): void

Add additional dependencies to the shared package that may not have been discovered by the project graph.

This can be useful for applications that use a Dependency Injection system that expects certain Singleton values to be present in the shared injection hierarchy.

Parameters

Name	Type	Description
`sharedConfig`	`Record`<`string`, `SharedLibraryConfig`>	The original Shared Config
`additionalShared`	`AdditionalSharedConfig`	The additional dependencies to add
`projectGraph`	`ProjectGraph`	The Nx project graph

Returns

void

applyChangesToString

▸ applyChangesToString(text, changes): string

Applies a list of changes to a string's original value.

This is useful when working with ASTs.

For Example, to rename a property in a method's options:

const code = `bootstrap({
  target: document.querySelector('#app')
})`;

const indexOfPropertyName = 13; // Usually determined by analyzing an AST.
const updatedCode = applyChangesToString(code, [
  {
    type: ChangeType.Insert,
    index: indexOfPropertyName,
    text: 'element',
  },
  {
    type: ChangeType.Delete,
    start: indexOfPropertyName,
    length: 6,
  },
]);

bootstrap({
  element: document.querySelector('#app'),
});

Parameters

Name	Type
`text`	`string`
`changes`	`StringChange`[]

Returns

string

applySharedFunction

▸ applySharedFunction(sharedConfig, sharedFn): void

Apply a custom function provided by the user that will modify the Shared Config of the dependencies for the Module Federation build.

Parameters

Name	Type	Description
`sharedConfig`	`Record`<`string`, `SharedLibraryConfig`>	The original Shared Config to be modified
`sharedFn`	`SharedFunction`	The custom function to run

Returns

void

convertNxExecutor

▸ convertNxExecutor(executor): any

Convert an Nx Executor into an Angular Devkit Builder

Use this to expose a compatible Angular Builder

Parameters

Name	Type
`executor`	`Executor`

Returns

any

convertNxGenerator

▸ convertNxGenerator<T>(generator, skipWritingConfigInOldFormat?): (generatorOptions: T) => (tree: any, context: any) => Promise<any>

Convert an Nx Generator into an Angular Devkit Schematic.

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Default value	Description
`generator`	`Generator`<`T`>	`undefined`	The Nx generator to convert to an Angular Devkit Schematic.
`skipWritingConfigInOldFormat`	`boolean`	`false`	-

Returns

fn

▸ (generatorOptions): (tree: any, context: any) => Promise<any>

Parameters

Name	Type
`generatorOptions`	`T`

Returns

fn

▸ (tree, context): Promise<any>

Parameters

Name	Type
`tree`	`any`
`context`	`any`

Returns

Promise<any>

createProjectGraphAsync

▸ createProjectGraphAsync(opts?): Promise<ProjectGraph>

Computes and returns a ProjectGraph.

Nx will compute the graph either in a daemon process or in the current process.

Nx will compute it in the current process if:

The process is running in CI (CI env variable is to true or other common variables used by CI providers are set).
It is running in the docker container.
The daemon process is disabled because of the previous error when starting the daemon.
NX_DAEMON is set to false.
useDaemon is set to false in nx.json

NX_DAEMON env variable takes precedence:

If it is set to true, the daemon will always be used.
If it is set to false, the graph will always be computed in the current process.

Tip: If you want to debug project graph creation, run your command with NX_DAEMON=false.

Nx uses two layers of caching: the information about explicit dependencies stored on the disk and the information stored in the daemon process. To reset both run: nx reset.

Parameters

Name	Type
`opts`	`Object`
`opts.exitOnError`	`boolean`
`opts.resetDaemonClient?`	`boolean`

Returns

Promise<ProjectGraph>

defaultTasksRunner

▸ defaultTasksRunner(tasks, options, context?): any

any | Promise<{ [id: string]: TaskStatus }> will change to Promise<{ [id: string]: TaskStatus }> after Nx 15 is released.

Parameters

Name	Type
`tasks`	`Task`[]
`options`	`DefaultTasksRunnerOptions`
`context?`	`Object`
`context.daemon?`	`DaemonClient`
`context.hasher?`	`TaskHasher`
`context.initiatingProject?`	`string`
`context.nxArgs`	`NxArgs`
`context.nxJson`	`NxJsonConfiguration`<`string`[] \| `"*"`>
`context.projectGraph`	`ProjectGraph`
`context.target?`	`string`
`context.taskGraph?`	`TaskGraph`

Returns

any

detectPackageManager

▸ detectPackageManager(dir?): PackageManager

Detects which package manager is used in the workspace based on the lock file.

Parameters

Name	Type	Default value
`dir`	`string`	`''`

Returns

PackageManager

ensurePackage

▸ ensurePackage(tree, pkg, requiredVersion, options?): void

Deprecated

Use the other function signature without a Tree

Use a package that has not been installed as a dependency.

For example:

ensurePackage(tree, '@nx/jest', nxVersion);

Nx 15 and lower use @nrwl/ instead of @nx/

This install the @nx/jest@<nxVersion> and return the module When running with --dryRun, the function will throw when dependencies are missing. Returns null for ESM dependencies. Import them with a dynamic import instead.

Parameters

Name	Type	Description
`tree`	`Tree`	the file system tree
`pkg`	`string`	the package to check (e.g. @nx/jest)
`requiredVersion`	`string`	the version or semver range to check (e.g. ~1.0.0, >=1.0.0 <2.0.0)
`options?`	`Object`	-
`options.dev?`	`boolean`	-
`options.throwOnMissing?`	`boolean`	-

Returns

void

▸ ensurePackage<T>(pkg, version): T

Ensure that dependencies and devDependencies from package.json are installed at the required versions. Returns null for ESM dependencies. Import them with a dynamic import instead.

For example:

ensurePackage('@nx/jest', nxVersion);

Nx 15 and lower use @nrwl/ instead of @nx/

Type parameters

Name	Type
`T`	extends `unknown` = `any`

Parameters

Name	Type	Description
`pkg`	`string`	the package to install and require
`version`	`string`	the version to install if the package doesn't exist already

Returns

T

extractLayoutDirectory

▸ extractLayoutDirectory(directory): Object

Experimental

Parameters

Name	Type
`directory`	`string`

Returns

Object

Name	Type
`layoutDirectory`	`string`
`projectDirectory`	`string`

formatFiles

▸ formatFiles(tree): Promise<void>

Formats all the created or updated files using Prettier

Parameters

Name	Type	Description
`tree`	`Tree`	the file system tree

Returns

Promise<void>

generateFiles

▸ generateFiles(tree, srcFolder, target, substitutions): void

Generates a folder of files based on provided templates.

While doing so it performs two substitutions:

Substitutes segments of file names surrounded by __
Uses ejs to substitute values in templates

Examples:

generateFiles(tree, path.join(__dirname, 'files'), './tools/scripts', {
  tmpl: '',
  name: 'myscript',
});

This command will take all the files from the files directory next to the place where the command is invoked from. It will replace all __tmpl__ with '' and all __name__ with 'myscript' in the file names, and will replace all <%= name %> with myscript in the files themselves. tmpl: '' is a common pattern. With it you can name files like this: index.ts__tmpl__, so your editor doesn't get confused about incorrect TypeScript files.

Parameters

Name	Type	Description
`tree`	`Tree`	the file system tree
`srcFolder`	`string`	the source folder of files (absolute path)
`target`	`string`	the target folder (relative to the tree root)
`substitutions`	`Object`	an object of key-value pairs

Returns

void

getDependentPackagesForProject

▸ getDependentPackagesForProject(projectGraph, name): Object

Parameters

Name	Type
`projectGraph`	`ProjectGraph`
`name`	`string`

Returns

Object

Name	Type
`npmPackages`	`string`[]
`workspaceLibraries`	`WorkspaceLibrary`[]

getNpmPackageSharedConfig

▸ getNpmPackageSharedConfig(pkgName, version): SharedLibraryConfig | undefined

Build the Module Federation Share Config for a specific package and the specified version of that package.

Parameters

Name	Type	Description
`pkgName`	`string`	Name of the package to share
`version`	`string`	Version of the package to require by other apps in the Module Federation setup

Returns

SharedLibraryConfig | undefined

getOutputsForTargetAndConfiguration

▸ getOutputsForTargetAndConfiguration(task, node): string[]

Returns the list of outputs that will be cached.

Parameters

Name	Type	Description
`task`	`Pick`<`Task`, `"overrides"` \| `"target"`>	target + overrides
`node`	`ProjectGraphProjectNode`	ProjectGraphProjectNode object that the task runs against

Returns

string[]

getPackageManagerCommand

▸ getPackageManagerCommand(packageManager?, root?): PackageManagerCommands

Returns commands for the package manager used in the workspace. By default, the package manager is derived based on the lock file, but it can also be passed in explicitly.

Example:

execSync(`${getPackageManagerCommand().addDev} my-dev-package`);

Parameters

Name	Type	Default value	Description
`packageManager`	`PackageManager`	`undefined`	The package manager to use. If not provided, it will be detected based on the lock file.
`root`	`string`	`workspaceRoot`	The directory the commands will be ran inside of. Defaults to the current workspace's root.

Returns

PackageManagerCommands

getPackageManagerVersion

▸ getPackageManagerVersion(packageManager?): string

Returns the version of the package manager used in the workspace. By default, the package manager is derived based on the lock file, but it can also be passed in explicitly.

Parameters

Name	Type
`packageManager`	`PackageManager`

Returns

string

getProjects

▸ getProjects(tree): Map<string, ProjectConfiguration>

Get a map of all projects in a workspace.

Use readProjectConfiguration if only one project is needed.

Parameters

Name	Type
`tree`	`Tree`

Returns

Map<string, ProjectConfiguration>

getWorkspaceLayout

▸ getWorkspaceLayout(tree): Object

Returns workspace defaults. It includes defaults folders for apps and libs, and the default scope.

Example:

{ appsDir: 'apps', libsDir: 'libs', npmScope: 'myorg' }

Parameters

Name	Type	Description
`tree`	`Tree`	file system tree

Returns

Object

Name	Type	Description
`appsDir`	`string`	-
`libsDir`	`string`	-
`npmScope`	`string`	`Deprecated` This will be removed in Nx 17. Use getNpmScope instead.
`standaloneAsDefault`	`boolean`	-

getWorkspacePath

▸ getWorkspacePath(tree): "angular.json" | "workspace.json"

Deprecated

all projects are configured using project.json

Parameters

Name	Type
`tree`	`Tree`

Returns

"angular.json" | "workspace.json"

hashArray

▸ hashArray(content): string

Parameters

Name	Type
`content`	`string`[]

Returns

string

installPackagesTask

▸ installPackagesTask(tree, alwaysRun?, cwd?, packageManager?): void

Runs npm install or yarn install. It will skip running the install if package.json hasn't changed at all or it hasn't changed since the last invocation.

Parameters

Name	Type	Default value	Description
`tree`	`Tree`	`undefined`	the file system tree
`alwaysRun`	`boolean`	`false`	always run the command even if `package.json` hasn't changed.
`cwd`	`string`	`''`	-
`packageManager`	`PackageManager`	`undefined`	-

Returns

void

isStandaloneProject

▸ isStandaloneProject(tree, project): boolean

Returns if a project has a standalone configuration (project.json).

Deprecated

non-standalone projects were deprecated

Parameters

Name	Type	Description
`tree`	`Tree`	the file system tree
`project`	`string`	the project name

Returns

boolean

joinPathFragments

▸ joinPathFragments(...fragments): string

Normalized path fragments and joins them

Parameters

Name	Type
`...fragments`	`string`[]

Returns

string

mapRemotes

▸ mapRemotes(remotes, remoteEntryExt, determineRemoteUrl): Record<string, string>

Map remote names to a format that can be understood and used by Module Federation.

Parameters

Name	Type	Description
`remotes`	`Remotes`	The remotes to map
`remoteEntryExt`	`"js"` \| `"mjs"`	The file extension of the remoteEntry file
`determineRemoteUrl`	(`remote`: `string`) => `string`	The function used to lookup the URL of the served remote

Returns

Record<string, string>

mapRemotesForSSR

▸ mapRemotesForSSR(remotes, remoteEntryExt, determineRemoteUrl): Record<string, string>

Map remote names to a format that can be understood and used by Module Federation.

Parameters

Name	Type	Description
`remotes`	`Remotes`	The remotes to map
`remoteEntryExt`	`"js"` \| `"mjs"`	The file extension of the remoteEntry file
`determineRemoteUrl`	(`remote`: `string`) => `string`	The function used to lookup the URL of the served remote

Returns

Record<string, string>

moveFilesToNewDirectory

▸ moveFilesToNewDirectory(tree, oldDir, newDir): void

Analogous to cp -r oldDir newDir

Parameters

Name	Type
`tree`	`Tree`
`oldDir`	`string`
`newDir`	`string`

Returns

void

names

▸ names(name): Object

Util function to generate different strings based off the provided name.

Examples:

names('my-name'); // {name: 'my-name', className: 'MyName', propertyName: 'myName', constantName: 'MY_NAME', fileName: 'my-name'}
names('myName'); // {name: 'myName', className: 'MyName', propertyName: 'myName', constantName: 'MY_NAME', fileName: 'my-name'}

Parameters

Name	Type
`name`	`string`

Returns

Object

Name	Type
`className`	`string`
`constantName`	`string`
`fileName`	`string`
`name`	`string`
`propertyName`	`string`

normalizePath

▸ normalizePath(osSpecificPath): string

Coverts an os specific path to a unix style path

Parameters

Name	Type
`osSpecificPath`	`string`

Returns

string

offsetFromRoot

▸ offsetFromRoot(fullPathToDir): string

Calculates an offset from the root of the workspace, which is useful for constructing relative URLs.

Examples:

offsetFromRoot('apps/mydir/myapp/'); // returns "../../../"

Parameters

Name	Type	Description
`fullPathToDir`	`string`	directory path

Returns

string

parseJson

▸ parseJson<T>(input, options?): T

Parses the given JSON string and returns the object the JSON content represents. By default javascript-style comments and trailing commas are allowed.

Type parameters

Name	Type
`T`	extends `object` = `any`

Parameters

Name	Type	Description
`input`	`string`	JSON content as string
`options?`	`JsonParseOptions`	JSON parse options

Returns

T

Object the JSON content represents

parseTargetString

▸ parseTargetString(targetString): Target

@deprecated(v17) A project graph should be passed to parseTargetString for best accuracy.

Parameters

Name	Type
`targetString`	`string`

Returns

Target

▸ parseTargetString(targetString, projectGraph): Target

Parses a target string into {project, target, configuration}

Examples:

parseTargetString('proj:test', graph); // returns { project: "proj", target: "test" }
parseTargetString('proj:test:production', graph); // returns { project: "proj", target: "test", configuration: "production" }

Parameters

Name	Type	Description
`targetString`	`string`	target reference
`projectGraph`	`ProjectGraph`	-

Returns

Target

readAllWorkspaceConfiguration

▸ readAllWorkspaceConfiguration(): ProjectsConfigurations & NxJsonConfiguration

Deprecated

Use readProjectsConfigurationFromProjectGraph(await createProjectGraphAsync())

Returns

ProjectsConfigurations & NxJsonConfiguration

readCachedProjectGraph

▸ readCachedProjectGraph(): ProjectGraph

Synchronously reads the latest cached copy of the workspace's ProjectGraph.

Throws

if there is no cached ProjectGraph to read from

Returns

ProjectGraph

readJson

▸ readJson<T>(tree, path, options?): T

Reads a json file, removes all comments and parses JSON.

Type parameters

Name	Type
`T`	extends `object` = `any`

Parameters

Name	Type	Description
`tree`	`Tree`	file system tree
`path`	`string`	file path
`options?`	`JsonParseOptions`	Optional JSON Parse Options

Returns

T

readJsonFile

▸ readJsonFile<T>(path, options?): T

Reads a JSON file and returns the object the JSON content represents.

Type parameters

Name	Type
`T`	extends `object` = `any`

Parameters

Name	Type	Description
`path`	`string`	A path to a file.
`options?`	`JsonReadOptions`	JSON parse options

Returns

T

Object the JSON content of the file represents

readNxJson

▸ readNxJson(): NxJsonConfiguration | null

Deprecated

You must pass a Tree

Returns

NxJsonConfiguration | null

▸ readNxJson(tree): NxJsonConfiguration | null

Reads nx.json

Parameters

Name	Type
`tree`	`Tree`

Returns

NxJsonConfiguration | null

readProjectConfiguration

▸ readProjectConfiguration(tree, projectName): ProjectConfiguration

Reads a project configuration.

Throws

If supplied projectName cannot be found

Parameters

Name	Type	Description
`tree`	`Tree`	the file system tree
`projectName`	`string`	unique name. Often directories are part of the name (e.g., mydir-mylib)

Returns

ProjectConfiguration

readRootPackageJson

▸ readRootPackageJson(): Object

Returns

Object

Name	Type
`dependencies?`	{ `[key: string]`: `string`; }
`devDependencies?`	{ `[key: string]`: `string`; }

readTargetOptions

▸ readTargetOptions<T>(«destructured», context): T

Reads and combines options for a given target.

Works as if you invoked the target yourself without passing any command lint overrides.

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type
`«destructured»`	`Target`
`context`	`ExecutorContext`

Returns

T

readWorkspaceConfiguration

▸ readWorkspaceConfiguration(tree): WorkspaceConfiguration

Read general workspace configuration such as the default project or cli settings

This does not provide projects configuration, use readProjectConfiguration instead.

Deprecated

use readNxJson

Parameters

Name	Type
`tree`	`Tree`

Returns

WorkspaceConfiguration

removeDependenciesFromPackageJson

▸ removeDependenciesFromPackageJson(tree, dependencies, devDependencies, packageJsonPath?): GeneratorCallback

Remove Dependencies and Dev Dependencies from package.json

For example:

removeDependenciesFromPackageJson(tree, ['react'], ['jest']);

This will remove react and jest from the dependencies and devDependencies sections of package.json respectively.

Parameters

Name	Type	Default value	Description
`tree`	`Tree`	`undefined`	-
`dependencies`	`string`[]	`undefined`	Dependencies to be removed from the dependencies section of package.json
`devDependencies`	`string`[]	`undefined`	Dependencies to be removed from the devDependencies section of package.json
`packageJsonPath`	`string`	`'package.json'`	-

Returns

GeneratorCallback

Callback to uninstall dependencies only if necessary. undefined is returned if changes are not necessary.

removeProjectConfiguration

▸ removeProjectConfiguration(tree, projectName): void

Removes the configuration of an existing project.

Parameters

Name	Type	Description
`tree`	`Tree`	the file system tree
`projectName`	`string`	unique name. Often directories are part of the name (e.g., mydir-mylib)

Returns

void

reverse

▸ reverse(graph): ProjectGraph

Returns a new project graph where all the edges are reversed.

For instance, if project A depends on B, in the reversed graph B will depend on A.

Parameters

Name	Type
`graph`	`ProjectGraph`

Returns

ProjectGraph

runExecutor

▸ runExecutor<T>(targetDescription, overrides, context): Promise<AsyncIterableIterator<T>>

Loads and invokes executor.

This is analogous to invoking executor from the terminal, with the exception that the params aren't parsed from the string, but instead provided parsed already.

Apart from that, it works the same way:

it will load the workspace configuration
it will resolve the target
it will load the executor and the schema
it will load the options for the appropriate configuration
it will run the validations and will set the default
and, of course, it will invoke the executor

Example:

for await (const s of await runExecutor(
  { project: 'myproj', target: 'serve' },
  { watch: true },
  context
)) {
  // s.success
}

Note that the return value is a promise of an iterator, so you need to await before iterating over it.

Type parameters

Name	Type
`T`	extends `Object`

Parameters

Name	Type
`targetDescription`	`Target`
`overrides`	`Object`
`context`	`ExecutorContext`

Returns

Promise<AsyncIterableIterator<T>>

runTasksInSerial

▸ runTasksInSerial(...tasks): GeneratorCallback

Run tasks in serial

Parameters

Name	Type	Description
`...tasks`	`GeneratorCallback`[]	The tasks to run in serial.

Returns

GeneratorCallback

serializeJson

▸ serializeJson<T>(input, options?): string

Serializes the given data to a JSON string. By default the JSON string is formatted with a 2 space indentation to be easy readable.

Type parameters

Name	Type
`T`	extends `object` = `object`

Parameters

Name	Type	Description
`input`	`T`	Object which should be serialized to JSON
`options?`	`JsonSerializeOptions`	JSON serialize options

Returns

string

the formatted JSON representation of the object

sharePackages

▸ sharePackages(packages): Record<string, SharedLibraryConfig>

Create a dictionary of packages and their Module Federation Shared Config from an array of package names.

Lookup the versions of the packages from the root package.json file in the workspace.

Parameters

Name	Type	Description
`packages`	`string`[]	Array of package names as strings

Returns

Record<string, SharedLibraryConfig>

shareWorkspaceLibraries

▸ shareWorkspaceLibraries(libraries, tsConfigPath?): SharedWorkspaceLibraryConfig

Build an object of functions to be used with the ModuleFederationPlugin to share Nx Workspace Libraries between Hosts and Remotes.

Parameters

Name	Type	Description
`libraries`	`WorkspaceLibrary`[]	The Nx Workspace Libraries to share
`tsConfigPath`	`string`	The path to TS Config File that contains the Path Mappings for the Libraries

Returns

SharedWorkspaceLibraryConfig

stripIndents

▸ stripIndents(strings, ...values): string

Removes indents, which is useful for printing warning and messages.

Example:

stripIndents`
 Options:
 - option1
 - option2
`;

Parameters

Name	Type
`strings`	`TemplateStringsArray`
`...values`	`any`[]

Returns

string

stripJsonComments

▸ stripJsonComments(text, replaceCh?): string

Takes JSON with JavaScript-style comments and remove them. Optionally replaces every none-newline character of comments with a replaceCharacter

Parameters

Name	Type
`text`	`string`
`replaceCh?`	`string`

Returns

string

targetToTargetString

▸ targetToTargetString(target): string

Returns a string in the format "project:target[:configuration]" for the target

Parameters

Name	Type	Description
`target`	`Target`	target object Examples: `typescript targetToTargetString({ project: "proj", target: "test" }) // returns "proj:test" targetToTargetString({ project: "proj", target: "test", configuration: "production" }) // returns "proj:test:production"`

Returns

string

toJS

▸ toJS(tree): void

Rename and transpile any new typescript files created to javascript files

Parameters

Name	Type
`tree`	`Tree`

Returns

void

updateJson

▸ updateJson<T, U>(tree, path, updater, options?): void

Updates a JSON value to the file system tree

Type parameters

Name	Type
`T`	extends `object` = `any`
`U`	extends `object` = `T`

Parameters

Name	Type	Description
`tree`	`Tree`	File system tree
`path`	`string`	Path of JSON file in the Tree
`updater`	(`value`: `T`) => `U`	Function that maps the current value of a JSON document to a new value to be written to the document
`options?`	`JsonParseOptions` & `JsonSerializeOptions`	Optional JSON Parse and Serialize Options

Returns

void

updateNxJson

▸ updateNxJson(tree, nxJson): void

Update nx.json

Parameters

Name	Type
`tree`	`Tree`
`nxJson`	`NxJsonConfiguration`<`string`[] \| `"*"`>

Returns

void

updateProjectConfiguration

▸ updateProjectConfiguration(tree, projectName, projectConfiguration): void

Updates the configuration of an existing project.

Parameters

Name	Type	Description
`tree`	`Tree`	the file system tree
`projectName`	`string`	unique name. Often directories are part of the name (e.g., mydir-mylib)
`projectConfiguration`	`ProjectConfiguration`	project configuration

Returns

void

updateTsConfigsToJs

▸ updateTsConfigsToJs(tree, options): void

Parameters

Name	Type
`tree`	`Tree`
`options`	`Object`
`options.projectRoot`	`string`

Returns

void

updateWorkspaceConfiguration

▸ updateWorkspaceConfiguration(tree, workspaceConfig): void

Update general workspace configuration such as the default project or cli settings.

This does not update projects configuration, use updateProjectConfiguration or addProjectConfiguration instead.

Deprecated

use updateNxJson

Parameters

Name	Type
`tree`	`Tree`
`workspaceConfig`	`WorkspaceConfiguration`

Returns

void

visitNotIgnoredFiles

▸ visitNotIgnoredFiles(tree, dirPath?, visitor): void

Utility to act on all files in a tree that are not ignored by git.

Parameters

Name	Type	Default value
`tree`	`Tree`	`undefined`
`dirPath`	`string`	`tree.root`
`visitor`	(`path`: `string`) => `void`	`undefined`

Returns

void

workspaceLayout

▸ workspaceLayout(): Object

Returns information about where apps and libs will be created.

Returns

Object

Name	Type
`appsDir`	`string`
`libsDir`	`string`

writeJson

▸ writeJson<T>(tree, path, value, options?): void

Writes a JSON value to the file system tree

Type parameters

Name	Type
`T`	extends `object` = `object`

Parameters

Name	Type	Description
`tree`	`Tree`	File system tree
`path`	`string`	Path of JSON file in the Tree
`value`	`T`	Serializable value to write
`options?`	`JsonSerializeOptions`	Optional JSON Serialize Options

Returns

void

writeJsonFile

▸ writeJsonFile<T>(path, data, options?): void

Serializes the given data to JSON and writes it to a file.

Type parameters

Name	Type
`T`	extends `object` = `object`

Parameters

Name	Type	Description
`path`	`string`	A path to a file.
`data`	`T`	data which should be serialized to JSON and written to the file
`options?`	`JsonWriteOptions`	JSON serialize options

Returns

void

Module: @nx/devkit

Table of contents

Enumerations

Classes

Interfaces

Type Aliases

Variables

Functions

Enumerations

ChangeType

DependencyType

Classes

ProjectGraphBuilder

Workspaces

Interfaces

DefaultTasksRunnerOptions

ExecutorContext

ExecutorsJson

FileChange

FileData

GeneratorsJson

Hash

HasherContext

ImplicitJsonSubsetDependency

Type parameters

JsonParseOptions

JsonSerializeOptions

MigrationsJson

ModuleFederationConfig

NxAffectedConfig

NxJsonConfiguration

Type parameters

NxPlugin

ProjectConfiguration

ProjectFileMap

ProjectGraph

ProjectGraphDependency

ProjectGraphExternalNode

ProjectGraphProcessorContext

ProjectGraphProjectNode

ProjectsConfigurations

RemoteCache

SharedLibraryConfig

StringDeletion

StringInsertion

Target

TargetConfiguration

Type parameters

TargetDependencyConfig

Task

TaskGraph

TaskHasher

Tree

Workspace

Type Aliases

AdditionalSharedConfig

CustomHasher

Type declaration