Development Server

/**
 * Development server instance with lifecycle management
 */
interface RsbuildDevServer {
  /** Start listening on configured port */
  listen(): Promise<void>;
  /** Close the development server */
  close(): Promise<void>;
  /** Connect server instance */
  server: Connect.Server;
  /** Server port number */
  port: number;
  /** Server host address */
  host: string;
}

/**
 * Result of starting development server
 */
interface StartServerResult {
  /** Server URLs (local and network) */
  urls: string[];
  /** Server port number */
  port: number;
  /** Development server instance */
  server: RsbuildDevServer;
}

interface ServerConfig {
  /** Server port number */
  port?: number;
  /** Server host address */
  host?: string;
  /** HTTPS configuration */
  https?: boolean | HTTPSOptions;
  /** Proxy configuration for API calls */
  proxy?: ProxyConfig;
  /** CORS settings */
  cors?: boolean | CorsOptions;
  /** Custom response headers */
  headers?: Record<string, string>;
  /** SPA routing support */
  historyApiFallback?: boolean | HistoryApiFallbackOptions;
  /** Response compression */
  compress?: boolean | CompressOptions;
  /** Auto-open browser */
  open?: boolean | string | OpenOptions;
  /** Base URL path */
  base?: string;
  /** Static file serving */
  publicDir?: PublicDir;
  /** Custom middleware setup */
  setupMiddlewares?: SetupMiddlewaresFn;
}

interface HTTPSOptions {
  /** SSL private key */
  key?: string;
  /** SSL certificate */
  cert?: string;
}

interface ProxyConfig {
  [path: string]: string | ProxyOptions;
}

interface ProxyOptions {
  /** Target server URL */
  target: string;
  /** Change origin header */
  changeOrigin?: boolean;
  /** Path rewriting rules */
  pathRewrite?: Record<string, string>;
  /** Request interceptor */
  onProxyReq?: (proxyReq: any, req: any, res: any) => void;
  /** Response interceptor */
  onProxyRes?: (proxyRes: any, req: any, res: any) => void;
  /** WebSocket proxying */
  ws?: boolean;
  /** Custom headers */
  headers?: Record<string, string>;
}

interface HistoryApiFallbackOptions {
  /** Rewrite rules */
  rewrites?: Array<{ from: RegExp; to: string }>;
  /** Files to serve directly */
  disableDotRule?: boolean;
  /** Verbose logging */
  verbose?: boolean;
}

interface OpenOptions {
  /** Target URL or app */
  target?: string;
  /** Browser app name */
  app?: {
    name: string;
    arguments?: string[];
  };
}

interface PublicDir {
  /** Public directory path */
  name?: string;
  /** Copy to output directory */
  copyOnBuild?: boolean;
}

type SetupMiddlewaresFn = (
  middlewares: RequestHandler[],
  server: SetupMiddlewaresContext
) => RequestHandler[] | void;

interface SetupMiddlewaresContext {
  /** Express app instance */
  app: any;
  /** Development server instance */
  server: RsbuildDevServer;
}

interface DevConfig {
  /** Hot Module Replacement configuration */
  hmr?: boolean | HMROptions;
  /** Live reload on file changes */
  liveReload?: boolean;
  /** Development asset prefix */
  assetPrefix?: string | 'auto';
  /** Client-side development configuration */
  client?: ClientConfig;
}

interface HMROptions {
  /** HMR server port */
  port?: number;
  /** HMR server host */
  host?: string;
  /** HMR WebSocket path */
  path?: string;
}

interface ClientConfig {
  /** WebSocket protocol */
  protocol?: 'ws' | 'wss';
  /** Client connection port */
  port?: number;
  /** Client connection host */
  host?: string;
  /** WebSocket connection path */
  path?: string;
  /** Error overlay configuration */
  overlay?: boolean | OverlayOptions;
}

interface OverlayOptions {
  /** Show compilation errors */
  errors?: boolean;
  /** Show compilation warnings */
  warnings?: boolean;
}

import { createRsbuild, defineConfig } from "@rsbuild/core";

// Basic server configuration
const config = defineConfig({
  server: {
    port: 3000,
    host: "localhost",
    open: true,
  },
  dev: {
    hmr: true,
    liveReload: true,
  },
});

// Advanced server configuration
const advancedConfig = defineConfig({
  server: {
    port: 8080,
    host: "0.0.0.0",
    https: {
      key: "./ssl/private-key.pem",
      cert: "./ssl/certificate.pem",
    },
    
    // Proxy API calls
    proxy: {
      "/api": {
        target: "http://localhost:3001",
        changeOrigin: true,
        pathRewrite: {
          "^/api": "/v1/api",
        },
      },
      "/ws": {
        target: "ws://localhost:3001",
        ws: true,
      },
    },
    
    // Custom headers
    headers: {
      "X-Custom-Header": "development",
    },
    
    // SPA routing
    historyApiFallback: {
      rewrites: [
        { from: /^\/admin/, to: "/admin.html" },
        { from: /./, to: "/index.html" },
      ],
    },
    
    // Custom middleware
    setupMiddlewares: (middlewares, { app }) => {
      // Add custom route
      app.get("/api/health", (req, res) => {
        res.json({ status: "ok" });
      });
      
      return middlewares;
    },
  },
  
  dev: {
    // Custom HMR configuration
    hmr: {
      port: 24678,
      host: "localhost",
    },
    
    // Client configuration
    client: {
      overlay: {
        errors: true,
        warnings: false,
      },
    },
  },
});

// Using the development server
const rsbuild = await createRsbuild({ rsbuildConfig: config });

// Start development server
const { urls, port, server } = await rsbuild.startDevServer();
console.log("Server running at:", urls);

// Or create server manually
const devServer = await rsbuild.createDevServer();
await devServer.listen();
console.log(`Server running on port ${devServer.port}`);

// Close server when needed
await devServer.close();

/**
 * Request handler type for Express-like middleware
 */
type RequestHandler = (req: any, res: any, next?: () => void) => void;

/**
 * Setup custom middleware function
 */
type SetupMiddlewaresFn = (
  middlewares: RequestHandler[],
  server: SetupMiddlewaresContext
) => RequestHandler[] | void;

const config = defineConfig({
  server: {
    setupMiddlewares: (middlewares, { app, server }) => {
      // Add middleware before existing ones
      middlewares.unshift((req, res, next) => {
        console.log(`${req.method} ${req.url}`);
        next();
      });
      
      // Add custom API endpoints
      app.get("/api/config", (req, res) => {
        res.json({
          version: "1.0.0",
          environment: "development",
        });
      });
      
      // Add middleware after existing ones
      middlewares.push((req, res, next) => {
        res.setHeader("X-Powered-By", "Rsbuild");
        next();
      });
      
      return middlewares;
    },
  },
});

// Available as separate exports
import "@rsbuild/core/client/hmr";     // HMR client
import "@rsbuild/core/client/overlay"; // Error overlay client

// Available in client code during development
declare const import.meta.env: {
  MODE: 'development' | 'production' | 'none';
  DEV: boolean;
  PROD: boolean;
  BASE_URL: string;
  ASSET_PREFIX: string;
};

/**
 * Hook called before development server starts
 */
type OnBeforeStartDevServerFn = (params: {
  port: number;
  host: string;
}) => void | Promise<void>;

/**
 * Hook called after development server starts
 */
type OnAfterStartDevServerFn = (params: {
  port: number;
  host: string;
  urls: string[];
}) => void | Promise<void>;

/**
 * Hook called when development server closes
 */
type OnCloseDevServerFn = () => void | Promise<void>;

const rsbuild = await createRsbuild({ rsbuildConfig: config });

// Before server starts
rsbuild.onBeforeStartDevServer(({ port, host }) => {
  console.log(`Starting server on ${host}:${port}`);
});

// After server starts
rsbuild.onAfterStartDevServer(({ urls }) => {
  console.log("Server started at:");
  urls.forEach(url => console.log(`  ${url}`));
});

// When server closes
rsbuild.onCloseDevServer(() => {
  console.log("Development server closed");
});

await rsbuild.startDevServer();