Build Configuration

/**
 * Main configuration interface for initializing Parcel builds
 */
interface InitialParcelOptions {
  /** Entry points for the build */
  entries?: FilePath | Array<FilePath>;
  /** Path to custom Parcel configuration file */
  config?: DependencySpecifier;
  /** Default configuration package to extend */
  defaultConfig?: DependencySpecifier;
  /** Build targets configuration */
  targets?: Array<string> | {[string]: TargetDescriptor};
  /** Build mode - affects optimization and development features */
  mode?: BuildMode;
  /** Environment variables to inject */
  env?: EnvMap;
  /** Whether to disable build caching */
  shouldDisableCache?: boolean;
  /** Custom cache directory location */
  cacheDir?: FilePath;
  /** Watch directory for file changes */
  watchDir?: FilePath;
  /** File watcher backend type */
  watchBackend?: BackendType;
  /** Files and patterns to ignore when watching */
  watchIgnore?: Array<FilePath | GlobPattern>;
  /** Whether to include content hash in bundle names */
  shouldContentHash?: boolean;
  /** Development server configuration */
  serveOptions?: InitialServerOptions | false;
  /** Whether to auto-install missing dependencies */
  shouldAutoInstall?: boolean;
  /** Logging level configuration */
  logLevel?: LogLevel;
  /** Whether to profile build performance */
  shouldProfile?: boolean;
  /** Whether to trace build operations */
  shouldTrace?: boolean;
  /** Whether to patch console output */
  shouldPatchConsole?: boolean;
  /** Whether to build lazily (only changed files) */
  shouldBuildLazily?: boolean;
  /** Patterns to include in lazy builds */
  lazyIncludes?: Array<string>;
  /** Patterns to exclude from lazy builds */
  lazyExcludes?: Array<string>;
  /** Whether to enable incremental bundling */
  shouldBundleIncrementally?: boolean;
  /** File invalidation events for unstable features */
  unstableFileInvalidations?: Array<Event>;
  /** Custom input file system */
  inputFS?: FileSystem;
  /** Custom output file system */
  outputFS?: FileSystem;
  /** Custom cache implementation */
  cache?: Cache;
  /** Worker farm for parallel processing */
  workerFarm?: WorkerFarm;
  /** Custom package manager */
  packageManager?: PackageManager;
  /** Detailed reporting options */
  detailedReport?: DetailedReportOptions;
  /** Default target options for all targets */
  defaultTargetOptions?: {
    shouldOptimize?: boolean;
    shouldScopeHoist?: boolean;
    sourceMaps?: boolean;
    publicUrl?: string;
    distDir?: FilePath;
    engines?: Engines;
    outputFormat?: OutputFormat;
    isLibrary?: boolean;
  };
  /** Additional reporter plugins */
  additionalReporters?: Array<{
    packageName: DependencySpecifier;
    resolveFrom: FilePath;
  }>;
  /** Hot module replacement options for development */
  hmrOptions?: HMROptions;
  /** Feature flags configuration */
  featureFlags?: Partial<FeatureFlags>;
}

/**
 * Build mode configuration
 * - 'development': Faster builds with debugging features
 * - 'production': Optimized builds for deployment
 * - Custom string: User-defined mode
 */
type BuildMode = 'development' | 'production' | string;

/**
 * Build target configuration for JS API usage
 */
interface TargetDescriptor {
  /** Target runtime context */
  context?: EnvironmentContext;
  /** Engine version requirements */
  engines?: Engines;
  /** Node modules inclusion strategy */
  includeNodeModules?: boolean | Array<PackageName> | {[PackageName]: boolean};
  /** Output module format */
  outputFormat?: OutputFormat;
  /** Public URL for assets */
  publicUrl?: string;
  /** Output directory (required) */
  distDir: FilePath;
  /** Output entry file name */
  distEntry?: FilePath;
  /** Source map configuration */
  sourceMap?: boolean | TargetSourceMapOptions;
  /** Whether this is a library build */
  isLibrary?: boolean;
  /** Whether to optimize the output */
  optimize?: boolean;
  /** Whether to enable scope hoisting */
  scopeHoist?: boolean;
  /** Input source files */
  source?: FilePath | Array<FilePath>;
}

/**
 * Package.json target configuration format
 */
interface PackageTargetDescriptor {
  context?: EnvironmentContext;
  engines?: Engines;
  includeNodeModules?: boolean | Array<PackageName> | {[PackageName]: boolean};
  outputFormat?: OutputFormat;
  publicUrl?: string;
  distDir?: FilePath;
  sourceMap?: boolean | TargetSourceMapOptions;
  isLibrary?: boolean;
  optimize?: boolean;
  scopeHoist?: boolean;
  source?: FilePath | Array<FilePath>;
}

/**
 * Engine version requirements
 */
interface Engines {
  /** Browser version requirements (browserslist format) */
  browsers?: string | Array<string>;
  /** Electron version requirement */
  electron?: SemverRange;
  /** Node.js version requirement */
  node?: SemverRange;
  /** Parcel version requirement */
  parcel?: SemverRange;
}

/**
 * Resolved browser version map
 * Example: { chrome: '91', firefox: '89', safari: '14' }
 */
interface VersionMap {
  [browserName: string]: string;
}

/**
 * Source map configuration options
 */
interface TargetSourceMapOptions {
  /** Source root path for source map */
  sourceRoot?: string;
  /** Whether to inline source map in output */
  inline?: boolean;
  /** Whether to include source content in source map */
  inlineSources?: boolean;
}

/**
 * Development server initialization options
 */
interface InitialServerOptions {
  /** Server port number */
  port?: number;
  /** Server host address */
  host?: string;
  /** HTTPS configuration */
  https?: HTTPSOptions | boolean;
}

/**
 * Runtime server options
 */
interface ServerOptions {
  port: number;
  host: string;
  https?: HTTPSOptions;
}

/**
 * HTTPS configuration for development server
 */
interface HTTPSOptions {
  /** Path to SSL certificate file */
  cert?: FilePath;
  /** Path to SSL private key file */
  key?: FilePath;
}

/**
 * Hot module replacement configuration
 */
interface HMROptions {
  /** HMR server port */
  port?: number;
  /** HMR server host */
  host?: string;
}

/**
 * Logging level configuration
 */
type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'verbose';

/**
 * Detailed reporting options
 */
interface DetailedReportOptions {
  /** Number of assets to show per bundle in detailed reports */
  assetsPerBundle?: number;
}

/**
 * File watcher backend types
 */
type BackendType = 'fs-events' | 'watchman' | 'brute-force';

/**
 * Glob pattern for file matching
 */
type GlobPattern = string;

/**
 * File system event from @parcel/watcher
 */
interface Event {
  /** Event type */
  type: 'create' | 'update' | 'delete';
  /** File path affected */
  path: string;
}

import type { InitialParcelOptions } from '@parcel/types';

// Basic production build configuration
const prodConfig: InitialParcelOptions = {
  entries: ['src/index.html'],
  mode: 'production',
  targets: {
    main: {
      distDir: 'dist',
      optimize: true,
      sourceMap: false
    }
  }
};

// Development configuration with HMR
const devConfig: InitialParcelOptions = {
  entries: ['src/index.html'],
  mode: 'development',
  hmrOptions: {
    port: 3000
  },
  serveOptions: {
    port: 1234,
    host: 'localhost'
  },
  targets: {
    main: {
      distDir: 'dev-dist',
      sourceMap: true
    }
  }
};

// Library build configuration
const libConfig: InitialParcelOptions = {
  entries: ['src/lib.ts'],
  targets: {
    main: {
      distDir: 'lib',
      isLibrary: true,
      outputFormat: 'esmodule',
      engines: {
        node: '>= 14'
      }
    }
  }
};