Creating files with a generator
Generators provide an API for managing files within your workspace. You can use generators to do things such as create, update, move, and delete files. Files with static or dynamic content can also be created.
The generator below shows you how to generate a library, and then scaffold out additional files with the newly created library.
First, you define a folder to store your static or dynamic templates used to generated files. This is commonly done in a files folder.
1happynrwl/
2├── apps/
3├── libs/
4│ └── my-plugin
5│ └── src
6│ └── generators
7│ └── my-generator/
8│ ├── files
9│ │ └── NOTES.md
10│ ├── index.ts
11│ └── schema.json
12├── nx.json
13├── package.json
14└── tsconfig.base.json
15The files can use EJS syntax to substitute variables and logic. See the EJS Docs to see more information about how to write these template files.
Example NOTES.md:
1Hello, my name is <%= name %>!
2Next, update the index.ts file for the generator, and generate the new files.
1import {
2 Tree,
3 formatFiles,
4 installPackagesTask,
5 generateFiles,
6 joinPathFragments,
7 readProjectConfiguration,
8} from '@nx/devkit';
9import { libraryGenerator } from '@nx/js';
10
11export default async function (tree: Tree, schema: any) {
12 await libraryGenerator(tree, { name: schema.name });
13 const libraryRoot = readProjectConfiguration(tree, schema.name).root;
14 generateFiles(
15 tree, // the virtual file system
16 joinPathFragments(__dirname, './files'), // path to the file templates
17 libraryRoot, // destination path of the files
18 schema // config object to replace variable in file templates
19 );
20 await formatFiles(tree);
21 return () => {
22 installPackagesTask(tree);
23 };
24}
25The exported function first creates the library, then creates the additional files in the new library's folder.
Next, run the generator:
Use the -d or --dry-run flag to see your changes without applying them. This will let you see what the command will do to your workspace.
❯
nx generate my-generator mylib
The following information will be displayed.
❯
nx generate my-generator mylib
1CREATE libs/mylib/README.md
2CREATE libs/mylib/.babelrc
3CREATE libs/mylib/src/index.ts
4CREATE libs/mylib/src/lib/mylib.spec.ts
5CREATE libs/mylib/src/lib/mylib.ts
6CREATE libs/mylib/tsconfig.json
7CREATE libs/mylib/tsconfig.lib.json
8UPDATE tsconfig.base.json
9UPDATE nx.json
10CREATE libs/mylib/.eslintrc.json
11CREATE libs/mylib/jest.config.ts
12CREATE libs/mylib/tsconfig.spec.json
13UPDATE jest.config.ts
14CREATE libs/mylib/NOTES.md
15libs/mylib/NOTES.md will contain the content with substituted variables:
1Hello, my name is mylib!
2Dynamic File Names
If you want the generated file or folder name to contain variable values, use __variable__. So NOTES-for-__name__.md would be resolved to NOTES_for_mylib.md in the above example.
Overwrite mode
By default, generators overwrite files when they already exist.
You can customize this behaviour with an optional argument to generateFiles that can take one of three values:
OverwriteStrategy.Overwrite(default): all generated files are created and overwrite existing target files if any.OverwriteStrategy.KeepExisting: generated files are created only when target file does not exist. Existing target files are kept as is.OverwriteStrategy.ThrowIfExisting: if a target file already exists, an exception is thrown. Suitable when a pristine target environment is expected.
EJS Syntax Quickstart
The EJS syntax can do much more than replace variable names with values. Here are some common techniques.
- Pass a function into the template:
1// template file
2This is my <%= uppercase(name) %>
31// typescript file
2function uppercase(val: string) {
3 return val.toUpperCase();
4}
5
6// later
7
8generateFiles(tree, join(__dirname, './files'), libraryRoot, {
9 uppercase,
10 name: schema.name,
11});
12- Use javascript for control flow in the template:
1<% if(shortVersion) { %>
2This is the short version.
3<% } else {
4 for(let x=0; x<numRepetitions; x++) {
5 %>
6 This text will be repeated <%= numRepetitions %> times.
7<% } // end for loop
8} // end else block %>
91// typescript file
2generateFiles(tree, join(__dirname, './files'), libraryRoot, {
3 shortVersion: false,
4 numRepetitions: 3,
5});
6