@caboodle-tech/node-simple-server

NSS: a Node based Simple Server

A small but effective node based server for development sites, customizable live reloading, and websocket support built-in. You should consider using NSS if:

:heavy_check_mark:  You want to add live reloading to the development process of a static site.

:heavy_check_mark:  You want easy two-way communication from the back-end and front-end of your development site or web based application with built-in WebSockets ready for use.

:heavy_check_mark:  You want more fine grained control over the whole live reloading process.

:heavy_check_mark:  You want to easily test your development site on multiple devices; must be on the same LAN.

:heavy_check_mark:  You want to easily setup a LAN application for educational purposes or other development; must be on the same LAN, please consider security implications.

:heavy_check_mark:  You want to easily setup a web based application that leverages the browser as your apps GUI but can interact with system data via websocket; great for internal applications.

Installation

Locally:

Like any other Node based application you can install NSS automatically with pnpm or npm and then reference it in your code. This is the recommended way to install and use NSS.

# Install using pnpm:
pnpm add @caboodle-tech/node-simple-server

# Or install using npm:
npm install @caboodle-tech/node-simple-server

Then use in your code with:

import NodeSimpleServer from '@caboodle-tech/node-simple-server';

Manually:

Node Simple Server (NSS) can be manually incorporated into your development process/ application. Extract the nss folder from the latest release and then import the server module into your code, similar to:

import NodeSimpleServer from './nss.js';

Globally:

You can install and use NSS globally with:

pnpm install -g @caboodle-tech/node-simple-server

Depending on how you use and incorporate NSS into your project will determine the best dependency strategy to use.

Usage

NSS is designed to be controlled and/or wrapped by another application. The bare minimum code needed to use NSS in your application is:

/**
 * If you want/need to import NSS from a manual install replace the below import statement with:
 * 
 * import NodeSimpleServer from './nss.js';
 * 
 * NOTE: Manual installs must include the handlers directory one directory higher than NSS.
 */
import NodeSimpleServer from '@caboodle-tech/node-simple-server'
import { fileURLToPath } from 'url';
import path from 'path'

// This is needed for ES modules.
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Determine what directory to watch for changes; defaults to project root.
const websiteRoot = __dirname;

// Build a bare minimum server options object.
const serverOptions = {
    root: websiteRoot
};

// Get a new instance of NSS.
const Server = new NodeSimpleServer(serverOptions);

/**
 * A bare minimum callback to handle most development changes. You register only for
 * the events you need; unhandled events (e.g. unlink/unlinkDir if not listed) are ignored.
 */
const watcherCallback = (event, path, statsOrDetails) => {
    const extension = statsOrDetails.ext;
    if (extension === 'css') {
        Server.reloadAllStyles();
        return;
    }
    if (extension === 'js') {
        /**
         * NOTE: This is a heavy request to use if your site loads resources from
         * other sites such as images, databases, or API calls. Consider a better
         * approach in these cases such as throttling.
         */
        Server.reloadAllPages();
        return;
    }
    if (event === 'change') {
        Server.reloadSinglePage(path);
    }
    // When a file or directory is removed, reload so the browser does not show stale content.
    if (event === 'unlink' || event === 'unlinkDir') {
        Server.reloadAllPages();
    }
};

/**
 * A bare minimum callback to handle all websocket messages from the frontend. By
 * default NSS registers and responds to WebSockets by the web pages pathname. In
 * a web page:
 * 
 * NSS_WS.send([string|int|bool|object]) // Pathname lookup will be used.
 */
const websocketCallback = (messageObject, pageId) => {
    const datatype = messageObject.type;
    const data = messageObject.data;
    console.log(`Received ${datatype} data from page ${pageId}: ${data}`);
    Server.message(pageId, 'Message received!');
};
Server.addWebsocketCallback('.*', websocketCallback);

/**
 * A bare minimum callback to handle all websocket messages from the frontend.
 * This is a special example that registers a specific route to listen for. In a
 * web page:
 * 
 * NSS_WS.send([string|int|bool|object], [route string]) // Route lookup will be used.
 */
const websocketCallbackRoute = (messageObject, pageId) => {
    const datatype = messageObject.type;
    const data = messageObject.data;
    console.log(`Route received ${datatype} data from page ${pageId}: ${data}`);
    Server.message(pageId, 'Route specific message received!');
};
Server.addWebsocketCallback('api/search', websocketCallbackRoute);

/**
 * Watcher options: the events you register are your intent. Only registered events
 * are handled; others (e.g. unlink, unlinkDir) are ignored unless you add them.
 */
const watcherOptions = {
    events: {
        all: watcherCallback,
    },
};

// Start the server.
Server.start();

// Watch the current directory for changes; use for development, omit for production.
Server.watch(websiteRoot, watcherOptions);

The options object required by the watch method must include an events property with at least one watched event. The demo code above used all to capture any event. You express intent by which events you register: only those are handled; others are ignored. If your app has a build step (e.g. source → output), register for unlink and unlinkDir in events to react when files or directories are removed (e.g. to keep your output in sync). This object takes a lot of settings and is explained below in the Watch Options table.

NSS uses process.cwd() as the live servers root if omitted and is pre-configured with several additional default settings. You can change these by providing your own options object when instantiating the server. How this looks in code is shown below, the following table Server Options explains all available options.

// Make your options object.
const options = {...};

// Get a new instance of NSS and pass in the options.
const Server = new NodeSimpleServer(options);

Note: If you set options.root to a different location than the current directory, you should usually provide the same path or a child path of this path, when you instantiate Server.watch.

:bookmark: Server Options (Object)

contentType    default: text/html

• The default Content-Type to report to the browser if one can not be determined for a page.

dirListing    default: false

• If a directory is requested should the directory listing page be shown.

disableAutoRestart    default: false

• If the server shuts off or crashes do not attempt to auto reconnect to it.

hostAddress    default: 127.0.0.1

• What IPv4 address or domain name to listen on.

NOTE: This is an advanced setting and should rarely need to be altered.

indexPage    default: index.html

• If a directory is requested consider this file to be the index page if it exits at that location.

liveReloading    default: true

• Reload the frontend when changes occur on the backend; disable if using NSS in a production setting.

NOTE: Even if you are not watching for any events this loads a full NSS developer websocket into all pages on the server address. Disabling this will load only a simplified NSS websocket.

port    default: 5000

• The port number the HTTP and WebSocket server should listen on for requests.

root    default: process.cwd()

• The absolute path to the directory that should be considered the servers root directory.

:bookmark: Watch Options (Object)

events

• Set to an object that can have any combination of these properties: all, add, addDir, change, unlink, unlinkDir, ready, raw, error. Any property set on events should point to a callback function that will handle that event. Only the events you register are handled; others are ignored. Use unlink and unlinkDir when you need to react to file or directory deletion (e.g. to sync your build output or trigger a reload).

persistent    default: true

• Indicates whether the process should continue to run as long as files are being watched.

ignored

• Defines files/paths to be ignored. The whole relative or absolute path is tested, not just filename. (anymatch-compatible definition)

ignoreInitial    default: false

• If set to true will not fire add or addDir events when the files/directories are first being discovered.

followSymlinks    default: true

• When false, only the symlinks themselves will be watched for changes instead of following the link references and bubbling events through the link's path.

cwd

• The base directory from which watch paths are to be derived. Paths emitted with events will be relative to this path and will use only forward slashes (/) on all operating systems.

disableGlobbing    default: false

• If set to true then the strings passed to .watch() and .unwatch() are treated as literal path names, even if they look like globs.

usePolling    default: false

• Whether to use fs.watchFile (backed by polling), or fs.watch. If polling leads to high CPU utilization, consider setting this to false.

interval    default: 100

• Interval of file system polling, in milliseconds.

binaryInterval    default: 300

• Interval of file system polling for binary files.

alwaysStat    default: false

• If relying upon the fs.Stats object that may get passed with add, addDir, and change events, set this to true to ensure it is provided even in cases where it wasn't already available from the underlying watch events.

depth    default: undefined

• If set, limits how many levels of subdirectories will be traversed when watching for changes.

awaitWriteFinish    default: false

• By default, the add event will fire when a file first appears on disk, before the entire file has been written.

ignorePermissionErrors    default: false

-Indicates whether to watch files that don't have read permissions if possible. If watching fails due to EPERM or EACCES with this set to true, the errors will be suppressed silently.

atomic    default: true

• Automatically filters out artifacts that occur when using editors that use "atomic writes" instead of writing directly to the source file.

Most of the Watch Object Options are directly from chokidar which is being used to handle the file monitoring. You may want to visit the chokidar repo for more information. Please note that event paths are altered by NSS to only use forward slashes (/) on all operating systems.

:bookmark: Server Methods

With your new instance of NSS you can call any of the following public methods:

addWebsocketCallback(pattern^, callback)

• Register a function (callback) to receive messages from the front-end if the pages URL matches the pattern.

getAddresses

• Returns an array of all the IP addresses you can reach this server at either from the machine itself or on the local area network (LAN).

getWatched

• Returns an array of watcher objects showing you which directories and files are actively being watched for changes.

message(pageId | pattern^, msg)

• Send a message (msg) via WebSocket to the page that matches the pageId, or send to a page or pages that match the pattern.

printListeningAddresses([returnInstead = false])

• Prints a message to console with all the addresses the server is available at. If you want full control of the printing you can set returnInstead to true.

reloadPages()

• Sends the reload signal to all active pages.

reloadSinglePage(pattern^)

• Sends the reload signal to a single page or group of pages matching the pattern.

reloadSingleStyles(pattern^)

• Sends the refreshCSS signal to a single page or group of pages matching the pattern.

reloadStyles()

• Sends the refreshCSS signal to all active pages.

removeWebsocketCallback(pattern^, callback)

• Unregister (stop messaging) a callback function that was initially registered with the pattern.

start([callback]) | start([port], [callback], [printAddresses=true])

• Starts the HTTP and WebSocket servers and notifies callback if present. Port is meant to be an internal option for NSS only but you may specify a port number for NSS to use if you have strict requirements in your environment. NOTE: This is a blocking process and will keep any application that ran it alive until stopped gracefully or forcefully terminated. If you do not want this behavior for any reason you will need to call this in its own process. Set printAddresses to false if you want to hide or print the server address on your own.

stop([callback])

• Gracefully closes all HTTP and WebSocket connections and turns off the servers, notifying callback if present.

unwatch(paths^^)

• Stop watching directories or files (paths) for changes previously registered with watch.

watch(paths^^, watchOptionsObject)

• Start watching a file, files, directory, or directories (paths) for changes and then callback to functions set in watchOptionsObject that will respond to these changes.

watchEnd()

• Stop watching all registered file, files, directory, or directories for changes.

:bookmark: Symbol Key

^ pattern refers to either a RegExp object or a string of text that represents a regular expression without surrounding slashes (/) or modifiers (g, i, etc.). If you provide a string make sure to correctly escape literal characters. In some instances pattern can also be a string of text representing a page's unique ID. pattern does not recognize glob patterns!

^^ paths refers either to a string or array of strings. Paths to files, directories to be watched recursively, or glob patterns. Globs must not contain windows separators (\), because that's how they work by the standard — you'll need to replace them with forward slashes (/). For additional glob documentation, check out low-level library: picomatch.

Changelog

The current changelog is here. All other changelogs are here.

Contributions

NSS is an open source community supported project, if you would like to help please consider tackling an issue or making a donation to keep the project alive.