Development Server

Development server with hot module replacement, middleware support, and error overlay for optimal development experience.

Capabilities

Development Server Function

Start development server with hot reloading and comprehensive development features.

/**
 * Start development server with hot reloading
 * @param opts - Development server configuration
 */
function dev(opts: {
  webpackConfig: object | object[];
  _beforeServerWithApp?: (app: object) => void;
  beforeMiddlewares?: Function[];
  afterMiddlewares?: Function[];
  beforeServer?: (server: object) => void;
  afterServer?: (server: object, port: number) => void;
  contentBase?: string;
  onCompileDone?: (result: DevCompileResult) => void;
  onFail?: (error: { stats: object }) => void;
  proxy?: object;
  port: number;
  history?: object;
  base?: string;
  serverConfig?: object;
}): void;

interface DevCompileResult {
  port: number;
  isFirstCompile: boolean;
  stats: object;
  server: object;
  urls: {
    local: string;      // Local terminal URL
    lan: string;        // LAN terminal URL  
    rawLocal: string;   // Raw local browser URL
    rawLanUrl: string;  // Raw LAN URL
  };
}

Parameters:

• webpackConfig (object | object[]): Webpack configuration object or array
• _beforeServerWithApp (function, optional): Internal callback for proxy middleware setup
• beforeMiddlewares (Function[], optional): Express middlewares to run before built-in middlewares
• afterMiddlewares (Function[], optional): Express middlewares to run after built-in middlewares
• beforeServer (function, optional): Callback executed before server starts listening
• afterServer (function, optional): Callback executed after server starts listening
• contentBase (string, optional): Directory for static content serving
• onCompileDone (function, optional): Callback executed after successful compilation
• onFail (function, optional): Callback executed on compilation failure
• proxy (object, optional): Proxy configuration for API requests
• port (number, required): Port number for the development server
• history (object, optional): History API configuration
• base (string, optional): Base path for the application
• serverConfig (object, optional): Additional webpack-dev-server configuration

Usage Examples:

const dev = require('af-webpack/dev');

// Basic development server
dev({
  webpackConfig: {
    entry: './src/index.js',
    output: {
      path: './dist',
      publicPath: '/'
    }
  },
  port: 8000
});

// Advanced development server with middleware
dev({
  webpackConfig,
  port: 3000,
  beforeMiddlewares: [
    // Custom authentication middleware
    (req, res, next) => {
      console.log('Request:', req.url);
      next();
    }
  ],
  afterMiddlewares: [
    // Custom API routes
    express.static('public')
  ],
  proxy: {
    '/api': {
      target: 'http://localhost:5000',
      changeOrigin: true
    }
  },
  onCompileDone: ({ port, isFirstCompile, stats, server, urls }) => {
    if (isFirstCompile) {
      console.log(`Server running at ${urls.local}`);
    }
    console.log('Compilation completed in', stats.endTime - stats.startTime, 'ms');
  },
  onFail: ({ stats }) => {
    console.error('Compilation failed');
    stats.compilation.errors.forEach(err => console.error(err));
  }
});

Development Server Features

The development server provides:

• Hot Module Replacement: Automatic code reloading without page refresh
• Error Overlay: Visual error display in the browser for development errors
• Proxy Support: API request proxying to backend services
• HTTPS Support: Configurable HTTPS with custom certificates
• History API Fallback: Single-page application routing support
• Static Content Serving: Configurable static file serving
• Middleware Support: Custom Express middleware integration
• Automatic Browser Opening: Opens browser automatically on first compilation
• Network Access: Configurable network interface binding
• Clipboard Integration: Copies local URL to clipboard on startup

Server Configuration

Default server configuration includes:

interface ServerConfig {
  disableHostCheck: boolean;    // Disable host header check
  compress: boolean;            // Enable gzip compression
  clientLogLevel: string;       // Client-side logging level
  hot: boolean;                 // Enable hot module replacement
  quiet: boolean;               // Suppress webpack output
  headers: object;              // Custom response headers
  publicPath: string;           // Webpack public path
  watchOptions: object;         // File watching configuration
  historyApiFallback: boolean;  // History API fallback
  overlay: boolean;             // Error overlay display
  host: string;                 // Server host
  proxy: object;                // Proxy configuration
  https: boolean;               // HTTPS enable
  cert?: Buffer;                // HTTPS certificate
  key?: Buffer;                 // HTTPS private key
  contentBase?: string;         // Static content directory
}

Environment Variables

• HOST: Server host (default: 0.0.0.0)
• HTTPS: Enable HTTPS server
• CERT: Path to HTTPS certificate file
• KEY: Path to HTTPS private key file
• SYSTEM_BELL: Set to none to disable error sound notifications
• SILENT: Suppress startup messages
• CI: Continuous integration mode flag
• CONTENT_BASE: Static content directory

Error Handling

Development server errors are handled through:

• Compilation Errors: Displayed in browser error overlay and terminal
• Server Errors: Logged to console with detailed stack traces
• Signal Handling: Graceful shutdown on SIGINT/SIGTERM signals

URL Generation

The server generates multiple URL formats for different use cases:

• Local Terminal URL: For terminal display with proper formatting
• LAN Terminal URL: For network access display
• Browser URLs: For programmatic browser opening
• Raw URLs: For API integration and clipboard copying