Configuration Management

/**
 * Load and validate Snowpack configuration from file system
 * @param overrides - Optional configuration overrides to merge
 * @param configPath - Optional path to specific config file
 * @returns Promise resolving to validated complete configuration
 */
function loadConfiguration(overrides?: SnowpackUserConfig, configPath?: string): Promise<SnowpackConfig>;

import { loadConfiguration } from "snowpack";

// Load configuration from default locations
const config = await loadConfiguration();

// Load with overrides
const config = await loadConfiguration({
  devOptions: { port: 3000 },
  buildOptions: { out: 'build' }
});

// Load from specific file
const config = await loadConfiguration({}, './custom.config.js');

/**
 * Create a Snowpack configuration object with defaults
 * @param config - Optional partial configuration to merge with defaults
 * @returns Complete configuration object with all defaults applied
 */
function createConfiguration(config?: SnowpackUserConfig): SnowpackConfig;

import { createConfiguration } from "snowpack";

// Create minimal configuration with defaults
const config = createConfiguration();

// Create configuration with custom options
const config = createConfiguration({
  root: './src',
  mount: {
    'src': '/',
    'public': { url: '/', static: true }
  },
  devOptions: {
    port: 8080,
    hostname: '0.0.0.0'
  }
});

/**
 * Expand CLI flags into configuration overrides
 * @param flags - CLI flags object
 * @returns Configuration overrides from flags
 */
function expandCliFlags(flags: CLIFlags): SnowpackUserConfig;

/**
 * CLI flags interface
 */
interface CLIFlags {
  /** Display help text */
  help?: boolean;
  /** Display version */
  version?: boolean;  
  /** Clear cache */
  reload?: boolean;
  /** Project root path */
  root?: string;
  /** Config file path */
  config?: string;
  /** Environment variables */
  env?: string[];
  /** URLs to open */
  open?: string[];
  /** Enable HTTPS */
  secure?: boolean;
  /** Verbose logging */
  verbose?: boolean;
  /** Quiet logging */
  quiet?: boolean;
  [flag: string]: any;
}

// Example CLI flag processing
const flags = {
  root: './my-app',
  port: 3000,
  open: ['chrome'],
  verbose: true
};

const cliConfig = expandCliFlags(flags);
const config = await loadConfiguration(cliConfig);

/**
 * Complete Snowpack configuration object
 */
interface SnowpackConfig {
  /** Project root directory */
  root: string;
  /** Build mode */
  mode: 'test' | 'development' | 'production';
  /** Workspace root directory */
  workspaceRoot?: string | false;
  /** Configuration to extend */
  extends?: string;
  /** Glob patterns to exclude */
  exclude: string[];
  /** Environment variables */
  env?: Record<string, string | boolean | undefined>;
  /** Directory mount points */
  mount: Record<string, MountEntry>;
  /** Import path aliases */
  alias: Record<string, string>;
  /** Loaded plugin instances */
  plugins: SnowpackPlugin[];
  /** Package dependencies */
  dependencies: Record<string, string>;
  /** Development server options */
  devOptions: DevOptions;
  /** Build system options */
  buildOptions: BuildOptions;
  /** Test runner options */
  testOptions: TestOptions;
  /** Package source options */
  packageOptions: PackageOptionsLocal | PackageOptionsRemote;
  /** Production optimization options */
  optimize?: OptimizeOptions;
  /** Route configuration */
  routes: RouteConfigObject[];
  /** Experimental features */
  experiments: {};
  /** Internal file extension mappings */
  _extensionMap: Record<string, string[]>;
}

/**
 * User-provided configuration (all fields optional)
 */
interface SnowpackUserConfig {
  /** Project root directory */
  root?: string;
  /** Build mode */
  mode?: SnowpackConfig['mode'];
  /** Workspace root directory */
  workspaceRoot?: string;
  /** Packages to install */
  install?: string[];
  /** Environment variables */
  env?: Record<string, string>;
  /** Configuration to extend */
  extends?: string;
  /** Glob patterns to exclude */
  exclude?: string[];
  /** Directory mount points */
  mount?: Record<string, string | Partial<MountEntry>>;
  /** Import path aliases */
  alias?: Record<string, string>;
  /** Plugin configurations */
  plugins?: (string | [string, any])[];
  /** Package dependencies */
  dependencies?: Record<string, string>;
  /** Development server options */
  devOptions?: Partial<SnowpackConfig['devOptions']>;
  /** Build system options */
  buildOptions?: Partial<SnowpackConfig['buildOptions']>;
  /** Test runner options */
  testOptions?: Partial<SnowpackConfig['testOptions']>;
  /** Package source options */
  packageOptions?: Partial<SnowpackConfig['packageOptions']>;
  /** Production optimization options */
  optimize?: Partial<SnowpackConfig['optimize']>;
  /** Route configuration */
  routes?: Pick<RouteConfigObject, 'src' | 'dest' | 'match'>[];
  /** Experimental features */
  experiments?: {};
}

/**
 * Development server configuration
 */
interface DevOptions {
  /** HTTPS configuration */
  secure: boolean | {
    cert: string | Buffer;
    key: string | Buffer;
  };
  /** Server hostname */
  hostname: string;
  /** Server port number */
  port: number;
  /** URL to open in browser */
  openUrl?: string;
  /** Browser to open */
  open?: string;
  /** Output display mode */
  output?: 'stream' | 'dashboard';
  /** Enable hot module replacement */
  hmr?: boolean;
  /** HMR connection delay */
  hmrDelay: number;
  /** HMR WebSocket port */
  hmrPort: number | undefined;
  /** Show HMR error overlay */
  hmrErrorOverlay: boolean;
  /** Tailwind config file path */
  tailwindConfig?: string;
}

// Example development options
const config = createConfiguration({
  devOptions: {
    hostname: 'localhost',
    port: 3000,
    secure: false,
    hmr: true,
    hmrDelay: 0,
    hmrErrorOverlay: true,
    open: 'chrome',
    output: 'dashboard'
  }
});

/**
 * Build system configuration
 */
interface BuildOptions {
  /** Output directory */
  out: string;
  /** Base URL for assets */
  baseUrl: string;
  /** Meta URL path */
  metaUrlPath: string;
  /** Cache directory path */
  cacheDirPath: string;
  /** Clean output before build */
  clean: boolean;
  /** Source map generation */
  sourcemap: 'inline' | false | undefined;
  /** Enable watch mode */
  watch: boolean;
  /** Generate HTML fragments */
  htmlFragments: boolean;
  /** JSX factory function */
  jsxFactory: string | undefined;
  /** JSX fragment function */
  jsxFragment: string | undefined;
  /** JSX import injection */
  jsxInject: string | undefined;
  /** Enable SSR */
  ssr: boolean;
  /** Resolve proxy imports */
  resolveProxyImports: boolean;
}

// Example build options
const config = createConfiguration({
  buildOptions: {
    out: 'dist',
    baseUrl: '/',
    clean: true,
    sourcemap: false,
    watch: false,
    ssr: false,
    jsxFactory: 'React.createElement',
    jsxFragment: 'React.Fragment'
  }
});

/**
 * Directory mount point configuration
 */
interface MountEntry {
  /** URL path to mount directory */
  url: string;
  /** Serve files statically */
  static: boolean;
  /** Enable import resolution */
  resolve: boolean;
  /** Include dotfiles */
  dot: boolean;
}

// Example mount configuration
const config = createConfiguration({
  mount: {
    // Process src/ files and mount to root
    'src': { url: '/', static: false, resolve: true, dot: false },
    // Serve public/ files statically
    'public': { url: '/', static: true, resolve: false, dot: false },
    // Mount assets to /assets/
    'assets': { url: '/assets', static: true, resolve: false, dot: false }
  }
});

/**
 * Local package source configuration
 */
interface PackageOptionsLocal {
  /** Package source type */
  source: 'local' | 'remote-next' | {[key: string]: string};
  /** External packages to exclude */
  external: string[];
  /** Known package entry points */
  knownEntrypoints: string[];
}

/**
 * Remote package source configuration  
 */
interface PackageOptionsRemote {
  /** Package source type */
  source: 'remote';
  /** External packages to exclude */
  external: string[];
  /** Known package entry points */
  knownEntrypoints: string[];
  /** Remote package origin */
  origin: string;
  /** Cache configuration */
  cache: string;
  /** Include type definitions */
  types: boolean;
}

// Local package configuration
const config = createConfiguration({
  packageOptions: {
    source: 'local',
    external: ['fsevents'],
    knownEntrypoints: ['react', 'react-dom']
  }
});

// Remote package configuration
const config = createConfiguration({
  packageOptions: {
    source: 'remote',
    origin: 'https://pkg.snowpack.dev',
    cache: '.snowpack',
    types: true,
    external: [],
    knownEntrypoints: []
  }
});

/**
 * Route configuration for development server
 */
interface RouteConfigObject {
  /** Source pattern */
  src: string;
  /** Destination or handler function */
  dest: string | ((req: http.IncomingMessage, res: http.ServerResponse) => void) | undefined;
  /** WebSocket upgrade handler */
  upgrade: ((req: http.IncomingMessage, socket: net.Socket, head: Buffer) => void) | undefined;
  /** Route matching mode */
  match: 'routes' | 'all';
  /** Internal regex for matching */
  _srcRegex: RegExp;
}

// Example route configuration
const config = createConfiguration({
  routes: [
    // Proxy API requests
    { src: '/api/.*', dest: 'http://localhost:4000$1', match: 'routes' },
    // SPA fallback
    { src: '/.*', dest: '/index.html', match: 'routes' }
  ]
});

// Environment variable configuration
const config = createConfiguration({
  env: {
    NODE_ENV: 'development',
    PUBLIC_URL: '/',
    CUSTOM_VAR: 'value'
  }
});

// Variables prefixed with SNOWPACK_PUBLIC_ are available client-side
process.env.SNOWPACK_PUBLIC_API_URL = 'https://api.example.com';

// snowpack.config.js
export default {
  mount: {
    src: '/',
    public: { url: '/', static: true }
  },
  plugins: [
    '@snowpack/plugin-typescript',
    '@snowpack/plugin-react-refresh'
  ],
  devOptions: {
    port: 3000,
    hmr: true
  },
  buildOptions: {
    out: 'build'
  }
};

// package.json
{
  "snowpack": {
    "mount": {
      "src": "/",
      "public": {"url": "/", "static": true}
    },
    "devOptions": {
      "port": 3000
    }
  }
}

try {
  const config = await loadConfiguration();
} catch (error) {
  if (error.name === 'CONFIG_VALIDATION_ERROR') {
    console.error('Configuration validation failed:');
    console.error(error.message);
  }
}