Docs for local generators and executors

[jasongerbes]

Documentation issue

• Reporting a typo
• Reporting a documentation bug
• Documentation improvement
• Documentation feedback

Is there a specific documentation page you are reporting?

• Workspace Generators
• Creating Custom Executors

Additional context or description

Hey @AgentEnder, thanks for completing #9116. This change is going to make local plugins much more usable.

I feel some doc changes may be required to clarify the process of creating and using local generators and executors now that they don't need to be manually compiled:

• Has the nx workspace-generator command been deprecated? (also, does Nx Console need to be updated?)
• Can the 'compiling' portion of Compiling and Running your Executor be removed?
• Clarify usage of generators and executors within the /tools directory, including the required package.json file(s).
• The docs suggest a new executor.json file per-executor, rather than one for the directory, e.g. /tools/executors/executors.json. Is this the recommended approach?
• The nav link is called "Using Custom Builders" instead of "Using Custom Executors".

[AgentEnder]

Hey!

Thanks for taking the time to create the issue! Some docs changes are certainly planned before this change is live, so look forward to them.

Until then, the process isn't changed.

[jasongerbes]

Hey @AgentEnder, thanks for the fast reply!

Any idea when this change will be live?

[AgentEnder]

Not particularly, it should be in 13.10, should be early betas soonish to test.

[kristianmandrup]

Awesome! Waiting for this before starting my first Nx plugins. Neo4J and Passport generators for NestJS.

[kristianmandrup]

BTW, where can I find documentation for @nx/devkit?

From https://nx.dev/generators/workspace-generators

The @nrwl/devkit package provides many utility functions that can be used in schematics to help with modifying files, reading and updating configuration files, and working with an Abstract Syntax Tree (AST).

https://nx.dev/guides/nx-devkit-angular-devkit

At the top it says

Note: this document covers the difference between Nx Devkit and Angular Devkit. See the Nx Devkit guide for more in-depth details about Nx Devkit.

However the link the the Nx Devkit guide no longer exists.

[kristianmandrup]

What I could find in the code

getWorkspaceLayout(tree: Tree)

invokeNxGenerator<T = any>(
  generator: Generator<T>,
  options: T,
  skipWritingConfigInOldFormat?: boolean

moveFilesToNewDirectory(
  tree: Tree,
  oldDir: string,
  newDir: string
)

names(name: string): {
  name: string;
  className: string;
  propertyName: string;
  constantName: string;
  fileName: string;
} 

offsetFromRoot(fullPathToDir: string): string

applyChangesToString(
  text: string,
  changes: StringChange[]
): 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')
});

Please someone improve the docs for writing generators and the utility functions available. Also please help improve the toolkit for this, especially for working with ASTs such as demonstrated in this video https://www.youtube.com/watch?v=9CsHV4umWR8 and https://www.youtube.com/watch?v=1eHlaVoeDfU&t=633s

The generator using AST mods is available here: https://github.com/nxtend-team/nxtend/tree/main/packages/ionic-angular/src/generators/page

The AST mod part is here: https://github.com/nxtend-team/nxtend/blob/main/packages/ionic-angular/src/generators/page/lib/update-routing-file.ts

PS: This comment should likely be turned into a documentation feature request

[AgentEnder]

I'm going to close this, some docs were added as part of #9564

However the link the the Nx Devkit guide no longer exists.

https://nx.dev/using-nx/nx-devkit

PS: This comment should likely be turned into a documentation feature request

Yeah, that'd be my recommendation. Do you care to pull the meat out of the requests and post it separately? Thanks!

[pascalbe-dev]

This link (https://nx.dev/using-nx/nx-devkit) points me to the getting started intro page. Is this intended?

I can not find the documentation from the pull request on the website. Please point me to the correct URL, in case I missed it. :)

[AgentEnder]

#9730 will fix it, definitely unintended.

[github-actions]

This issue has been closed for more than 30 days. If this issue is still occuring, please open a new issue with more recent context.