@nutsloop/ivy-server

v1.8.0-alpha.2

Published

6 months ago

Facilitating & Enhancing Network Strength.

0High
0Medium
0Low

nutsloop

node.js server esmodule threads cluster

@nutsloop/ivy-server

Facilitating & Enhancing Network Strength

⚠ Alpha Warning: This project is in early development. Expect breaking changes, bugs, and a little chaos. We document with love, but things may shift quickly.

Description

What is Ivy Server?

@nutsloop/ivy-server is a modern, powerful, TypeScript-powered command-line server. With a rust-native file watcher at its core, it enhances developer workflows with features like:

⚙️ Live browser reloading on file changes (powered by Rust) for instant feedback and seamless development
🛰️ Static and dynamic content serving
🔁 Built-in route support
🧪 Zero-config developer experience
🧩 Extensive CLI customisation through flags
🛠️ Experimental control room for remote management, audit via secure sockets (work in progress)
🌐 Multi-domain support — Serve content across multiple domains with ease!

Common uses include:

⚡️ Local development servers for fast feedback loops
🌐 Lightweight APIs and microservices
🧪 Experimental workflows and prototyping

Requirements

Supported Operating Systems:
- Linux (tested on Fedora and Oracle Linux)
- macOS
- ⚠ Windows is not supported
Software dependencies:
- Rust >= 1.55.0
- Node.js >= 20.0.0

Quick Start

📦 Installation

Install via npm:

Important:
@nutsloop/ivy-server runs only on Unix-like systems (macOS, Linux). Windows is currently not supported.
It also requires Node.js v20 or higher.

npm install @nutsloop/ivy-server
npm pkg set type=module

Warning:
@nutsloop/ivy-server is built exclusively with ES Modules (ESM).
Your entire project — including all route handlers — must use ESM.
CommonJS (require, module.exports) is not supported and will cause runtime errors.

To ensure compatibility:

Set "type": "module" in your package.json.
Use import / export syntax only.
Avoid .cjs or CommonJS-style tooling.

This strict ESM-only setup guarantees cleaner semantics and future-friendly module resolution.

Create a Public Directory

Ivy serves static files from a ./public directory by default. To get started, create the folder and add a basic index.html:

mkdir ./public
echo '<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Ivy Server</title>
  </head>
  <body>
    <h1>Hello from Ivy</h1>
  </body>
</html>' > ./public/index.html

Start the server:

export PATH="$PWD/node_modules/.bin:$PATH"
ivy-server spin

CLI Commands and Flags

Ivy Server includes powerful commands and flags for customisation.

Core Commands

spin: Start a single server instance:
```
ivy-server spin
```

cluster: Start multiple server instances using Node.js clusters:

# this will fork for the half of the available cpus
ivy-server cluster

help: View help documentation for commands/flags:
```
ivy-server --help
```
version: View the current version of Ivy Server:
```
ivy-server --version
```

🌍 Global Flags

| Flag | Type | Description | |-------------------------|------|---------------------------------------------------------------------------------------| | --ease, -e | void | Allows binding to ports below 1024 (note: system-level restrictions may still apply). | | --ease-cluster, -ec | void | Removes cluster CPU limits — allows forking any number of workers. |

# let’s assume the server has 8 CPUs available and system-level port restrictions have been eased.
ivy-server --ease --ease-cluster cluster --port=80 --cpus=32

🛠️ Common Flags

| Flag | Type |---------------------------------|----------- | --address, -a | --port, -p | --https, -S | --log, -l | --log-color, -lc | --log-persistent, -lp | --log-request-headers, | --acme-challenge, -ac | --control-room, -cr | --cut-user-agent, -cua | --hot-routes, -hr | --live-reload, -lr | --multi-domain, -md | --mute-client-error, -mce | --routes, -r | --virtual-routes, -vr | --to-index-html, -tih | --plugins, -P | --served-by, -sb | --socket, -s | --redirect-to, -rt | --redirect-to-https, -rth | --www-root, -wr | Description | -|----------------------------------------------------------------------| | string | Address to bind the server (default: 0.0.0.0). | | number | Port to run the server on (default: 3001). | | void\KVP | Enable HTTPS. | | void | Enable request logging. | | void | Colorize log output (requires --log). | | void | Persist logs to file/db (requires logConfig.js). | -lrh | void | Log request headers (requires --log). | | void | Serve ACME challenge files, skipping redirects/multidomain. | | void | Open a socket for stats/control panel. | | void | Hide the user-agent in logs. | | void | Enable hot reloading of routes. | | void/KVP | Live reload server when files change. | | string | Load multidomain config from file. | | void | Suppress client error logs. | | string | Path to custom routes file. | | string | Declare STATUS_CODE 200 for addresses (used with --to-index-html). | | void | Route all requests to index.html. | | array | Load list of comma-separated plugins. | | string | Set a custom served-by HTTP header. | | void | Enable socket/tls connection (requires socketConfig.js). | | string | Redirect requests to another URL (e.g., 301 redirects). | | void | Redirect requests to HTTPS (works with --redirect-to). | | string | Directory for static content. |

🧠 Cluster-Specific Flags

| Flag | Type | Description | |----------------|-------------|------------------------------------------------------------------------------------------| | --cpus, -c | number/void | Number of CPUs to utilize. If no value is provided, defaults to half the available CPUs. | | --exec, -e | string | Path to an entry file to execute in cluster mode. |

Example usage:

ivy-server cluster --cpus=4

Advanced Features

Multi-Domain Support

Serve multiple domains with a configuration file:

ivy-server spin --multi-domain=path/to/config.json

Plugin Support

Load plugins dynamically:

ivy-server spin --plugins=plugin1,plugin2

Live Reload

Enable reload of the browser when files change (rust powered in part):

ivy-server spin --live-reload

Development Notes

Ivy Server is not production-ready yet.
It works on Unix-like operating systems (Linux and macOS). Windows is unsupported.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@nutsloop/ivy-server

Description

What is Ivy Server?

Requirements

Quick Start

📦 Installation

Create a Public Directory

CLI Commands and Flags

Core Commands

🌍 Global Flags

🌍 Global Flags

🛠️ Common Flags

🧠 Cluster-Specific Flags

Advanced Features

Multi-Domain Support

Plugin Support

Live Reload

Development Notes

Links