Development Tools

/**
 * Start development server on specified port
 * @param port - HTTP port number (optional)
 * @returns Server instance promise
 */
serve(port?: number): Promise<void>;

/**
 * Configure development server options
 * @param options - Server configuration options
 * @param override - Whether to override existing options completely
 */
setServerOptions(options?: ServerOptions, override?: boolean): void;

/**
 * Set server passthrough copy behavior during development
 * @param behavior - Copy behavior mode
 */
setServerPassthroughCopyBehavior(behavior: 'copy' | 'passthrough'): void;

interface ServerOptions {
  /** Server port number */
  port?: number;
  
  /** Show server on all network interfaces */
  showAllHosts?: boolean;
  
  /** Show Eleventy version in output */
  showVersion?: boolean;
  
  /** Response encoding */
  encoding?: string;
  
  /** Enable/disable live reload */
  liveReload?: boolean;
  
  /** Delay before reload (milliseconds) */
  reloadDelay?: number;
  
  /** Custom middleware functions */
  middleware?: Function[];
  
  /** Server root directory */
  root?: string;
  
  /** Enable directory browsing */
  browse?: boolean;
  
  /** Custom error pages */
  errorPages?: {
    404?: string;
    500?: string;
  };
}

// Basic server usage
const elev = new Eleventy("./src", "./_site", { runMode: "serve" });
await elev.init();
await elev.serve(8080);

// Configure server options
eleventyConfig.setServerOptions({
  port: 3000,
  showAllHosts: true,
  liveReload: true,
  middleware: [
    (req, res, next) => {
      // Custom middleware
      res.setHeader("X-Custom-Header", "Eleventy");
      next();
    }
  ]
});

// Faster development with passthrough
eleventyConfig.setServerPassthroughCopyBehavior("passthrough");

/**
 * Start file watching for automatic rebuilds
 * @returns Watch function for testing
 */
watch(): Promise<Function>;

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

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

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

/**
 * Add additional files or patterns to watch
 * @param additionalWatchTargets - Files/patterns to watch
 * @param options - Watch target options
 */
addWatchTarget(additionalWatchTargets: string, options?: WatchTargetOptions): void;

interface WatchTargetOptions {
  /** Reset configuration when target changes */
  resetConfig?: boolean;
}

// Basic watch usage
const elev = new Eleventy("./src", "./_site", { runMode: "watch" });
await elev.init();
await elev.watch();

// Watch additional files
eleventyConfig.addWatchTarget("./src/assets/**/*.scss");
eleventyConfig.addWatchTarget("./src/data/**/*.yml");

// Watch with config reset
eleventyConfig.addWatchTarget("./custom-config/*.js", {
  resetConfig: true
});

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

/**
 * Enable/disable JavaScript dependency watching
 * @param watchEnabled - Whether to watch JS dependencies
 */
setWatchJavaScriptDependencies(watchEnabled: boolean): void;

interface JavaScriptWatchOptions {
  /** Watch JavaScript dependencies automatically */
  watchJavaScriptDependencies?: boolean;
  
  /** Additional files to watch */
  additionalWatchTargets?: string[];
  
  /** Files to ignore during watching */
  watchIgnores?: string[];
}

// Enable JS dependency watching (default: true)
eleventyConfig.setWatchJavaScriptDependencies(true);

// Disable for faster startup (not recommended)
eleventyConfig.setWatchJavaScriptDependencies(false);

// Watch dependencies are automatically tracked for:
// - .eleventy.js config files
// - .11ty.js template files  
// - _data/*.js global data files
// - Template directory data files

/**
 * Configure Chokidar file watcher options
 * @param options - Chokidar configuration options
 */
setChokidarConfig(options?: ChokidarOptions): void;

/**
 * Set watch throttle wait time to batch file changes
 * @param time - Wait time in milliseconds
 */
setWatchThrottleWaitTime(time?: number): void;

/**
 * Set files to ignore during watching
 * @param enabled - Whether to use .gitignore
 */
setUseGitIgnore(enabled: boolean): void;

interface ChokidarOptions {
  /** Ignore initial add events */
  ignoreInitial?: boolean;
  
  /** Ignored paths/patterns */ 
  ignored?: string | string[] | Function;
  
  /** Follow symbolic links */
  followSymlinks?: boolean;
  
  /** Working directory for relative paths */
  cwd?: string;
  
  /** Disable globbing */
  disableGlobbing?: boolean;
  
  /** Use fs.watchFile as fallback */
  usePolling?: boolean;
  
  /** Polling interval (if usePolling: true) */
  interval?: number;
  
  /** Binary file polling interval */
  binaryInterval?: number;
  
  /** Additional options for fs.watch */
  awaitWriteFinish?: {
    stabilityThreshold?: number;
    pollInterval?: number;
  };
}

// Configure file watcher
eleventyConfig.setChokidarConfig({
  usePolling: false,
  ignoreInitial: true,
  awaitWriteFinish: {
    stabilityThreshold: 150,
    pollInterval: 25
  }
});

// Throttle rebuilds (wait 500ms after last change)
eleventyConfig.setWatchThrottleWaitTime(500);

// Use .gitignore for watch ignores
eleventyConfig.setUseGitIgnore(true);

/**
 * Set incremental build mode for faster rebuilds
 * @param isIncremental - Enable incremental builds
 */
setIncrementalBuild(isIncremental: boolean): void;

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

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

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

// Enable incremental builds for faster development
elev.setIncrementalBuild(true);

// Skip initial build, only build on changes
elev.setIgnoreInitial(true);

// Process specific file incrementally
elev.setIncrementalFile("./src/posts/new-post.md");

// Dry run mode for testing
elev.setDryRun(true);

interface LiveReloadOptions {
  /** Files that triggered the reload */
  files: string[];
  
  /** Reload subtype for CSS hot-swapping */
  subtype?: 'css';
  
  /** Build results for smart reloading */
  build?: {
    /** Updated stylesheets for CSS injection */
    stylesheets: string[];
    
    /** Updated templates for partial reloads */
    templates: any[];
  };
}

interface ReloadCapabilities {
  /** CSS hot-swapping without full page reload */
  cssHotReload: boolean;
  
  /** Template partial updates */
  templateUpdates: boolean;
  
  /** Asset injection */
  assetInjection: boolean;
}

/**
 * Complete development setup
 */
interface DevelopmentWorkflow {
  /** Initialize Eleventy */
  init(): Promise<void>;
  
  /** Start file watching */
  watch(): Promise<Function>;
  
  /** Start development server */
  serve(port?: number): Promise<void>;
  
  /** Stop all development processes */
  stopWatch(): Promise<void>;
}

// Complete development setup
const elev = new Eleventy("./src", "./_site", {
  runMode: "serve",
  quietMode: false
});

// Configure development tools
eleventyConfig.setServerOptions({
  port: 8080,
  showAllHosts: true
});

eleventyConfig.setWatchThrottleWaitTime(100);
eleventyConfig.setIncrementalBuild(true);
eleventyConfig.addWatchTarget("./src/assets/**/*.scss");

// Start development
await elev.init();
const watchFn = await elev.watch();
await elev.serve();

// Graceful shutdown
process.on("SIGINT", async () => {
  await elev.stopWatch();
  process.exit(0);
});

// CLI equivalent: npx @11ty/eleventy --serve --watch --port=8080

interface DevelopmentErrors {
  /** Error overlay in browser */
  errorOverlay: boolean;
  
  /** Detailed error messages */
  verboseErrors: boolean;
  
  /** Source maps for debugging */
  sourceMaps: boolean;
}

/**
 * Set verbose mode for detailed error messages
 * @param isVerbose - Enable verbose output
 */
setIsVerbose(isVerbose: boolean): void;

/**
 * Disable logger output
 */
disableLogger(): void;

// Enable verbose error messages
elev.setIsVerbose(true);

// Development error handling
eleventyConfig.on("eleventy.config", () => {
  if (process.env.NODE_ENV === "development") {
    elev.setIsVerbose(true);
  }
});

// Custom error handling
try {
  await elev.write();
} catch (error) {
  if (error.name === "EleventyConfigError") {
    console.error("Configuration error:", error.message);
  } else {
    console.error("Build error:", error);
  }
}

interface ServerOptions {
  port?: number;
  showAllHosts?: boolean;
  showVersion?: boolean;
  encoding?: string;
  liveReload?: boolean;
  reloadDelay?: number;
  middleware?: Function[];
  root?: string;
  browse?: boolean;
  errorPages?: {
    404?: string;
    500?: string;
  };
}

interface WatchTargetOptions {
  resetConfig?: boolean;
}

interface ChokidarOptions {
  ignoreInitial?: boolean;
  ignored?: string | string[] | Function;
  followSymlinks?: boolean;
  cwd?: string;
  disableGlobbing?: boolean;
  usePolling?: boolean;
  interval?: number;
  binaryInterval?: number;
  awaitWriteFinish?: {
    stabilityThreshold?: number;
    pollInterval?: number;
  };
}

interface JavaScriptWatchOptions {
  watchJavaScriptDependencies?: boolean;
  additionalWatchTargets?: string[];
  watchIgnores?: string[];
}

interface LiveReloadOptions {
  files: string[];
  subtype?: 'css';
  build?: {
    stylesheets: string[];
    templates: any[];
  };
}

interface DevelopmentWorkflow {
  init(): Promise<void>;
  watch(): Promise<Function>;
  serve(port?: number): Promise<void>;
  stopWatch(): Promise<void>;
}