Programmatic API

/**
 * Main Eleventy class for programmatic usage
 * @param input - Directory or filename for input/sources files
 * @param output - Directory serving as the target for writing output files  
 * @param options - Configuration options
 * @param eleventyConfig - Override config instance for centralized config re-use
 */
class Eleventy {
  constructor(
    input?: string,
    output?: string,
    options?: EleventyOptions,
    eleventyConfig?: TemplateConfig
  );
}

interface EleventyOptions {
  /** Called via CLI ('cli') or Programmatically ('script') */
  source?: 'cli' | 'script';
  /** One of build, serve, or watch */
  runMode?: 'build' | 'serve' | 'watch';
  /** Is Eleventy running in dry mode? */
  dryRun?: boolean;
  /** Override the config file path */
  configPath?: string;
  /** The top level directory the site pretends to reside in */
  pathPrefix?: string;
  /** Quiet mode override */
  quietMode?: boolean;
  /** Programmatic config function */
  config?: (eleventyConfig: UserConfig) => void;
  /** Input directory override */
  inputDir?: string;
  /** Force ESM or CJS mode instead of detecting from package.json */
  loader?: 'esm' | 'cjs' | 'auto';
}

import Eleventy from "@11ty/eleventy";

// Basic usage
const elev = new Eleventy("./src", "./_site");

// With options
const elev = new Eleventy("./src", "./_site", {
  runMode: "build",
  dryRun: false,
  pathPrefix: "/mysite/",
  config: (eleventyConfig) => {
    eleventyConfig.addFilter("uppercase", (str) => str.toUpperCase());
  }
});

// Reuse existing config
const existingConfig = new TemplateConfig();
const elev = new Eleventy("./src", "./_site", {}, existingConfig);

/**
 * Initialize Eleventy configuration and setup
 * @param options - Initialization options
 */
init(options?: { viaConfigReset?: boolean }): Promise<void>;

/**
 * Initialize configuration with custom overrides
 * @param initOverrides - Configuration overrides
 */
initializeConfig(initOverrides?: any): Promise<void>;

/**
 * Reset the configuration to initial state
 */
resetConfig(): void;

// Basic initialization
await elev.init();

// With config reset
await elev.init({ viaConfigReset: true });

// Manual config initialization
await elev.initializeConfig({ customOverride: true });

/**
 * Write templates to the file system
 * @returns Array with passthrough copy results and template results
 */
write(): Promise<[passthroughCopy: any[], templates: any[]]>;

/**
 * Render templates to a JSON object
 * @returns Array of template objects
 */
toJSON(): Promise<any[]>;

/**
 * Returns a stream of new line delimited (NDJSON) objects
 * @returns ReadableStream of template objects
 */
toNDJSON(): Promise<ReadableStream>;

/**
 * Execute build with specified output format
 * @param to - Output format: 'fs' (filesystem), 'json', or 'ndjson'
 * @returns Build results based on output format
 */
executeBuild(to?: 'fs' | 'json' | 'ndjson'): Promise<any>;

// Write to filesystem
const [passthroughResults, templateResults] = await elev.write();

// Get JSON output
const templates = await elev.toJSON();

// Stream NDJSON
const stream = await elev.toNDJSON();
stream.pipe(process.stdout);

// Explicit build execution
const results = await elev.executeBuild("json");

/**
 * Start watching files for changes and rebuild automatically
 * @returns Watch function for testing
 */
watch(): Promise<Function>;

/**
 * Stop file watching and close servers
 */
stopWatch(): Promise<void>;

/**
 * Serve Eleventy on specified port with development server
 * @param port - HTTP port to serve from (optional)
 */
serve(port?: number): Promise<void>;

/**
 * Initialize watch system dependencies
 */
initWatch(): Promise<void>;

/**
 * Get all files being watched
 * @returns Array of watched file paths
 */
getWatchedFiles(): Promise<string[]>;

// Start watching for changes
const watchFn = await elev.watch();

// Start development server
await elev.serve(8080);

// Initialize watching without starting
await elev.initWatch();

// Get watched files
const watchedFiles = await elev.getWatchedFiles();
console.log("Watching:", watchedFiles);

// Stop watching
await elev.stopWatch();

/**
 * Set dry run mode - don't write files to disk
 * @param isDryRun - Enable/disable dry run
 */
setDryRun(isDryRun: boolean): void;

/**
 * Set incremental build mode - only process changed files
 * @param isIncremental - Enable/disable incremental builds
 */
setIncrementalBuild(isIncremental: boolean): void;

/**
 * Set whether to process files on first run
 * @param ignoreInitialBuild - Skip initial build before watching
 */
setIgnoreInitial(ignoreInitialBuild: boolean): void;

/**
 * Update the path prefix used in the config
 * @param pathPrefix - New path prefix
 */
setPathPrefix(pathPrefix: string): void;

/**
 * Update template formats
 * @param formats - Comma-separated template formats
 */
setFormats(formats: string): void;

/**
 * Update the run mode of Eleventy
 * @param runMode - One of "build", "watch", or "serve"
 */
setRunMode(runMode: 'build' | 'watch' | 'serve'): void;

/**
 * Set specific file for incremental builds
 * @param incrementalFile - File path for incremental processing
 */
setIncrementalFile(incrementalFile: string): void;

/**
 * Clear incremental file setting
 */
unsetIncrementalFile(): void;

/**
 * Set verbose logging mode
 * @param isVerbose - Enable/disable verbose output
 */
setIsVerbose(isVerbose: boolean): void;

/**
 * Disable all logging output
 */
disableLogger(): void;

// Configure build behavior
elev.setDryRun(true);              // Don't write files
elev.setIncrementalBuild(true);    // Only process changed files
elev.setIgnoreInitial(true);       // Skip initial build
elev.setPathPrefix("/blog/");      // Set URL prefix
elev.setFormats("md,njk,html");    // Set template formats
elev.setRunMode("serve");          // Change to serve mode

// Incremental builds
elev.setIncrementalFile("./src/posts/new-post.md");

// Logging control
elev.setIsVerbose(false);          // Quiet mode
elev.disableLogger();              // No output

/** Input directory or file */
get input(): string;

/** Input file if specified */
get inputFile(): string;

/** Input directory */
get inputDir(): string;

/** Output directory */
get outputDir(): string;

/** Config file path */
get configPath(): string;

/** Path prefix for URLs */
get pathPrefix(): string;

/** Project directories configuration */
get directories(): ProjectDirectories;

/** Run mode (build, serve, watch) */
get runMode(): string;

/** Verbose mode status */
get verboseMode(): boolean;

/** Logger instance */
get logger(): ConsoleLogger;

/** Error handler instance */
get errorHandler(): EleventyErrorHandler;

/**
 * Restart Eleventy (clears caches and resets state)
 */
restart(): Promise<void>;

/**
 * Log build completion statistics
 * @returns Formatted log message with build stats
 */
logFinished(): string;

/**
 * Get current timestamp for benchmarking
 * @returns Performance timestamp
 */
getNewTimestamp(): number;

/**
 * Check if configuration needs reset based on changed files
 * @param changedFiles - Array of changed file paths
 * @returns Whether config reset is needed
 */
shouldTriggerConfigReset(changedFiles: string[]): boolean;

/**
 * Get the current Eleventy version
 * @returns Version string
 */
static getVersion(): string;

/**
 * Get CLI help text
 * @returns Help message with usage information
 */
static getHelp(): string;

// Get version info
console.log(Eleventy.getVersion()); // "3.1.2"

// Show help
console.log(Eleventy.getHelp());

// Instance methods
await elev.restart();              // Reset state
const stats = elev.logFinished();  // Get build stats
const timestamp = elev.getNewTimestamp();

interface ProjectDirectories {
  input: string;
  output: string;
  includes: string;
  layouts: string;
  data: string;
  inputFile?: string;
  inputGlob?: string;
}

interface ConsoleLogger {
  isVerbose: boolean;
  log(message: string): void;
  forceLog(message: string): void;
  logWithOptions(options: { message: string; color?: string; force?: boolean }): void;
  closeStream(): ReadableStream;
}

interface EleventyErrorHandler {
  isVerbose: boolean;
  logger: ConsoleLogger;
  error(error: Error, message?: string): void;
  fatal(error: Error, message?: string): void;
  warn(error: Error, message?: string): void;
}