Skip to content

Latest commit

 

History

History
1684 lines (1027 loc) · 47.8 KB

index.md

File metadata and controls

1684 lines (1027 loc) · 47.8 KB

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

Table of contents

Project Graph Enumerations

Utils Enumerations

Project Graph Classes

Commands Interfaces

Other Interfaces

Project Graph Interfaces

Tree Interfaces

Utils Interfaces

Workspace Interfaces

Generators Type aliases

Other Type aliases

Package Manager Type aliases

Project Graph Type aliases

Utils Type aliases

Workspace Type aliases

Logger Variables

Functions

Project Graph Enumerations

DependencyType

DependencyType: Object


Utils Enumerations

ChangeType

ChangeType: Object

Project Graph Classes

ProjectGraphBuilder

ProjectGraphBuilder: Object

Commands Interfaces

Target

Target: Object


Other Interfaces

NxPlugin

NxPlugin: Object

A plugin for Nx


Project Graph Interfaces

FileData

FileData: Object


ProjectFileMap

ProjectFileMap: Object


ProjectGraph

ProjectGraph<T>: Object

Type parameters

Name Type
T any

ProjectGraphDependency

ProjectGraphDependency: Object


ProjectGraphExternalNode

ProjectGraphExternalNode: Object


ProjectGraphProcessorContext

ProjectGraphProcessorContext: Object


ProjectGraphProjectNode

ProjectGraphProjectNode<T>: Object

Type parameters

Name Type
T any

ProjectGraphV4

ProjectGraphV4<T>: Object

Type parameters

Name Type
T any

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


Other Type aliases

ProjectTargetConfigurator

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

Type declaration

▸ (file): Record<string, TargetConfiguration>

Parameters
Name Type
file string
Returns

Record<string, TargetConfiguration>


Package Manager Type aliases

PackageManager

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


Project Graph Type aliases

ProjectGraphNode

Ƭ ProjectGraphNode<T>: ProjectGraphProjectNode<T> | ProjectGraphExternalNode

Type parameters

Name Type
T any

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

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:

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. 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 or the associated project.json file. The utility will update either 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 project configuration
standalone? boolean 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:

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


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

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:

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


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:

execSync(`${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>

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
appsDir string
libsDir string
npmScope string
standaloneAsDefault boolean

getWorkspacePath

getWorkspacePath(tree): "/angular.json" | "/workspace.json" | null

Parameters

Name Type
tree Tree

Returns

"/angular.json" | "/workspace.json" | null


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:

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

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

parseTargetString('proj:test'); // returns { project: "proj", target: "test" }
parseTargetString('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

Reads a project configuration.

The project configuration is stored in workspace.json or the associated project.json file. The utility will read from either file.

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


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


registerTsProject

Const registerTsProject(path, configFilename?): any

Optionally, if swc-node and tsconfig-paths are available in the current workspace, apply the require register hooks so that .ts files can be used for writing custom workspace projects.

If ts-node and tsconfig-paths are not available, the user can still provide an index.js file in the root of their project and the fundamentals will still work (but workspace path mapping will not, for example).

Parameters

Name Type Default value
path string undefined
configFilename string 'tsconfig.json'

Returns

any


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.

The project configuration is stored in workspace.json or the associated project.json file. The utility will update either file.

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:

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

stripIndents`
 Options:
 - option1
 - option2
`;

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


updateProjectConfiguration

updateProjectConfiguration(tree, projectName, projectConfiguration): void

Updates the configuration of an existing project.

The project configuration is stored in workspace.json or the associated project.json file. The utility will update either 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 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 Default value
tree Tree undefined
dirPath string tree.root
visitor (path: string) => void undefined

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