server-fancy-ui

A futuristic, animated UI middleware for Express. Drop it on any route and get a stunning cyberpunk-style dashboard — no frontend setup required.

Browsers get a full animated HTML page. API clients (curl, fetch, Postman) get clean JSON automatically.

Installation

npm install server-fancy-ui
# or
yarn add server-fancy-ui
# or
pnpm add server-fancy-ui

Quick Start

import express from "express";
import serverFancyUI from "server-fancy-ui";

const app = express();

app.get("/", serverFancyUI({ ui: "root" }));

app.listen(3000);

Open http://localhost:3000 in a browser — you get the animated dashboard.
Hit it with curl http://localhost:3000 — you get JSON.

Built-in UIs

root — Landing dashboard

Animated globe, server panel, live stats canvas. Good for a home/landing route.

app.get("/", serverFancyUI({ ui: "root" }));

With custom text:

app.get("/", serverFancyUI({
  ui: "root",
  brandName: "MY APP",
  brandSub: "Production · Node-01 · Region US-East",
  orbLabel: "MY APP<br />CORE",
  pageTitle: "My App — Dashboard",
}));

| Option | Type | Default | |---|---|---| | brandName | string | "NEXUS CORE" | | brandSub | string | "Global Network Infrastructure · Node-01 · Sector Ω" | | orbLabel | string | "GLOBAL<br />NETWORK<br />CORE" | | pageTitle | string | "NEXUS CORE — Global Network Infrastructure" |

health — Health check screen

Diagnostic card showing status, uptime, memory, CPU, and Node.js version.

app.get("/health", serverFancyUI({ ui: "health" }));

With real runtime data:

import os from "os";

app.get("/health", (req, res, next) => {
  serverFancyUI({
    ui: "health",
    status: "SYSTEM OPERATIONAL",
    uptime: `${Math.floor(process.uptime())}s`,
    memory: `${Math.round(process.memoryUsage().heapUsed / 1024 / 1024)} MB`,
    cpu: `${os.loadavg()[0].toFixed(2)}`,
  })(req, res, next);
});

| Option | Type | Default | |---|---|---| | status | string | "SYSTEM OPERATIONAL" | | uptime | string | "N/A" | | memory | string | "N/A" | | cpu | string | "N/A" | | brandName | string | "NEXUS CORE" | | brandSub | string | "System Health Diagnostic" | | pageTitle | string | "NEXUS CORE — System Health" |

not-found — 404 page

Glitch-effect 404 screen. Automatically injects the requested path — no need to pass it manually.

// Catch-all at the bottom of your routes
app.use(serverFancyUI({ ui: "not-found" }));

With a custom message:

app.use(serverFancyUI({
  ui: "not-found",
  message: "That route doesn't exist. Check the docs.",
}));

With a custom JSON response for API clients:

When a non-browser client hits a 404, you can control exactly what JSON they receive using jsonData. The requested path is always appended automatically.

app.use(serverFancyUI({
  ui: "not-found",
  message: "Route not found.",           // shown in the browser HTML
  jsonData: {                            // returned to curl / fetch / Postman
    success: false,
    statusCode: 404,
    error: "NOT_FOUND",
    hint: "Visit /docs for valid routes.",
  },
}));

A curl request to /api/unknown would receive:

{
  "success": false,
  "statusCode": 404,
  "error": "NOT_FOUND",
  "hint": "Visit /docs for valid routes.",
  "path": "/api/unknown"
}

| Option | Type | Default | |---|---|---| | message | string | "The requested coordinates do not exist in the network." | | path | string | auto — req.originalUrl | | pageTitle | string | "NEXUS CORE — 404 Not Found" | | footerText | string | "NEXUS CORE // SECURITY PROTOCOL" | | jsonData | Record<string, unknown> | undefined |

Browser vs API client detection

server-fancy-ui checks two request headers to decide what to send:

• Accept must include text/html
• User-Agent must match a known browser (Mozilla, Chrome, Safari, Firefox, Edge, Opera)

Both must be true to serve HTML. Everything else — curl, fetch, axios, Postman — gets JSON.

Browser → HTML page

API client → JSON

For root and health, the JSON is the options object you passed in:

curl http://localhost:3000/health
# { "ui": "health", "status": "SYSTEM OPERATIONAL", "uptime": "3600s" }

For not-found, the JSON is either your jsonData (with path appended) or the options object (with path appended).

Full example

import express from "express";
import os from "os";
import serverFancyUI from "server-fancy-ui";

const app = express();

// Landing page
app.get("/", serverFancyUI({
  ui: "root",
  brandName: "MY SERVICE",
  brandSub: "Production · v2.0.0",
}));

// Health check
app.get("/health", (req, res, next) => {
  serverFancyUI({
    ui: "health",
    status: "SYSTEM OPERATIONAL",
    uptime: `${Math.floor(process.uptime())}s`,
    memory: `${Math.round(process.memoryUsage().heapUsed / 1024 / 1024)} MB`,
    cpu: `${os.loadavg()[0].toFixed(2)}`,
  })(req, res, next);
});

// 404 — must be last
app.use(serverFancyUI({
  ui: "not-found",
  message: "That route doesn't exist.",
  jsonData: {
    success: false,
    statusCode: 404,
    error: "NOT_FOUND",
  },
}));

app.listen(3000, () => {
  console.log("Running on http://localhost:3000");
});

TypeScript

All options are fully typed. Import the specific type for each UI to get precise IntelliSense:

import serverFancyUI from "server-fancy-ui";
import type { HealthUIOptions, NotFoundUIOptions, RootUIOptions } from "server-fancy-ui";

The main serverFancyUI() function accepts the UIOptions union type, so autocomplete works directly on the options object based on the ui value you set.

License

MIT