dx-server-js

v2.2.4

Published

15 days ago

A high-performance, lightweight development/production server and build tool designed for modern frontend applications. It provides essential developer experience (DX) features out of the box, including hot-reloading, Single Page Application (SPA) routing

0High
0Medium
0Low

elias_a_soshina

DX Developer Experience HTTP-Server Server Build-tool SPA Hot-reload SSL

DX Server

DX Server is a high-performance, lightweight development/production server and build tool designed for modern frontend applications. It provides essential developer experience (DX) features out of the box, including hot-reloading, Single Page Application (SPA) routing, automatic SSL generation, and a unique Build Ingestion system to monitor your build processes directly from the browser.

Key Features

⚡ Hot-Reloading: Automatic browser refresh on file changes via Server-Sent Events (SSE).
🧭 SPA Support: Smart fallback routing. Serves index.html automatically for client-side non static asset routes.
🛠️ Build Ingestion: Pipe your bundler's stdout directly to DX Server. It analyzes the logs to show real-time build states (compiling, success, error) in the browser.
🔒 Zero-Config SSL: Automatic self-signed SSL certificate generation using mkcert.
🩹 Frontend Patches: Optional injection to wrap console.error (for better object inspection) and enforce global fetch timeouts (preventing browser freezes during reloads or infinite loops).
🌍 Language Management: Built-in secure endpoint (/dx-lang) to update translation JSON files dynamically.
🔄 Watch Commands: Execute custom CLI commands (like linters, bundlers, compilers) automatically when files change.
🚪 Auto Port-Killing: Automatically frees up the requested port if it's already in use.

Requirements

Node.js: v20.19.0 or higher.

Installation

You can install DX Server via NPM:

npm install dx-server-js

# or
# as a dev dependency in your project:

npm install -D dx-server-js

Quick Start

Run the server from your project root (defaults to serving the www folder on port 80):

npx dx-server-js --dev

CLI Options & Configuration

🚀 Server Modes

⚙️ General Settings

🔒 SSL Configuration

👁️ Watcher & Commands

🏗️ Build Ingestion Options (Requires `--built`)

🩹 Frontend Patching

Advanced Usage Guide

1. Build Ingestion (Piping `stdout`)

DX Server can read the output of your bundler (Webpack, Vite, Esbuild, etc.) to understand the state of your build. If an error occurs during compilation, DX Server will catch it via regex/keywords and display an error overlay directly in your browser.

Example:

# Pipe your bundler's watch mode into DX Server
npm run build:watch | npx dx-server-js --built --built-error-keywords "SyntaxError, Failed to compile"

How it works: The server buffers the stdin up to the --ingest-limit. It scans for error keywords. If found, it updates the internal state to error and notifies the connected browsers via SSE.

2. Frontend Mode (`--frontend`)

When enabled, DX Server injects a lightweight script into your index.html that provides:

Fetch Interceptor: Automatically attaches an AbortController to all global fetch requests. If a request exceeds --frontend-fetch-timeout, it is aborted. This prevents the browser from freezing during browser reloads or development if you accidentally create an infinite fetch loop.
Console Error Wrapper: Enhances console.error to stringify complex objects. This is highly useful for debugging on mobile devices or environments with limited object inspection capabilities.
Polyfills: Injects safe fallbacks for Object.hasOwn, Promise.prototype.finally, and AbortController.

3. Language Management Endpoint

In --dev mode, DX Server exposes a POST /dx-lang endpoint. This allows your frontend application (e.g., an admin panel or translation UI) to save JSON translation files directly to the disk.

Security Mechanism: To prevent accidental data loss, the server compares the incoming JSON with the existing file. It will reject (400 Bad Request) the update if the new JSON contains fewer keys than the original file, ensuring you don't accidentally overwrite and delete translations.

Frontend Fetch Example:

fetch('http://localhost/dx-lang', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    dir: 'en',          // Target language sub-folder
    code: 'navbar',     // Filename (will become "en/navbar.json")
    keys: {             // The JSON content to save
      "welcome": "Welcome to my app!"
    }
  })
});

Additional Note: This endpoint features strict Path-Traversal protection. It also implements an asynchronous Mutex lock to prevent Race Conditions if multiple keys are saved simultaneously, guaranteeing zero data corruption.

Payload Limit: To prevent memory abuse, the JSON body payload is strictly limited to 1MB by default (equivalent to roughly 1,000 large key-value pairs).

4. SPA Routing Logic

DX Server is optimized for Single Page Applications with a highly performant in-memory cache system. When a request hits the server, a custom middleware evaluates it before serving static files:

It checks the request path and the Accept header.
If the request is looking for an asset (image/*, css, js, json), it bypasses the interceptor and continues to express.static. If the asset is missing, it serves the --fallback file (e.g., 404.html) with a 404 Not Found status.
If the request accepts html (a client-side route navigation), it intercepts the request.
It reads index.html, injects the hot-reload script, and caches the result in memory. It will serve this cached version instantly on subsequent requests, only re-reading the file if its modification time changes.

💡 Pro Tip: Smart HTTP Status Detection

DX Server includes an intelligent feature for custom fallbacks: it automatically detects the HTTP status code from your filename.

If you name your fallback file with a valid HTTP status code (e.g., 404.html, 403.html, or 500.html), the server will parse that number and use it as the HTTP response status. This allows you to serve semantic error pages automatically without any extra configuration.

404.html → Server responds with 404 Not Found.
403.html → Server responds with 403 Forbidden.
200.html → Server responds with 200 OK (useful for specific SPA configurations).

Internal Architecture & Files

When running, DX Server creates a dx-server folder in your project root to manage its internal state:

dx-server/self-signed-certificates/: Stores the cert.crt and cert.key generated by mkcert.
dx-server/_built.tmp: Tracks the current build state (compilation, built, error).
dx-server/_error.tmp: Stores the latest build error message to serve to the browser.
dx-server/_browserOpen.tmp: Prevents opening multiple browser tabs on rapid restarts.

Note: It is recommended to add dx-server/ to your .gitignore.

⚠️ Important Considerations

Network Binding (--network): By default, DX Server binds to :: (IPv6 Unspecified), which usually covers both IPv4 and IPv6 on modern OS. If you encounter network availability errors (EADDRNOTAVAIL), explicitly set it to IPv4 using --network 0.0.0.0.
Root Directory: DX Server automatically uses your terminal's current directory (process.cwd()) as the root. If you need to run it from a different folder, use the --root ./path/to/project argument to ensure the www, src, and lang folders are resolved correctly.
Ports 80 / 443: Binding to standard web ports on macOS and Linux usually requires sudo privileges. If you don't want to run as root, use a higher port (e.g., --port 8080).
Port Killing: By default, DX Server aggressively frees up the requested port. If you have a Docker container or a database unexpectedly running on port 80, DX Server will kill it. Use --no-kill if you want traditional safe behavior.
Security: CORS restrictions are disabled by default. The --dev mode exposes endpoints that allow disk writes (/dx-lang). Never use --dev in a publicly exposed network or a production environment. Always use --prod for deployments.

License

MIT License.