Refactor/break server in modules

[ditadi]

Server Plugin Refactor

Overview

This refactor separates the ServerPlugin into focused, single-responsibility classes for better maintainability and clearer architecture.

Architecture

ServerPlugin (orchestrator)
├── ViteDevServer      - Development mode with HMR
├── StaticServer       - Production static file serving
└── RemoteTunnelManager - Databricks Apps remote tunneling

Classes

ServerPlugin (index.ts)

The main orchestrator that:

• Initializes Express application
• Registers plugin routes via extendRoutes()
• Delegates frontend serving based on NODE_ENV
• Handles graceful shutdown

Key behavior:

• NODE_ENV=development → Uses ViteDevServer
• NODE_ENV=production (or unset) → Uses StaticServer

ViteDevServer (vite-dev-server.ts)

Handles development mode with Vite middleware:

• Creates Vite server in middlewareMode
• Auto-detects client root directory (searches: client/, src/, app/, frontend/, .)
• Loads and merges user's vite.config.ts if present
• Provides HMR (Hot Module Replacement) for React
• SPA fallback for client-side routing

Requirements:

• Must find vite.config.ts + index.html in one of the candidate directories
• Throws clear error if no valid client directory found

StaticServer (static-server.ts)

Handles production static file serving:

• Serves pre-built files from detected/configured static path
• SPA fallback (serves index.html for non-API routes)
• Injects runtime config (window.__CONFIG__) into HTML

Static path detection order:

1. config.staticPath (user-provided)
2. Auto-detect from: dist/, client/dist/, build/, public/, out/

RemoteTunnelManager (remote-tunnel-manager.ts)

Handles Databricks Apps remote development:

• WebSocket tunnels for dev mode in deployed apps
• Viewer approval system for shared tunnels
• HMR forwarding through tunnels
• Only active when isRemoteServerEnabled() returns true

Usage

Development Mode

NODE_ENV=development tsx watch server/index.ts

Features:

• Vite HMR for instant frontend updates
• tsx watch for server hot reload
• No build step required

Production Mode

# Build first
vite build

# Run server
node server/index.ts

Features:

• Serves pre-built static files
• Optimized for performance

Package.json Scripts

{
  "scripts": {
    "dev": "NODE_ENV=development tsx watch server/index.ts",
    "build": "vite build",
    "start": "node server/index.ts"
  }
}

Example

import { createApp, server } from "@databricks/app-kit";

// Minimal - uses all defaults
await createApp({
  plugins: [server()],
});

// Custom configuration
await createApp({
  plugins: [
    server({
      port: 3000,
      staticPath: "./build",
      autoStart: false,
    }),
  ],
});