Snowpack

import { 
  startServer, 
  build, 
  loadConfiguration, 
  createConfiguration,
  clearCache,
  logger 
} from "snowpack";

const { 
  startServer, 
  build, 
  loadConfiguration, 
  createConfiguration,
  clearCache,
  logger 
} = require("snowpack");

import { startServer, loadConfiguration } from "snowpack";

// Start development server
const config = await loadConfiguration();
const server = await startServer({ config });

console.log(`Dev server running on port ${server.port}`);

/**
 * Start the Snowpack development server
 * @param commandOptions - Configuration and lockfile options
 * @param options - Optional server configuration
 * @returns Promise resolving to development server instance
 */
function startServer(
  commandOptions: CommandOptions,
  options?: {
    isDev?: boolean;
    isWatch?: boolean;
    preparePackages?: boolean;
  }
): Promise<SnowpackDevServer>;

/**
 * Build the project for production
 * @param commandOptions - Configuration and lockfile options  
 * @returns Promise resolving to build result with file change monitoring
 */
function build(commandOptions: CommandOptions): Promise<SnowpackBuildResult>;

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

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

/**
 * Plugin interface for extending Snowpack functionality
 */
interface SnowpackPlugin {
  /** Plugin name */
  name: string;
  /** File resolution configuration */
  resolve?: {
    input: string[];
    output: string[];
  };
  /** Load files matching resolve.input */
  load?(options: PluginLoadOptions): Promise<PluginLoadResult | string | null | undefined | void>;
  /** Transform files matching resolve.input */
  transform?(options: PluginTransformOptions): Promise<PluginTransformResult | string | null | undefined | void>;
  /** Run commands unrelated to file building */
  run?(options: PluginRunOptions): Promise<unknown>;
  /** Optimize the entire built application */
  optimize?(options: PluginOptimizeOptions): Promise<void>;
  /** Cleanup long-running instances before exit */
  cleanup?(): void | Promise<void>;
  /** Known entrypoints that should be installed */
  knownEntrypoints?: string[];
  /** Modify Snowpack configuration */
  config?(snowpackConfig: SnowpackConfig): void;
  /** Handle file changes during development */
  onChange?({filePath}: {filePath: string}): void;
  /** (internal interface, not set by the user) Mark a file as changed */
  markChanged?(file: string): void;
}

/**
 * Main CLI entry point
 * @param args - Command line arguments
 * @returns Promise resolving when command completes
 */
function cli(args: string[]): Promise<void>;

/**
 * Get URL for a file location
 * @param fileLoc - File location path
 * @param config - Snowpack configuration
 * @returns File URL or null if not found
 */
function getUrlForFile(fileLoc: string, config: SnowpackConfig): string | null;

/**
 * Prepare packages for the build process
 * @param options - Command options with configuration
 * @returns Promise resolving when packages are prepared
 */
function preparePackages({config}: CommandOptions): Promise<void>;

/**
 * Clear the Snowpack cache directory
 * @returns Promise resolving when cache is cleared
 */
function clearCache(): Promise<void>;

/**
 * Read the snowpack.deps.json lockfile
 * @param cwd - Current working directory
 * @returns Promise resolving to lockfile manifest or null
 */
function loadLockfile(cwd: string): Promise<LockfileManifest | null>;

/**
 * Main Snowpack configuration object
 */
interface SnowpackConfig {
  /** Project root directory */
  root: string;
  /** Build mode */
  mode: 'test' | 'development' | 'production';
  /** Workspace root directory */  
  workspaceRoot?: string | false;
  /** Configuration extension */
  extends?: string;
  /** Files to exclude from processing */
  exclude: string[];
  /** Environment variables */
  env?: Record<string, string | boolean | undefined>;
  /** Directory mount points */
  mount: Record<string, MountEntry>;
  /** Import aliases */
  alias: Record<string, string>;
  /** Loaded plugins */
  plugins: SnowpackPlugin[];
  /** Dependency mappings */
  dependencies: Record<string, string>;
  /** Development server options */
  devOptions: {
    secure: boolean | {cert: string | Buffer; key: string | Buffer};
    hostname: string;
    port: number;
    openUrl?: string;
    open?: string;
    output?: 'stream' | 'dashboard';
    hmr?: boolean;
    hmrDelay: number;
    hmrPort: number | undefined;
    hmrErrorOverlay: boolean;
    tailwindConfig?: string;
  };
  /** Build options */
  buildOptions: {
    out: string;
    baseUrl: string;
    metaUrlPath: string;
    cacheDirPath: string;
    clean: boolean;
    sourcemap: 'inline' | false | undefined;
    watch: boolean;
    htmlFragments: boolean;
    jsxFactory: string | undefined;
    jsxFragment: string | undefined;
    jsxInject: string | undefined;
    ssr: boolean;
    resolveProxyImports: boolean;
  }; 
  /** Test options */
  testOptions: {
    files: string[];
  };
  /** Package source options */
  packageOptions: PackageOptionsLocal | PackageOptionsRemote;
  /** Production optimization options */
  optimize?: OptimizeOptions;
  /** Route configuration */
  routes: RouteConfigObject[];
  /** Experimental features */
  experiments: {};
  /** File extension mappings */
  _extensionMap: Record<string, string[]>;
}

/**
 * User-provided configuration (partial of SnowpackConfig)
 */
interface SnowpackUserConfig {
  root?: string;
  mode?: SnowpackConfig['mode'];
  workspaceRoot?: string;
  install?: string[];
  env?: Record<string, string>;
  extends?: string;
  exclude?: string[];
  mount?: Record<string, string | Partial<MountEntry>>;
  alias?: Record<string, string>;
  plugins?: (string | [string, any])[];
  dependencies?: Record<string, string>;
  devOptions?: Partial<{
    secure: boolean | {cert: string | Buffer; key: string | Buffer};
    hostname: string;
    port: number;
    openUrl?: string;
    open?: string;
    output?: 'stream' | 'dashboard';
    hmr?: boolean;
    hmrDelay: number;
    hmrPort: number | undefined;
    hmrErrorOverlay: boolean;
    tailwindConfig?: string;
  }>;
  buildOptions?: Partial<{
    out: string;
    baseUrl: string;
    metaUrlPath: string;
    cacheDirPath: string;
    clean: boolean;
    sourcemap: 'inline' | false | undefined;
    watch: boolean;
    htmlFragments: boolean;
    jsxFactory: string | undefined;
    jsxFragment: string | undefined;
    jsxInject: string | undefined;
    ssr: boolean;
    resolveProxyImports: boolean;
  }>;
  testOptions?: Partial<{
    files: string[];
  }>;
  packageOptions?: Partial<SnowpackConfig['packageOptions']>;
  optimize?: Partial<SnowpackConfig['optimize']>;
  routes?: Pick<RouteConfigObject, 'src' | 'dest' | 'match'>[];
  experiments?: {};
}

/**
 * Command options passed to commands
 */
interface CommandOptions {
  /** Snowpack configuration */
  config: SnowpackConfig;
  /** Optional lockfile manifest */
  lockfile?: LockfileManifest | null;
}

/**
 * Development server instance
 */
interface SnowpackDevServer {
  /** Server port number */
  port: number;
  /** Hot module replacement engine */
  hmrEngine?: EsmHmrEngine;
  /** Raw HTTP server instance */
  rawServer?: http.Server | http2.Http2Server | undefined;
  /** Load URL with options */
  loadUrl: {
    (reqUrl: string, opt?: LoadUrlOptions | undefined): Promise<LoadResult<Buffer | string> | undefined>;
    (reqUrl: string, opt: LoadUrlOptions & {encoding: BufferEncoding}): Promise<LoadResult<string> | undefined>;
    (reqUrl: string, opt: LoadUrlOptions & {encoding: null}): Promise<LoadResult<Buffer> | undefined>;
  };
  /** Handle HTTP requests */
  handleRequest: (req: http.IncomingMessage, res: http.ServerResponse, options?: {handleError?: boolean}) => Promise<void>;
  /** Send response file */
  sendResponseFile: (req: http.IncomingMessage, res: http.ServerResponse, result: LoadResult) => void;
  /** Get server runtime for SSR */
  getServerRuntime: (options?: {invalidateOnChange?: boolean}) => ServerRuntime;
  /** Send error response */
  sendResponseError: (req: http.IncomingMessage, res: http.ServerResponse, status: number) => void;
  /** Get URL for file location */
  getUrlForFile: (fileLoc: string) => string | null;
  /** Get URL for package */
  getUrlForPackage: (packageSpec: string) => Promise<string>;
  /** Register file change callback */
  onFileChange: (callback: OnFileChangeCallback) => void;
  /** Mark file as changed */
  markChanged: (fileLoc: string) => void;
  /** Shutdown server */
  shutdown(): Promise<void>;
}

/**
 * Build result from production build
 */
interface SnowpackBuildResult {
  /** Register file change callback */
  onFileChange: (callback: OnFileChangeCallback) => void;
  /** Shutdown build process */
  shutdown(): Promise<void>;
}

/**
 * Plugin factory function type
 */
type SnowpackPluginFactory<PluginOptions = object> = (
  snowpackConfig: SnowpackConfig,
  pluginOptions?: PluginOptions,
) => SnowpackPlugin;

/**
 * Options for plugin load method
 */
interface PluginLoadOptions {
  /** Absolute file path */
  filePath: string;
  /** File extension */
  fileExt: string;
  /** Development mode flag */
  isDev: boolean;
  /** HMR enabled flag */
  isHmrEnabled: boolean;
  /** SSR mode flag */
  isSSR: boolean;
  /** Package file flag */
  isPackage: boolean;
}

/**
 * Options for plugin transform method
 */
interface PluginTransformOptions {
  /** Build file path */
  id: string;
  /** Source file path */
  srcPath: string;
  /** File extension */
  fileExt: string;
  /** File contents */
  contents: string | Buffer;
  /** Development mode flag */
  isDev: boolean;
  /** HMR enabled flag */
  isHmrEnabled: boolean;
  /** SSR mode flag */
  isSSR: boolean;
  /** Package file flag */
  isPackage: boolean;
}

/**
 * Plugin load result type
 */
type PluginLoadResult = SnowpackBuildMap;

/**
 * Plugin transform result type
 */
type PluginTransformResult = {
  contents: string;
  map: string | RawSourceMap;
};

/**
 * File load result
 */
interface LoadResult<T = Buffer | string> {
  /** File contents */
  contents: T;
  /** Import targets found in file */
  imports: InstallTarget[];
  /** Original file location */
  originalFileLoc: string | null;
  /** Content type */
  contentType: string | false;
  /** Function to check if file is stale */
  checkStale?: () => Promise<void>;
}

/**
 * File change callback type
 */
type OnFileChangeCallback = ({filePath: string}) => any;

/**
 * Import map structure
 */
interface ImportMap {
  imports: {[specifier: string]: string};
}

/**
 * Lockfile manifest structure
 */
interface LockfileManifest {
  dependencies: {[packageName: string]: string};
  lock: {[specifier: string]: string};
}

/**
 * CLI flags interface
 */
interface CLIFlags {
  help?: boolean;
  version?: boolean;
  reload?: boolean;
  root?: string;
  config?: string;
  env?: string[];
  open?: string[];
  secure?: boolean;
  verbose?: boolean;
  quiet?: boolean;
  [flag: string]: any;
}

/**
 * Snowpack logger instance
 */
interface SnowpackLogger {
  /** Log level */
  level: LoggerLevel;
  /** Debug log message */
  debug(message: string, options?: LoggerOptions): void;
  /** Info log message */
  info(message: string, options?: LoggerOptions): void;
  /** Warning log message */
  warn(message: string, options?: LoggerOptions): void;
  /** Error log message */
  error(message: string, options?: LoggerOptions): void;
}

/**
 * Logger instance for Snowpack operations
 */
const logger: SnowpackLogger;

/**
 * Logger level type
 */
type LoggerLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';

/**
 * Error thrown when a file is not found during development
 */
class NotFoundError extends Error {
  constructor(message: string);
}

/**
 * @deprecated Renamed to startServer(). Throws deprecation error.
 */
function startDevServer(): never;

/**
 * @deprecated Renamed to build(). Throws deprecation error.
 */
function buildProject(): never;

/**
 * @deprecated Replaced by loadConfiguration() and createConfiguration(). Throws deprecation error.
 */
function loadAndValidateConfig(): never;