Generators

/**
 * Creates a new TypeScript/JavaScript library with comprehensive configuration options
 * @param tree - The virtual file system tree
 * @param schema - Library generation configuration
 * @returns Promise resolving to a GeneratorCallback for additional setup
 */
function libraryGenerator(
  tree: Tree,
  schema: LibraryGeneratorSchema
): Promise<GeneratorCallback>;

interface LibraryGeneratorSchema {
  directory: string;                    // Required: Library directory path
  name?: string;                        // Library name (inferred from directory if not provided)
  skipFormat?: boolean;                 // Skip formatting generated files
  tags?: string;                        // Comma-separated tags for the library
  skipTsConfig?: boolean;               // Skip TypeScript configuration updates
  skipPackageJson?: boolean;            // Skip package.json updates
  includeBabelRc?: boolean;             // Include .babelrc configuration
  unitTestRunner?: 'jest' | 'vitest' | 'none'; // Test runner selection
  linter?: Linter | LinterType;         // Linting configuration
  testEnvironment?: 'jsdom' | 'node';   // Test environment selection
  importPath?: string;                  // Custom import path for the library
  js?: boolean;                         // Generate JavaScript instead of TypeScript
  pascalCaseFiles?: boolean;            // Use PascalCase for generated file names
  strict?: boolean;                     // Enable strict TypeScript compilation
  publishable?: boolean;                // Make library publishable to npm
  buildable?: boolean;                  // Make library buildable
  setParserOptionsProject?: boolean;    // Set parserOptions.project for ESLint
  config?: 'workspace' | 'project' | 'npm-scripts'; // Configuration strategy
  compiler?: Compiler;                  // Compiler selection: 'tsc' | 'swc'
  bundler?: Bundler;                   // Bundler selection
  skipTypeCheck?: boolean;              // Skip type checking in build
  minimal?: boolean;                    // Generate minimal library structure
  rootProject?: boolean;                // Generate as root project
  simpleName?: boolean;                 // Use simple naming (deprecated)
  addPlugin?: boolean;                  // Add plugin to workspace
  useProjectJson?: boolean;             // Use project.json configuration
  useTscExecutor?: boolean;             // Use TypeScript executor
}

type Compiler = 'tsc' | 'swc';
type Bundler = 'swc' | 'tsc' | 'rollup' | 'vite' | 'esbuild' | 'none';

import { Tree } from "@nx/devkit";
import { libraryGenerator } from "@nx/js";

// Create a publishable TypeScript library with Jest testing
await libraryGenerator(tree, {
  directory: 'libs/data-utils',
  name: 'data-utils',
  bundler: 'rollup',
  unitTestRunner: 'jest',
  linter: 'eslint',
  publishable: true,
  buildable: true,
  importPath: '@myorg/data-utils'
});

/**
 * Converts a TypeScript project to use SWC instead of TSC for compilation
 * @param tree - The virtual file system tree
 * @param schema - Conversion configuration
 * @returns Promise resolving to a GeneratorCallback for dependency updates
 */
function convertToSwcGenerator(
  tree: Tree,
  schema: ConvertToSwcGeneratorSchema
): Promise<GeneratorCallback>;

interface ConvertToSwcGeneratorSchema {
  project: string;                      // Required: Project name to convert
  targets?: string[];                   // Build targets to convert (default: ['build'])
}

import { Tree } from "@nx/devkit";
import { convertToSwcGenerator } from "@nx/js";

// Convert a library to use SWC compilation
await convertToSwcGenerator(tree, {
  project: 'my-lib',
  targets: ['build', 'test']
});

/**
 * Sets up Prettier code formatting for the workspace
 * @param tree - The virtual file system tree
 * @param options - Prettier setup configuration
 * @returns Promise resolving to a GeneratorCallback for dependency installation
 */
function setupPrettierGenerator(
  tree: Tree,
  options: GeneratorOptions
): Promise<GeneratorCallback>;

interface GeneratorOptions {
  skipFormat?: boolean;                 // Skip formatting generated files
  skipPackageJson?: boolean;            // Skip package.json updates
}

import { Tree } from "@nx/devkit";
import { setupPrettierGenerator } from "@nx/js";

// Set up Prettier with default configuration
await setupPrettierGenerator(tree, {
  skipFormat: false,
  skipPackageJson: false
});

/**
 * Sets up Verdaccio local package registry for the workspace
 * @param tree - The virtual file system tree
 * @param options - Verdaccio setup configuration
 * @returns Promise resolving to a GeneratorCallback for dependency installation
 */
function setupVerdaccio(
  tree: Tree,
  options: SetupVerdaccioGeneratorSchema
): Promise<GeneratorCallback>;

interface SetupVerdaccioGeneratorSchema {
  skipFormat: boolean;                  // Skip formatting generated files
}

import { Tree } from "@nx/devkit";
import { setupVerdaccio } from "@nx/js";

// Set up local Verdaccio registry
await setupVerdaccio(tree, {
  skipFormat: false
});

/**
 * Updates version information for releases across workspace dependencies
 * @param tree - The virtual file system tree
 * @param options - Version release configuration
 * @returns Promise resolving to a GeneratorCallback for additional setup
 */
function releaseVersionGenerator(
  tree: Tree,
  options: ReleaseVersionGeneratorSchema
): Promise<GeneratorCallback>;

interface ReleaseVersionGeneratorSchema {
  // Internal schema - specific options not publicly documented
  [key: string]: any;
}

/**
 * Synchronizes TypeScript project references based on project dependencies
 * @param tree - The virtual file system tree
 * @returns Promise resolving to sync results with out-of-sync details
 */
function typescriptSyncGenerator(tree: Tree): Promise<SyncGeneratorResult>;

interface SyncGeneratorResult {
  outOfSyncMessage?: string;           // Description of sync issues found
  outOfSyncDetails?: string[];         // Detailed list of files that were out of sync
}

import { Tree } from "@nx/devkit";
import { typescriptSyncGenerator } from "@nx/js";

// Sync TypeScript project references
const result = await typescriptSyncGenerator(tree);
if (result.outOfSyncMessage) {
  console.log('TypeScript references were updated:', result.outOfSyncMessage);
}

/**
 * Adds build configuration to an existing project
 * @param tree - The virtual file system tree
 * @param options - Build setup configuration
 * @returns Promise resolving to a GeneratorCallback for any additional setup
 */
function setupBuildGenerator(
  tree: Tree,
  options: SetupBuildGeneratorSchema
): Promise<GeneratorCallback>;

interface SetupBuildGeneratorSchema {
  project: string;                                              // Required: Project name
  bundler: 'tsc' | 'swc' | 'vite' | 'rollup' | 'esbuild';     // Required: Bundler selection
  main?: string;                                                // Main entry file
  tsConfig?: string;                                            // TypeScript configuration file
  buildTarget?: string;                                         // Build target name
}

import { Tree } from "@nx/devkit";
import { setupBuildGenerator } from "@nx/js";

// Add Rollup build configuration to a project
await setupBuildGenerator(tree, {
  project: 'my-existing-lib',
  bundler: 'rollup',
  main: 'src/index.ts',
  buildTarget: 'build'
});

const callback = await libraryGenerator(tree, options);
// Execute callback to install dependencies and perform additional setup
await callback();

import { Tree, writeJson, generateFiles } from "@nx/devkit";

// Generators receive a Tree instance for file operations
function myGenerator(tree: Tree, options: MyOptions) {
  // Add files
  generateFiles(tree, joinPathFragments(__dirname, 'files'), '.', options);
  
  // Modify package.json
  const packageJson = readJson(tree, 'package.json');
  packageJson.scripts.build = 'nx build';
  writeJson(tree, 'package.json', packageJson);
  
  return () => {
    // Return callback for post-generation tasks
  };
}