Local Development

/**
 * Start local development server with Netlify features
 * Command: netlify dev [options]
 */
interface DevOptions {
  /** Command to run for the application server */
  command?: string;
  /** Deploy context for environment variables (default: dev) */
  context?: string;
  /** Port for Netlify dev server */
  port?: number;
  /** Skip waiting for target port to be available */
  skipWaitPort?: boolean;
  /** Disable automatic browser opening */
  noOpen?: boolean;
  /** Target application server port */
  targetPort?: number;
  /** Framework to use (#auto for auto-detection) */
  framework?: string;
  /** Static files directory */
  dir?: string;
  /** Functions folder */
  functions?: string;
  /** Disable network-dependent features */
  offline?: boolean;
  /** Disable fetching environment variables from Netlify */
  offlineEnv?: boolean;
  /** Disable edge functions */
  internalDisableEdgeFunctions?: boolean;
  /** Start public live session with optional subdomain */
  live?: string | boolean;
  /** Functions server port */
  functionsPort?: number;
  /** Geolocation mode: cache, mock, or update */
  geo?: 'cache' | 'mock' | 'update';
  /** Two-letter country code for mock geolocation */
  country?: string;
  /** Static server port */
  staticServerPort?: number;
  /** Enable V8 Inspector for Edge Functions with optional address */
  edgeInspect?: string | boolean;
  /** Enable V8 Inspector for Edge Functions with break on start */
  edgeInspectBrk?: string | boolean;
  /** Skip adding .netlify to .gitignore */
  skipGitignore?: boolean;
}

# Basic dev server
netlify dev

# Dev server with custom port
netlify dev --port 8080

# Dev server with specific framework detection
netlify dev --framework react

# Dev server with custom command
netlify dev --command "npm run start:custom"

# Dev server with functions in custom directory
netlify dev --functions ./my-functions

# Dev server with live tunneling
netlify dev --live

# Dev server with custom live subdomain
netlify dev --live my-project

# Dev server with geolocation mocking
netlify dev --geo mock --country US

# Dev server with edge function debugging
netlify dev --edge-inspect

# Offline development mode
netlify dev --offline

/**
 * Execute command in development context
 * Command: netlify dev-exec <command...>
 */
interface DevExecOptions {
  /** Deploy context for environment variables */
  context?: string;
}

# Run tests in dev context
netlify dev-exec npm test

# Run database migrations with dev environment
netlify dev-exec npm run migrate

# Execute custom script with Netlify environment
netlify dev-exec node scripts/seed-db.js

# Run with specific context
netlify dev-exec --context production npm run check

type SupportedFrameworks = 
  | 'gatsby'
  | 'create-react-app' 
  | 'vue-cli'
  | 'nuxt'
  | 'next'
  | 'angular'
  | 'ember'
  | 'hugo'
  | 'jekyll'
  | 'eleventy'
  | 'svelte'
  | 'vite'
  | 'remix'
  | 'astro'
  | '#auto'     // Auto-detection
  | '#static'   // Static files only
  | '#custom';  // Custom configuration

interface FrameworkConfig {
  command?: string;        // Development command
  port?: number;          // Default development port
  env?: Record<string, string>; // Framework-specific environment variables
  pollingStrategies?: string[]; // File watching strategies
  dist?: string;          // Build output directory
}

/**
 * Live session configuration for public access to local development
 */
interface LiveSession {
  /** Custom subdomain for the live session */
  subdomain?: string;
  /** Generated public URL */
  url: string;
  /** Session expiration time */
  expiresAt: Date;
  /** Whether HTTPS is enabled */
  https: boolean;
}

# Start live session with auto-generated subdomain
netlify dev --live

# Start live session with custom subdomain
netlify dev --live my-awesome-project

# Live session outputs:
# ◈ Server now ready on http://localhost:8888
# ◈ Live session: https://my-awesome-project.netlify.live

/**
 * Geolocation configuration for local development
 */
interface GeoConfig {
  /** Geolocation mode */
  mode: 'cache' | 'mock' | 'update';
  /** Country code for mock mode */
  country?: string;
  /** Cached geolocation data */
  cache?: {
    country: string;
    subdivision: string;
    city: string;
    timezone: string;
  };
}

# Mock geolocation for US
netlify dev --geo mock --country US

# Mock geolocation for UK
netlify dev --geo mock --country GB

# Cache geolocation data
netlify dev --geo cache

# Update geolocation cache
netlify dev --geo update

/**
 * Edge function debugging configuration
 */
interface EdgeInspectorConfig {
  /** Inspector address (default: 127.0.0.1:9229) */
  address?: string;
  /** Break on start */
  breakOnStart?: boolean;
  /** Inspector port */
  port?: number;
}

# Enable edge function debugging
netlify dev --edge-inspect

# Debug with custom address
netlify dev --edge-inspect 0.0.0.0:9230

# Debug with break on start
netlify dev --edge-inspect-brk

# Then connect Chrome DevTools to chrome://inspect

/**
 * Development configuration sources
 */
interface DevConfigSources {
  /** netlify.toml configuration */
  netlifyToml?: {
    dev?: {
      command?: string;
      port?: number;
      targetPort?: number;
      framework?: string;
      autoLaunch?: boolean;
    };
  };
  /** package.json scripts and netlify key */
  packageJson?: {
    scripts?: Record<string, string>;
    netlify?: {
      dev?: DevOptions;
    };
  };
  /** .netlify/state.json for site linking */
  siteState?: {
    siteId: string;
    adminUrl: string;
    url: string;
  };
}

/**
 * Environment variable sources in development
 */
interface DevEnvironment {
  /** Local .env files (in priority order) */
  localEnvFiles: [
    '.env.local',
    '.env.development',
    '.env'
  ];
  /** Netlify environment variables from the dashboard */
  netlifyEnv?: Record<string, string>;
  /** Context-specific variables */
  contextEnv?: Record<string, string>;
  /** Injected Netlify-specific variables */
  netlifyVars: {
    NETLIFY: 'true';
    NETLIFY_DEV: 'true';
    NETLIFY_LOCAL: 'true';
    URL: string;
    DEPLOY_URL: string;
    CONTEXT: string;
    BRANCH: string;
    HEAD: string;
    COMMIT_REF: string;
    REPOSITORY_URL: string;
  };
}