Build Configuration

/**
 * Main Stencil configuration interface
 */
interface Config extends StencilConfig {
  buildAppCore?: boolean;
  buildDocs?: boolean;
  configPath?: string;
  writeLog?: boolean;
  devServer?: DevServerConfig;
  flags?: ConfigFlags;
  fsNamespace?: string;
  logLevel?: LogLevel;
  rootDir?: string;
  packageJsonFilePath?: string;
  suppressLogs?: boolean;
  profile?: boolean;
  tsCompilerOptions?: any;
  tsWatchOptions?: any;
  _isValidated?: boolean;
  _isTesting?: boolean;
}

interface StencilConfig {
  /** By default, Stencil will statically analyze the application and generate component bundles */
  bundles?: ConfigBundle[];
  /** Stencil will cache build results to speed up rebuilds */
  enableCache?: boolean;
  /** The directory where sub-directories will be created for caching */
  cacheDir?: string;
  /** Global CSS file for styles across all components */
  globalStyle?: string;
  /** Generate export map entry points for each component */
  generateExportMaps?: boolean;
  /** Hash file names for production builds */
  hashFileNames?: boolean;
  /** Length of hashed file names */
  hashedFileNameLength?: number;
  /** Namespace for the app */
  namespace?: string;
  /** Output targets configuration */
  outputTargets?: OutputTarget[];
  /** Rollup plugins configuration */
  plugins?: any[];
  /** Generate source maps */
  sourceMap?: boolean;
  /** Source directory containing TypeScript files */
  srcDir?: string;
  /** Transform aliased import paths from tsconfig.json */
  transformAliasedImportPaths?: boolean;
  /** Validate primary package output target */
  validatePrimaryPackageOutputTarget?: boolean;
  /** Rollup commonjs configuration */
  commonjs?: BundlingConfig;
  /** Node resolve configuration */
  nodeResolve?: NodeResolveConfig;
  /** Rollup configuration overrides */
  rollupConfig?: RollupConfig;
  /** Build ES5 version */
  buildEs5?: boolean | 'prod';
  /** Minify JavaScript output */
  minifyJs?: boolean;
  /** Minify CSS output */
  minifyCss?: boolean;
  /** Force development mode */
  devMode?: boolean;
  /** Custom logger instance */
  logger?: Logger;
  /** Runtime extras configuration */
  extras?: ConfigExtras;
  /** Hydrated flag configuration */
  hydratedFlag?: HydratedFlag | null;
  /** Task queue strategy */
  taskQueue?: 'async' | 'immediate' | 'congestionAsync';
  /** Environment variables */
  env?: { [prop: string]: string | undefined };
  /** Documentation configuration */
  docs?: StencilDocsConfig;
  /** Global script file */
  globalScript?: string;
  /** Source index.html file */
  srcIndexHtml?: string;
  /** Testing configuration */
  testing?: TestingConfig;
  /** Max concurrent workers */
  maxConcurrentWorkers?: number;
  /** Build preamble text */
  preamble?: string;
  /** Additional rollup plugins */
  rollupPlugins?: { before?: any[]; after?: any[] };
  /** Entry component hints for optimization */
  entryComponentsHint?: string[];
  /** Whether to write dist files */
  buildDist?: boolean;
  /** Build log file path */
  buildLogFilePath?: string;
  /** Enable dev inspector */
  devInspector?: boolean;
  /** Dev server configuration */
  devServer?: StencilDevServerConfig;
  /** Compiler system */
  sys?: CompilerSystem;
  /** TypeScript config file path */
  tsconfig?: string;
  /** Validate TypeScript types */
  validateTypes?: boolean;
  /** Watch for file changes */
  watch?: boolean;
  /** External directories to watch */
  watchExternalDirs?: string[];
  /** Regex patterns to ignore in watch mode */
  watchIgnoredRegex?: RegExp | RegExp[];
  /** Exclude unused dependencies from build */
  excludeUnusedDependencies?: boolean;
}

/**
 * Union type of all available output target types
 */
type OutputTarget =
  | OutputTargetDist
  | OutputTargetDistCustomElements
  | OutputTargetDistCollection
  | OutputTargetWww
  | OutputTargetCustom
  | OutputTargetDocsJson
  | OutputTargetDocsReadme
  | OutputTargetDocsVscode
  | OutputTargetHydrate
  | OutputTargetStats
  | OutputTargetCopy;

/**
 * Distribution output target for npm publishing
 */
interface OutputTargetDist {
  type: 'dist';
  /** Build directory for compiled files */
  buildDir?: string;
  /** Collection directory for component metadata */
  collectionDir?: string | null;
  /** Transform aliased imports in collection bundle */
  transformAliasedImportPathsInCollection?: boolean | null;
  /** Types directory for TypeScript definitions */
  typesDir?: string;
  /** ESM loader directory path */
  esmLoaderPath?: string;
  /** Files to copy to build directory */
  copy?: CopyTask[];
  /** Include polyfills in build */
  polyfills?: boolean;
  /** Empty build directory before build */
  empty?: boolean;
}

/**
 * Custom elements output target for framework integration
 */
interface OutputTargetDistCustomElements {
  type: 'dist-custom-elements';
  /** Empty build directory before build */
  empty?: boolean;
  /** Treat @stencil/core modules as external */
  externalRuntime?: boolean;
  /** Files to copy to build directory */
  copy?: CopyTask[];
  /** Include global scripts in components */
  includeGlobalScripts?: boolean;
  /** Minify output files */
  minify?: boolean;
  /** Generate TypeScript declaration files */
  generateTypeDeclarations?: boolean;
  /** Export/definition behavior for custom elements */
  customElementsExportBehavior?: CustomElementsExportBehavior;
}

type CustomElementsExportBehavior = 
  | 'default'
  | 'auto-define-custom-elements'
  | 'bundle'
  | 'single-export-module';

/**
 * Web app output target for static sites
 */
interface OutputTargetWww {
  type: 'www';
  /** Build directory for JS/CSS files */
  buildDir?: string;
  /** Directory for entire application */
  dir?: string;
  /** Empty directory before build */
  empty?: boolean;
  /** Index HTML file path */
  indexHtml?: string;
  /** Files to copy to build directory */
  copy?: CopyTask[];
  /** Base URL of the app */
  baseUrl?: string;
  /** Include polyfills in build */
  polyfills?: boolean;
  /** Prerender configuration file */
  prerenderConfig?: string;
  /** Service worker configuration */
  serviceWorker?: ServiceWorkerConfig | null | false;
}

/**
 * Custom output target for build integrations
 */
interface OutputTargetCustom {
  type: 'custom';
  /** Name of the custom output target */
  name: string;
  /** When the output target should run */
  taskShouldRun?: 'onBuildOnly' | 'always';
  /** Validation function for configuration */
  validate?: (config: Config, diagnostics: Diagnostic[]) => void;
  /** Generator function for build output */
  generator: (config: Config, compilerCtx: CompilerCtx, buildCtx: BuildCtx, docs: JsonDocs) => Promise<void>;
  /** Files to copy to build directory */
  copy?: CopyTask[];
}

import { Config } from '@stencil/core';

export const config: Config = {
  namespace: 'MyApp',
  outputTargets: [
    {
      type: 'dist',
      esmLoaderPath: '../loader',
    },
    {
      type: 'dist-custom-elements',
      customElementsExportBehavior: 'auto-define-custom-elements',
      generateTypeDeclarations: true,
    },
    {
      type: 'www',
      serviceWorker: null,
      copy: [
        { src: 'assets', dest: 'build/assets' }
      ]
    }
  ],
  globalStyle: 'src/global/app.css',
  buildEs5: 'prod'
};

/**
 * File and directory copy operation configuration
 */
interface CopyTask {
  /** Source file path (absolute, relative, or glob pattern) */
  src: string;
  /** Optional destination path */
  dest?: string;
  /** Glob patterns to exclude from copy */
  ignore?: string[];
  /** Issue warnings if source files not found */
  warn?: boolean;
  /** Preserve directory structure when copying */
  keepDirStructure?: boolean;
}

const copyTasks: CopyTask[] = [
  // Copy entire assets directory
  { src: 'assets' },
  // Copy with custom destination
  { src: 'src/docs', dest: 'documentation' },
  // Copy with exclusions
  { 
    src: 'static/**/*',
    ignore: ['**/*.tmp', '**/node_modules/**']
  },
  // Copy single file with preserved structure
  {
    src: 'config/app.json',
    dest: 'build/config',
    keepDirStructure: true
  }
];

/**
 * Configuration for additional runtime features
 */
interface ConfigExtras {
  /** Enable import injection for better bundler compatibility */
  enableImportInjection?: boolean;
  /** Dispatch component lifecycle events for testing */
  lifecycleDOMEvents?: boolean;
  /** Support script data-opts property */
  scriptDataOpts?: boolean;
  /** Initialize components on next tick (Angular compatibility) */
  initializeNextTick?: boolean;
  /** Enable tagName transform option */
  tagNameTransform?: boolean;
  /** Experimental scoped slot changes */
  experimentalScopedSlotChanges?: boolean;
  /** Add global styles to each component */
  addGlobalStyleToComponents?: boolean;
  /** Fix appendChild to work with slot polyfill */
  appendChildSlotFix?: boolean;
  /** Fix cloneNode to work with slot polyfill */
  cloneNodeFix?: boolean;
  /** Fix textContent behavior in scoped components */
  scopedSlotTextContentFix?: boolean;
  /** Fix childNodes and children getters for slot polyfill */
  slotChildNodesFix?: boolean;
  /** Enable all slot-related fixes */
  experimentalSlotFixes?: boolean;
}

/**
 * Configuration for hydrated component flag
 */
interface HydratedFlag {
  /** CSS class or attribute name */
  name?: string;
  /** Use 'class' or 'attribute' selector */
  selector?: 'class' | 'attribute';
  /** CSS property to control visibility */
  property?: string;
  /** Initial CSS value before hydration */
  initialValue?: string;
  /** CSS value after hydration completes */
  hydratedValue?: string;
}

const config: Config = {
  // Use opacity instead of visibility
  hydratedFlag: {
    name: 'hydrated',
    selector: 'class',
    property: 'opacity',
    initialValue: '0',
    hydratedValue: '1'
  }
};

/**
 * Documentation generation configuration
 */
interface StencilDocsConfig {
  /** Markdown processing options */
  markdown?: {
    /** Target component styling for diagrams */
    targetComponent?: {
      /** Background color for component nodes */
      background?: string;
      /** Text color for component nodes */
      textColor?: string;
    };
  };
}

/**
 * README documentation output target
 */
interface OutputTargetDocsReadme {
  type: 'docs-readme';
  /** Root directory for README files */
  dir?: string;
  /** Include component dependencies */
  dependencies?: boolean;
  /** How to handle existing README files */
  overwriteExisting?: boolean | 'if-missing';
  /** Footer text for generated READMEs */
  footer?: string;
  /** Strict mode for documentation validation */
  strict?: boolean;
}

/**
 * JSON documentation output target
 */
interface OutputTargetDocsJson {
  type: 'docs-json';
  /** Output file path for JSON documentation */
  file: string;
  /** TypeScript definitions file for docs types */
  typesFile?: string | null;
  /** Strict mode for documentation validation */
  strict?: boolean;
  /** Additional public types file to include */
  supplementalPublicTypes?: string;
}

/**
 * VS Code custom data output target
 */
interface OutputTargetDocsVscode {
  type: 'docs-vscode';
  /** Output file path for VS Code data */
  file: string;
  /** Base URL for component source code */
  sourceCodeBaseUrl?: string;
}

/**
 * Rollup configuration overrides
 */
interface RollupConfig {
  /** Input options for Rollup */
  inputOptions?: RollupInputOptions;
  /** Output options for Rollup */
  outputOptions?: RollupOutputOptions;
}

interface RollupInputOptions {
  /** Context for module evaluation */
  context?: string;
  /** Module context configuration */
  moduleContext?: ((id: string) => string) | { [id: string]: string };
  /** Tree shaking configuration */
  treeshake?: boolean;
  /** Max parallel file operations */
  maxParallelFileOps?: number;
  /** External dependencies configuration */
  external?: 
    | (string | RegExp)[]
    | string
    | RegExp
    | ((source: string, importer: string | undefined, isResolved: boolean) => boolean | null | undefined);
}

interface RollupOutputOptions {
  /** Global variable names for external dependencies */
  globals?: { [name: string]: string } | ((name: string) => string);
}

/**
 * Node resolve plugin configuration
 */
interface NodeResolveConfig {
  /** Export conditions to match */
  exportConditions?: string[];
  /** Use browser field in package.json */
  browser?: boolean;
  /** Directories to search for modules */
  moduleDirectories?: string[];
  /** Additional module paths */
  modulePaths?: string[];
  /** Dedupe module instances */
  dedupe?: string[] | ((importee: string) => boolean);
  /** File extensions to resolve */
  extensions?: readonly string[];
  /** Jail resolution to specific directory */
  jail?: string;
  /** Package.json fields to check */
  mainFields?: readonly string[];
  /** Only resolve modules (no files) */
  modulesOnly?: boolean;
  /** Prefer built-in Node.js modules */
  preferBuiltins?: boolean | ((module: string) => boolean);
  /** Only resolve specific modules */
  resolveOnly?: ReadonlyArray<string | RegExp> | null | ((module: string) => boolean);
  /** Root directory for resolution */
  rootDir?: string;
  /** Allow exports folder mapping */
  allowExportsFolderMapping?: boolean;
}

const config: Config = {
  rollupConfig: {
    inputOptions: {
      external: ['lodash', 'moment'],
      treeshake: {
        moduleSideEffects: false
      }
    },
    outputOptions: {
      globals: {
        'lodash': '_',
        'moment': 'moment'
      }
    }
  },
  nodeResolve: {
    browser: true,
    preferBuiltins: false,
    mainFields: ['browser', 'module', 'main']
  }
};