imagic-web-server

Lightweight HTTP/HTTPS server with named route params, middleware, static assets, and response helpers.

Install

npm install imagic-web-server

Quick Start

import WebServer from 'imagic-web-server'

const server = new WebServer()

server.use((req, res, next) => {
    console.log(`${req.method} ${req.pathname}`)
    next()
})

server.createRoute({ url: '/api/users/:id', methods: ['GET'] }, (req, res) => {
    res.json({ userId: req.params.id })
})

server.listen(3000, () => console.log('Listening on http://localhost:3000'))

API

new WebServer(options?)

Creates a web server instance. Does not bind a port until listen() is called.

new WebServer(options?: {
    https?: boolean
    key?: Buffer | string
    cert?: Buffer | string
    assets?: Array<AssetDir | AssetFile>
    nextRequestHandler?: (req, res) => void
    onError?: (err: Error, req, res) => void
})

| Option | Type | Default | Description | |---|---|---|---| | https | boolean | false | Create an HTTPS server. Requires key and cert | | key | Buffer \| string | — | TLS private key (PEM). Required when https: true | | cert | Buffer \| string | — | TLS certificate (PEM). Required when https: true | | assets | Array<AssetDir \| AssetFile> | [] | Static file serving entries (see below) | | nextRequestHandler | (req, res) => void | — | Fallback handler for requests that match no route; used for Next.js custom server integration | | onError | (err, req, res) => void | — | Called when a synchronous route handler throws, before the 500 response is sent |

AssetDir — serve an entire directory under a route prefix:

{ route: string, dir: string }
// e.g. { route: '/static', dir: './public' }

AssetFile — serve a single file at a fixed route:

{ route: string, file: string }
// e.g. { route: '/favicon.ico', file: './favicon.ico' }

createRoute(options, callback): void

Registers a route handler.

createRoute(
    options: {
        url: string
        methods?: string[]
    },
    callback: (req: EnhancedRequest, res: EnhancedResponse) => void
): void

| Option | Type | Default | Description | |---|---|---|---| | url | string | required | Route pattern (see route syntax below) | | methods | string[] | ['*'] | HTTP methods to match. '*' matches all methods |

Routes are matched in registration order. The first match wins.

use(middleware): void

Adds a middleware function executed before route handlers on every request.

use(middleware: (req: EnhancedRequest, res: EnhancedResponse, next: () => void) => void): void

Middlewares run in the order they were registered. Call next() to proceed. If next() is not called, the request is terminated.

listen(...args): net.Server

Starts listening. Delegates directly to the underlying node:http (or node:https) server.listen().

listen(port: number, callback?: () => void): net.Server
listen(port: number, hostname: string, callback?: () => void): net.Server
listen(options: object, callback?: () => void): net.Server

Request enhancements

The following properties are set on every req object before middleware and route handlers run:

| Property | Type | Description | |---|---|---| | req.pathname | string | URL path without query string (e.g. /users/42) | | req.query | object | Parsed query string parameters | | req.params | object | Route parameters extracted from the URL pattern |

Response enhancements

| Method | Signature | Description | |---|---|---| | res.json(data) | (data: object) => void | Sets Content-Type: application/json, serializes with JSON.stringify, calls res.end() | | res.status(code) | (code: number) => res | Sets res.statusCode; returns res for chaining | | res.redirect(code, location) | (code: number, location: string) => void | Sends a redirect response with writeHead + end |

Route Syntax

Patterns are matched against req.pathname (path only, no query string).

| Pattern | Example URL | req.params | |---|---|---| | /users/:id | /users/42 | { id: '42' } | | /users/:id/posts/:postId | /users/1/posts/99 | { id: '1', postId: '99' } | | /files/:path* | /files/images/logo.png | { path: 'images/logo.png' } | | /items/:id([0-9]+) | /items/123 | { id: '123' } | | /items/:id([0-9]+) | /items/abc | no match | | * | any URL | catch-all (use for 404) |

• :param — matches a single path segment (no slashes)
• :param* — matches one or more segments including slashes
• :param(regex) — matches a segment against a custom regular expression
• * — matches any path unconditionally

Error Handling

The library does not expose dedicated error types. Synchronous exceptions thrown inside route handlers are caught internally — the server responds with HTTP 500 and body '500'. The server continues handling subsequent requests normally.

Note: async route handlers are not awaited. Errors thrown inside an async handler after the first await are unhandled promise rejections and are not caught by the library.

To receive caught errors, pass an onError callback:

const server = new WebServer({
    onError: (err, req, res) => {
        console.error(`Route error: ${err.message}`)
    },
})

For custom error responses inside a handler, use a try/catch block:

server.createRoute({ url: '/api/data', methods: ['GET'] }, async (req, res) => {
    try {
        const data = await fetchData()
        res.json(data)
    } catch (error) {
        res.status(500).json({ error: error.message })
    }
})

For a global 404, register a catch-all route last:

server.createRoute({ url: '*', methods: ['*'] }, (req, res) => {
    res.status(404).json({ error: 'Not Found' })
})

Examples

See examples/ for runnable scripts, including:

• Basic HTTP server with routing and middleware
• HTTPS setup with self-signed certificates
• Static asset serving
• Next.js custom server integration

// examples/server.js excerpt — HTTPS with assets
import fs from 'node:fs'
import WebServer from 'imagic-web-server'

const server = new WebServer({
    https: true,
    key: fs.readFileSync('./certs/key.pem'),
    cert: fs.readFileSync('./certs/cert.pem'),
    assets: [
        { route: '/static', dir: './public' },
        { route: '/favicon.ico', file: './public/favicon.ico' },
    ],
})

server.use((req, res, next) => {
    res.setHeader('X-Powered-By', 'imagic-web-server')
    next()
})

server.createRoute({ url: '/api/health', methods: ['GET'] }, (req, res) => {
    res.json({ status: 'ok' })
})

server.listen(443, () => console.log('HTTPS server running on port 443'))

License

MIT