Configuration Reference

Complete Reference

Every configuration option explained with examples. Use this as your single source of truth.

Quick Start

Recommended: Use the interactive wizard:

bash

npx fluent-gen-ts init

This creates fluentgen.config.js with guided prompts.

Or create manually:

javascript

/** @type {import('fluent-gen-ts').Config} */
export default {
  targets: [{ file: './src/types.ts', types: ['User'] }],
  generator: {
    outputDir: './src/builders',
  },
};

Then run:

bash

npx fluent-gen-ts batch

Complete Schema

typescript

interface Config {
  // Optional: What to generate (either targets or patterns)
  targets?: Target[];

  // Optional: File patterns to scan
  patterns?: string[];

  // Optional: Patterns to exclude
  exclude?: string[];

  // Optional: Generator settings (includes output dir and naming)
  generator?: GeneratorConfig;

  // Optional: TypeScript config
  tsConfigPath?: string;

  // Optional: Plugins
  plugins?: string[];

  // Optional: Monorepo support
  monorepo?: MonorepoConfig;
}

targets (Optional)

Specifies which types to generate builders for. Either targets or patterns must be provided.

Schema

typescript

interface Target {
  file: string; // Path to TypeScript file (glob supported)
  types?: string[]; // Type names to generate (optional - defaults to all exported types)
  outputFile?: string; // Custom output file path for this target
}

Examples

Single file, single type:

javascript

targets: [{ file: './src/types/user.ts', types: ['User'] }];

Single file, multiple types:

javascript

targets: [
  { file: './src/types/user.ts', types: ['User', 'Profile', 'Settings'] },
];

Multiple files:

javascript

targets: [
  { file: './src/types/user.ts', types: ['User', 'Profile'] },
  { file: './src/types/product.ts', types: ['Product', 'Category'] },
  { file: './src/types/order.ts', types: ['Order', 'OrderItem'] },
];

All types from a file:

javascript

targets: [{ file: './src/types/models.ts', types: ['*'] }];

Glob patterns:

javascript

targets: [{ file: './src/models/**/*.ts', types: ['*'] }];

Glob Performance

Using globs without specific types can be slow. Prefer specific files and types for faster generation.

generator (Optional)

Fine-tune builder generation behavior, output location, and naming conventions.

Schema

typescript

interface GeneratorConfig {
  outputDir?: string; // Output directory for generated builders
  useDefaults?: boolean; // Generate smart defaults (default: true)
  addComments?: boolean; // Add JSDoc comments (default: true)
  contextType?: string; // Custom context type name
  customCommonFilePath?: string; // Path to custom common file (if not using generated common.ts)
  naming?: NamingConfig; // File naming configuration
}

outputDir

Where generated builders will be written.

javascript

generator: {
  outputDir: './src/builders'; // Default: './builders'
}

Supports absolute or relative paths. Directory is created if it doesn't exist.

useDefaults

Generate default values for required properties.

true (default):

typescript

// Generated builder includes:
static defaults = {
  id: '',
  name: '',
  age: 0,
  isActive: false
};

false:

typescript

// No defaults generated
// User must provide all values

When to disable:

You want explicit value setting
Default values don't make sense for your domain
Performance-critical (minimal builder size)

addComments

Add JSDoc comments to generated methods.

true (default):

typescript

/**
 * Set the email property
 * @param value - The email value
 */
withEmail(value: string): this {
  return this.set('email', value);
}

false:

typescript

withEmail(value: string): this {
  return this.set('email', value);
}

When to disable:

Minimize file size
Comments add no value (self-documenting types)

contextType

Use custom context type for builders.

javascript

generator: {
  contextType: 'MyCustomContext';
}

Generated builders will use:

typescript

build(context?: MyCustomContext): T {
  // ...
}

See Custom Context for details.

customCommonFilePath

Path to your own custom common utilities file. When provided, fluent-gen-ts will:

Skip generating the default common.ts file
Configure all generated builders to import from your custom path

javascript

generator: {
  customCommonFilePath: '@/builders/common.js'; // Use path alias or relative path
}

When not provided (default behavior):

common.ts is automatically generated with shared builder utilities
Builders import from ./common.js

When provided:

No common.ts is generated (you provide your own)
Builders import from your specified path

This is useful when you want to:

Use a custom utilities file with additional features
Share common utilities across multiple projects
Use path aliases for imports (e.g., @/builders/common.js)

Example with custom common file:

javascript

generator: {
  outputDir: './src/builders',
  customCommonFilePath: '@/shared/fluent-builder-common.js'
}

You can create a custom common file using:

bash

npx fluent-gen-ts setup-common --output ./src/shared/fluent-builder-common.ts

naming

Configure output file naming conventions. See naming configuration below for details.

tsConfigPath (Optional)

Path to tsconfig.json for TypeScript compilation. Auto-detects if not specified.

javascript

tsConfigPath: './tsconfig.build.json';

Useful for:

Custom tsconfig locations
Build-specific configs
Monorepo shared configs

plugins (Optional)

Add plugins to customize generation.

Schema

typescript

type PluginConfig = (string | Plugin)[];

File Paths (Recommended)

javascript

plugins: [
  './plugins/validation.ts',
  './plugins/testing.ts',
  './plugins/database.ts',
];

Paths are relative to config file location.

Plugin Objects

javascript

import validationPlugin from './plugins/validation.ts';

export default {
  plugins: [
    validationPlugin, // Direct plugin object
    './plugins/testing.ts', // Or file path
  ],
};

npm Packages

javascript

plugins: [
  '@company/fluent-gen-validation', // From node_modules
  './plugins/custom.ts', // Local plugin
];

Execution Order

Plugins execute in array order:

javascript

plugins: [
  './plugins/type-transform.ts', // 1st
  './plugins/validation.ts', // 2nd
  './plugins/custom-methods.ts', // 3rd
];

Order Matters

Plugin order affects transformations. Specific plugins before generic ones!

See Plugin Guide for creating custom plugins.

monorepo (Optional)

Configure monorepo support for dependency resolution.

Schema

typescript

interface MonorepoConfig {
  enabled: boolean;
  dependencyResolutionStrategy?:
    | 'auto'
    | 'workspace-root'
    | 'hoisted'
    | 'local-only';
  workspaceRoot?: string;
  customPaths?: string[];
}

enabled

Enable monorepo dependency resolution.

javascript

monorepo: {
  enabled: true;
}

dependencyResolutionStrategy

How to resolve dependencies across packages.

'auto' (Recommended): Tries multiple strategies automatically:

javascript

monorepo: {
  enabled: true,
  dependencyResolutionStrategy: 'auto'
}

Tries in order:

Local node_modules
Hoisted dependencies
Package manager store (pnpm .pnpm)
Workspace root

'workspace-root': Look in workspace root first:

javascript

monorepo: {
  enabled: true,
  dependencyResolutionStrategy: 'workspace-root',
  workspaceRoot: '../../'  // Relative to config
}

'hoisted': Walk up directory tree (good for Yarn):

javascript

monorepo: {
  enabled: true,
  dependencyResolutionStrategy: 'hoisted'
}

'local-only': Only check local node_modules:

javascript

monorepo: {
  enabled: true,
  dependencyResolutionStrategy: 'local-only'
}

customPaths

Additional paths to search for dependencies:

javascript

monorepo: {
  enabled: true,
  customPaths: [
    './shared-dependencies',
    '../common/node_modules',
    '../../packages/*/node_modules'
  ]
}

Recommended for most monorepos:

javascript

monorepo: {
  enabled: true,
  dependencyResolutionStrategy: 'auto'  // Works with pnpm, yarn, npm
}

See Monorepo Guide for details.

patterns & exclude (Optional)

Alternative to targets for scanning files with patterns.

Schema

typescript

interface Config {
  patterns?: string[]; // Glob patterns to scan
  exclude?: string[]; // Patterns to exclude
}

Examples

Scan all TypeScript files:

javascript

export default {
  patterns: ['src/**/*.ts'],
  exclude: ['**/*.test.ts', '**/*.spec.ts'],
  generator: {
    outputDir: './src/builders',
  },
};

Multiple patterns:

javascript

export default {
  patterns: ['src/models/**/*.ts', 'src/types/**/*.ts'],
  exclude: ['**/*.test.ts', '**/node_modules/**'],
};

naming (Optional)

Customize output file naming. This is configured under generator.naming.

Schema

typescript

interface NamingConfig {
  convention?: 'camelCase' | 'kebab-case' | 'snake_case' | 'PascalCase';
  suffix?: string;
  transform?: string; // JavaScript function as string
  factoryTransform?: string; // Function name transform
}

convention

Predefined naming styles.

'camelCase':

javascript

generator: {
  naming: {
    convention: 'camelCase';
  }
}
// UserProfile → userProfile.builder.ts

'kebab-case' (recommended):

javascript

generator: {
  naming: {
    convention: 'kebab-case';
  }
}
// UserProfile → user-profile.builder.ts

'snake_case':

javascript

generator: {
  naming: {
    convention: 'snake_case';
  }
}
// UserProfile → user_profile.builder.ts

'PascalCase':

javascript

generator: {
  naming: {
    convention: 'PascalCase';
  }
}
// UserProfile → UserProfile.builder.ts

suffix

File suffix (default: 'builder'):

javascript

generator: {
  naming: {
    convention: 'kebab-case',
    suffix: 'factory'
  }
}
// UserProfile → user-profile.factory.ts

transform

Custom JavaScript function for file naming:

javascript

generator: {
  naming: {
    transform: `(typeName) => {
      return typeName
        .replace(/DTO$/, '')
        .toLowerCase() + '.gen';
    }`;
  }
}
// UserDTO → user.gen.ts

factoryTransform

Custom JavaScript function for factory function names:

javascript

generator: {
  naming: {
    factoryTransform: `(typeName) => {
      return 'create' + typeName;
    }`;
  }
}
// User → createUser() factory function

Examples

Standard kebab-case:

javascript

generator: {
  naming: {
    convention: 'kebab-case',
    suffix: 'builder'
  }
}

Custom suffix:

javascript

generator: {
  naming: {
    convention: 'camelCase',
    suffix: 'factory'
  }
}
// Result: userProfile.factory.ts

Custom transforms:

javascript

generator: {
  naming: {
    transform: `(typeName) => {
      const base = typeName.replace(/(DTO|Model|Entity)$/, '');
      return base.toLowerCase() + '.generated';
    }`,
    factoryTransform: `(typeName) => {
      return 'make' + typeName;
    }`
  }
}
// UserDTO → user.generated.ts with makeUser() function

Example Configs

Minimal

javascript

export default {
  targets: [{ file: './src/types.ts', types: ['User'] }],
  generator: { outputDir: './src/builders' },
};

Production

javascript

/** @type {import('fluent-gen-ts').Config} */
export default {
  targets: [
    { file: './src/types/user.ts', types: ['User', 'Profile'] },
    { file: './src/types/product.ts', types: ['Product'] },
  ],
  generator: {
    outputDir: './src/builders',
    naming: { convention: 'kebab-case' },
  },
  plugins: ['./plugins/validation.ts'],
};

Monorepo

javascript

export default {
  patterns: ['./src/models/**/*.ts'],
  exclude: ['**/*.test.ts'],
  generator: { outputDir: './src/builders' },
  monorepo: {
    enabled: true,
    dependencyResolutionStrategy: 'auto',
  },
};

More Examples

See Config Recipes for real-world configurations.

TypeScript Types

Enable autocomplete in your config:

javascript

/** @type {import('fluent-gen-ts').Config} */
export default {
  // TypeScript autocomplete works here!
  targets: [
    /*...*/
  ],
};

Or use a .ts config file:

typescript

import type { Config } from 'fluent-gen-ts';

const config: Config = {
  targets: [
    /*...*/
  ],
};

export default config;

Config Validation

fluent-gen-ts validates your config automatically. If there are issues, you'll see clear error messages pointing to the problem.

Use TypeScript autocomplete for validation while editing:

javascript

/** @type {import('fluent-gen-ts').Config} */
export default {
  // TypeScript will show errors for invalid options
};

Next Steps

📚 Config Recipes

Real-world examples: Configuration Recipes →

🔧 CLI Commands

Learn CLI usage: CLI Reference →

🔌 Plugins

Extend generation: Plugin System →

💡 Advanced Usage

Complex scenarios: Advanced Guide →

CLI Reference - Command reference
Configuration Recipes - Real-world configs
Troubleshooting - Common config issues
API Reference - Programmatic API

Configuration Reference ​

Quick Start ​

Complete Schema ​

targets (Optional) ​

Schema ​

Examples ​

generator (Optional) ​

Schema ​

outputDir ​

useDefaults ​

addComments ​

contextType ​

customCommonFilePath ​

naming ​

tsConfigPath (Optional) ​

plugins (Optional) ​

Schema ​

File Paths (Recommended) ​

Plugin Objects ​

npm Packages ​

Execution Order ​

monorepo (Optional) ​

Schema ​

enabled ​

dependencyResolutionStrategy ​

customPaths ​

patterns & exclude (Optional) ​

Schema ​

Examples ​

naming (Optional) ​

Schema ​

convention ​

suffix ​

transform ​

factoryTransform ​

Examples ​

Example Configs ​

Minimal ​

Production ​

Monorepo ​

TypeScript Types ​

Config Validation ​

Next Steps ​

📚 Config Recipes ​

🔧 CLI Commands ​

🔌 Plugins ​

💡 Advanced Usage ​

Related Resources ​

Configuration Reference

Quick Start

Complete Schema

targets (Optional)

Schema

Examples

generator (Optional)

Schema

outputDir

useDefaults

addComments

contextType

customCommonFilePath

naming

tsConfigPath (Optional)

plugins (Optional)

Schema

File Paths (Recommended)

Plugin Objects

npm Packages

Execution Order

monorepo (Optional)

Schema

enabled

dependencyResolutionStrategy

customPaths

patterns & exclude (Optional)

Schema

Examples

naming (Optional)

Schema

convention

suffix

transform

factoryTransform

Examples

Example Configs

Minimal

Production

Monorepo

TypeScript Types

Config Validation

Next Steps

📚 Config Recipes

🔧 CLI Commands

🔌 Plugins

💡 Advanced Usage

Related Resources