Module: index

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).

Project Graph Interfaces

Tree Interfaces

Utils Interfaces

Workspace Interfaces

Generators Type aliases

WorkspaceConfiguration

Package Manager Type aliases

PackageManager

Utils Type aliases

StringChange

Workspace Type aliases

Logger Variables

logger

Functions

Project Graph Enumerations

DependencyType

• DependencyType: Object

Utils Enumerations

ChangeType

• ChangeType: Object

Project Graph Classes

ProjectGraphBuilder

• ProjectGraphBuilder: Object

Commands Interfaces

Target

• Target: Object

Project Graph Interfaces

FileData

• FileData: Object

NxPlugin

• NxPlugin: Object

ProjectFileMap

• ProjectFileMap: Object

ProjectGraph

• ProjectGraph<T>: Object

Type parameters

Name	Type
`T`	`any`

ProjectGraphDependency

• ProjectGraphDependency: Object

ProjectGraphNode

• ProjectGraphNode<T>: Object

Type parameters

Name	Type
`T`	`any`

ProjectGraphProcessorContext

• ProjectGraphProcessorContext: Object

Tree Interfaces

FileChange

• FileChange: Object

Tree

• Tree: Object

Utils Interfaces

JsonParseOptions

• JsonParseOptions: Object

JsonSerializeOptions

• JsonSerializeOptions: Object

StringDeletion

• StringDeletion: Object

StringInsertion

• StringInsertion: Object

Workspace Interfaces

ExecutorContext

• ExecutorContext: Object

ImplicitJsonSubsetDependency

• ImplicitJsonSubsetDependency<T>: Object

Type parameters

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

NxAffectedConfig

• NxAffectedConfig: Object

NxJsonConfiguration

• NxJsonConfiguration<T>: Object

Type parameters

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

NxJsonProjectConfiguration

• NxJsonProjectConfiguration: Object

ProjectConfiguration

• ProjectConfiguration: Object

TargetConfiguration

• TargetConfiguration: Object

TargetDependencyConfig

• TargetDependencyConfig: Object

Task

• Task: Object

TaskGraph

• TaskGraph: Object

Workspace

• Workspace: Object

WorkspaceJsonConfiguration

• WorkspaceJsonConfiguration: Object

Generators Type aliases

WorkspaceConfiguration

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

Package Manager Type aliases

PackageManager

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

Utils Type aliases

StringChange

Ƭ StringChange: StringInsertion | StringDeletion

Workspace Type aliases

Executor

Ƭ Executor<T>: (options: T, context: ExecutorContext) => Promise<Object> | AsyncIterableIterator<Object>

Type parameters

Name	Type
`T`	`any`

Type declaration

▸ (options, context): Promise<Object> | AsyncIterableIterator<Object>

Implementation of a target of a project

Parameters

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

Returns

Promise<Object> | AsyncIterableIterator<Object>

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>

ImplicitDependencyEntry

Ƭ ImplicitDependencyEntry<T>: Object

Type parameters

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

Index signature

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

ProjectType

Ƭ ProjectType: "library" | "application"

TaskGraphExecutor

Ƭ TaskGraphExecutor<T>: (taskGraph: TaskGraph, options: Record<string, T>, overrides: T, context: ExecutorContext) => Promise<Record<string, Object>>

Type parameters

Name	Type
`T`	`any`

Type declaration

▸ (taskGraph, options, overrides, context): Promise<Record<string, Object>>

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, Object>>

Logger Variables

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`

Functions

addDependenciesToPackageJson

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

Add Dependencies and Dev Dependencies to package.json

For example:

1addDependenciesToPackageJson(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. undefined is returned if changes are not necessary.

addProjectConfiguration

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

Adds project configuration to the Nx workspace.

The project configuration is stored in workspace.json and nx.json. The utility will update both files.

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` & `NxJsonProjectConfiguration`	`undefined`	project configuration
`standalone`	`boolean`	`false`	should the project use package.json? If false, the project config is inside workspace.json

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:

1const code = `bootstrap({
2  target: document.querySelector('#app')
3})`;
4
5const indexOfPropertyName = 13; // Usually determined by analyzing an AST.
6const updatedCode = applyChangesToString(code, [
7  {
8    type: ChangeType.Insert,
9    index: indexOfPropertyName,
10    text: 'element',
11  },
12  {
13    type: ChangeType.Delete,
14    start: indexOfPropertyName,
15    length: 6,
16  },
17]);
18
19bootstrap({
20  element: document.querySelector('#app'),
21});

Parameters

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

Returns

string

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): (options: 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
`generator`	`Generator`<`T`>

Returns

fn

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

Parameters

Name	Type
`options`	`T`

Returns

fn

▸ (tree, context): Promise<any>

Parameters

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

Returns

Promise<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

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:

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

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

getPackageManagerCommand

▸ getPackageManagerCommand(packageManager?): 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:

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

Parameters

Name	Type
`packageManager`	`PackageManager`

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 & NxJsonProjectConfiguration>

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 & NxJsonProjectConfiguration>

getWorkspaceLayout

▸ getWorkspaceLayout(tree): Object

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

Example:

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

Parameters

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

Returns

Object

Name	Type
`appsDir`	`string`
`libsDir`	`string`
`npmScope`	`string`
`standaloneAsDefault`	`boolean`

getWorkspacePath

▸ getWorkspacePath(tree): string

Parameters

Name	Type
`tree`	`Tree`

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).

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

moveFilesToNewDirectory

▸ moveFilesToNewDirectory(tree, oldDir, newDir): void

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:

1names('my-name'); // {name: 'my-name', className: 'MyName', propertyName: 'myName', constantName: 'MY_NAME', fileName: 'my-name'}
2names('myName'); // {name: 'my-name', 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:

1offsetFromRoot('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 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

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

Examples:

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

Parameters

Name	Type	Description
`targetString`	`string`	target reference

Returns

Target

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

readProjectConfiguration

▸ readProjectConfiguration(tree, projectName): ProjectConfiguration & NxJsonProjectConfiguration

Reads a project configuration.

The project configuration is stored in workspace.json and nx.json. The utility will read both files.

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 & NxJsonProjectConfiguration

readTargetOptions

▸ readTargetOptions<T>(__namedParameters, 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
`__namedParameters`	`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.

Parameters

Name	Type
`tree`	`Tree`

Returns

WorkspaceConfiguration

removeDependenciesFromPackageJson

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

Remove Dependencies and Dev Dependencies from package.json

For example:

1removeDependenciesFromPackageJson(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.

The project configuration is stored in workspace.json and nx.json. The utility will update both files.

Parameters

Name	Type
`tree`	`Tree`
`projectName`	`string`

Returns

void

runExecutor

▸ runExecutor<T>(targetDescription, options, 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:

1for await (const s of await runExecutor(
2  { project: 'myproj', target: 'serve' },
3  { watch: true },
4  context
5)) {
6  // s.success
7}

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`	`Object`
`targetDescription.configuration?`	`string`
`targetDescription.project`	`string`
`targetDescription.target`	`string`
`options`	`Object`
`context`	`ExecutorContext`

Returns

Promise<AsyncIterableIterator<T>>

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 intendation 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

stripIndents

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

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

Example:

1stripIndents`
2 Options:
3 - option1
4 - option2
5`;

Parameters

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

Returns

string

stripJsonComments

▸ Const 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(__namedParameters): string

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

Parameters

Name	Type
`__namedParameters`	`Target`

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

updateProjectConfiguration

▸ updateProjectConfiguration(tree, projectName, projectConfiguration): void

Updates the configuration of an existing project.

The project configuration is stored in workspace.json and nx.json. The utility will update both files.

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` & `NxJsonProjectConfiguration`	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.

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
`tree`	`Tree`
`dirPath`	`string`
`visitor`	(`path`: `string`) => `void`

Returns

void

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: index

Table of contents

Project Graph Enumerations

Utils Enumerations

Project Graph Classes

Commands Interfaces

Project Graph Interfaces

Tree Interfaces

Utils Interfaces

Workspace Interfaces

Generators Type aliases

Package Manager Type aliases

Utils Type aliases

Workspace Type aliases

Logger Variables

Functions

Project Graph Enumerations

DependencyType

Utils Enumerations

ChangeType

Project Graph Classes

ProjectGraphBuilder

Commands Interfaces

Target

Project Graph Interfaces

FileData

NxPlugin

ProjectFileMap

ProjectGraph

Type parameters

ProjectGraphDependency

ProjectGraphNode

Type parameters

ProjectGraphProcessorContext

Tree Interfaces

FileChange

Tree

Utils Interfaces

JsonParseOptions

JsonSerializeOptions

StringDeletion

StringInsertion

Workspace Interfaces

ExecutorContext

ImplicitJsonSubsetDependency

Type parameters

NxAffectedConfig

NxJsonConfiguration

Type parameters

NxJsonProjectConfiguration

ProjectConfiguration

TargetConfiguration

TargetDependencyConfig

Task

TaskGraph

Workspace

WorkspaceJsonConfiguration

Generators Type aliases

WorkspaceConfiguration

Package Manager Type aliases

PackageManager

Utils Type aliases

StringChange

Workspace Type aliases

Executor

Type parameters

Type declaration

Parameters

Returns

Generator

Type parameters

Type declaration

Parameters

Returns

GeneratorCallback

Type declaration

Returns

ImplicitDependencyEntry

Type parameters

Index signature