gib-runs

v3.0.2

Published

2 months ago

Plugin-based development server with live reload - runs on merit, not nepotism

0High
0Medium
0Low

development server live-reload hot-reload hmr http https http2 spa cli devserver watch websocket performance compression proxy plugin extensible

🚀 GIB-RUNS

Plugin-based development server with live reload. Built for developers who value capability over connections.

"Unlike some people, this actually runs on merit, not nepotism."

What's New in v3.0.2?

🔒 Security Fixes - Fixed IP spoofing vulnerability in rate limiter and password storage in share manager
🐛 Bug Fixes - Fixed memory leaks in logger and watcher, eliminated SPA middleware duplication
⚡ Performance - Optimized share manager cleanup and reduced port check timeout
🔧 Code Quality - Eliminated code duplications and improved cleanup handlers
✅ Quality - 21 issues fixed, all tests passing, ESLint clean

Changelog

Why GIB-RUNS?

Named after Indonesia's Vice President Gibran Rakabuming Raka, who got his position through family connections. But unlike certain political figures, this server:

✅ Earned its position through real features
✅ Works without shortcuts or special treatment
✅ Serves everyone equally
✅ Transparent and honest about what it does
✅ Performance based on actual metrics

"When your dev server has more integrity than some vice presidents."

Features

🔄 Live Reload - Automatic browser refresh on file changes
⚡ Hot CSS Injection - Update styles without full page reload
🎨 Beautiful UI - Modern status indicator with real-time feedback
📊 Performance Monitoring - Track requests, reloads, and uptime
📝 Comprehensive Logging - All requests, errors, and file changes with timestamps and file sizes
🔀 Smart File Tracking - Accurately detects file moved, created, changed, and deleted operations
📜 Request History - Track last 50 requests via /history endpoint
🗜️ Compression - Built-in gzip compression
🔒 HTTPS/HTTP2 - Secure development with modern protocols
🌐 CORS Support - Easy cross-origin development
🔐 HTTP Auth - Protect your development server
🎯 SPA Support - Perfect for Single Page Applications
🔌 Proxy Support - Proxy API requests during development
📦 Middleware - Extend functionality with custom middleware
🎭 Mount Directories - Serve multiple directories on different routes
🚀 NPM Scripts - Run npm scripts alongside the server
🔄 PM2 Integration - Production-ready process management
🌍 Public Tunnels - Share your dev server with anyone, anywhere
📱 Multi-Device - Access from any device on your network

🆕 Advanced Features

🎯 Interactive CLI - Inquirer-style setup wizard
🔍 Auto-Detect - Automatically detect project type (React, Vue, Angular, etc.)
⚙️ Config Generator - Generate .gib-runs.json with one command
🎨 Enhanced Logging - Color-coded logs with better formatting
🔗 Secure Share Links - Password-protected share links with expiration
📱 QR Code Sharing - Share via QR code for mobile access
🐳 Docker Support - Generate Docker files and docker-compose
🔧 Port Resolver - Automatic port conflict resolution
🏢 Multi-Project - Run multiple projects simultaneously
🌐 Remote Collaboration - Secure team sharing with access control

Installation

# Global (recommended)
npm install -g gib-runs

# Local
npm install --save-dev gib-runs

Quick Start

# Interactive setup (recommended for first time)
gib-runs --init

# Auto-detect project and start
gib-runs --detect
gib-runs

# Serve current directory
gib-runs

# Serve specific directory
gib-runs ./dist

# Custom port
gib-runs --port=3000

# SPA mode
gib-runs --spa

# With HTTPS
gib-runs --https=./config/https.conf.js

# Generate config file
gib-runs --generate-config

# Docker setup
gib-runs --docker-init

Common Use Cases

Basic Development Server

# Serve current directory with live reload
gib-runs

# Custom port and verbose logging
gib-runs --port=3000 --verbose

# Serve specific directory
gib-runs ./public

Single Page Applications

# SPA mode (redirects all routes to index.html)
gib-runs --spa

# SPA with custom port
gib-runs --spa --port=8000

Proxy API Requests

# Proxy /api to backend server
gib-runs --proxy=/api:http://localhost:3000

# Multiple proxies
gib-runs --proxy=/api:http://localhost:3000 --proxy=/auth:http://localhost:4000

Mount Directories

# Mount node_modules to /components
gib-runs --mount=/components:./node_modules

# Multiple mounts
gib-runs --mount=/static:./assets --mount=/lib:./node_modules

Run with NPM Scripts

# Run npm dev script with live reload
gib-runs --npm-script=dev

# Run with PM2 process manager
gib-runs --npm-script=dev --pm2

# Run custom command
gib-runs --exec="node server.js"

Public Tunnels

# Create public URL (no signup needed)
gib-runs --tunnel

# Use Cloudflare Tunnel
gib-runs --tunnel-service=cloudflared

# Use Ngrok (requires auth token)
gib-runs --tunnel-service=ngrok --tunnel-authtoken=YOUR_TOKEN

HTTPS Development

Create https.conf.js:

const fs = require('fs');

module.exports = {
  cert: fs.readFileSync(__dirname + '/server.cert'),
  key: fs.readFileSync(__dirname + '/server.key'),
  passphrase: 'your-passphrase'
};

Then run:

gib-runs --https=./https.conf.js

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --port=NUMBER | Port to use | 8080 | | --host=ADDRESS | Address to bind to | 0.0.0.0 | | --open=PATH | Path to open in browser | / | | --no-browser | Suppress browser launch | false | | -q, --quiet | Suppress logging | false | | -V, --verbose | Verbose logging | false | | --watch=PATH | Paths to watch (comma-separated) | All files | | --ignore=PATH | Paths to ignore (comma-separated) | None | | --no-css-inject | Reload page on CSS change | false | | --spa | Single Page App mode | false | | --cors | Enable CORS | false | | --https=PATH | HTTPS config module | None | | --proxy=ROUTE:URL | Proxy requests | None | | --middleware=PATH | Custom middleware | None | | --htpasswd=PATH | HTTP auth file | None | | --tunnel | Create public tunnel | false | | --tunnel-service=NAME | Tunnel service (lt, cf, ngrok) | localtunnel | | --npm-script=SCRIPT | Run npm script | None | | --exec=COMMAND | Run custom command | None | | --pm2 | Use PM2 process manager | false | | --auto-restart | Auto-restart server on crash | false | | --enable-upload | Enable file upload endpoint | false | | --log-to-file | Log requests to file | false | | --init | Interactive setup wizard | - | | --detect | Auto-detect project type | - | | --generate-config | Generate config file | - | | --docker-init | Generate Docker files | - | | --share | Create secure share link | false | | --share-password | Password-protect share link | false | | --share-expires=MIN | Share link expiration (minutes) | None | | --share-qr | Show QR code for share link | false |

Node.js API

const gibRuns = require('gib-runs');

const server = gibRuns.start({
  port: 8080,
  host: '0.0.0.0',
  root: './public',
  open: true,
  file: 'index.html',
  wait: 100,
  logLevel: 2,
  compression: true,
  cors: true,
  spa: true,
  watch: ['./src', './public'],
  ignore: ['node_modules', '.git'],
  mount: [
    ['/components', './node_modules'],
    ['/assets', './static']
  ],
  proxy: [
    ['/api', 'http://localhost:3000']
  ],
  middleware: [
    function(req, res, next) {
      console.log('Custom middleware');
      next();
    }
  ]
});

// Broadcast custom message to all connected clients
gibRuns.broadcast('reload');

// Shutdown programmatically
// gibRuns.shutdown();

Configuration File

Create ~/.gib-runs.json for global defaults:

{
  "port": 8080,
  "host": "0.0.0.0",
  "open": true,
  "logLevel": 2,
  "compression": true,
  "cors": false
}

Or .gib-runs.json in your project root (overrides global config):

{
  "port": 3000,
  "spa": true,
  "watch": ["src", "public"],
  "ignore": ["*.test.js", "*.spec.js"]
}

Priority: CLI arguments > Project config > Global config > Defaults

Advanced Features

Request History

Track all HTTP requests for debugging:

# View request history
curl http://localhost:8080/history

Response:

{
  "total": 10,
  "requests": [
    {
      "timestamp": "2026-02-15T06:09:17.875Z",
      "method": "GET",
      "url": "/index.html",
      "status": 200,
      "duration": "5ms",
      "ip": "127.0.0.1"
    }
  ]
}

Environment Variables

Automatically loads .env file from project root:

# .env
API_KEY=your-secret-key
DATABASE_URL=postgres://localhost/mydb

Use in HTML with ${VAR_NAME} syntax:

<script>
  const apiKey = '${API_KEY}';
</script>

File Upload Endpoint

# Enable file upload
gib-runs --enable-upload

Upload files via POST to /upload:

const formData = new FormData();
formData.append('file', fileInput.files[0]);

fetch('/upload', {
  method: 'POST',
  body: formData
})
.then(res => res.json())
.then(data => console.log('Uploaded:', data.file));

Health Check Endpoint

Access server health at /health:

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "uptime": 123.45,
  "server": {
    "requests": 42,
    "reloads": 5,
    "memory": { "rss": "45MB", "heapUsed": "23MB" }
  },
  "system": {
    "platform": "linux",
    "cpus": 8,
    "freemem": "2048MB"
  }
}

Request Logging

# Log all requests to file
gib-runs --log-to-file

# Logs saved to gib-runs.log

Parse logs with jq:

# Show all 404 errors
cat gib-runs.log | jq 'select(.status == 404)'

# Show slow requests (>100ms)
cat gib-runs.log | jq 'select(.duration | tonumber > 100)'

Custom Middleware

Create middleware/custom.js:

module.exports = (req, res, next) => {
  console.log('Request:', req.url);
  next();
};

Use it:

gib-runs --middleware=./middleware/custom.js

Network Access

Server automatically binds to 0.0.0.0 and shows all network URLs:

🚀 GIB-RUNS v3.0.2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📁 Root:       /home/user/project
  🌐 Local:      http://127.0.0.1:8080
  🔗 Network:    http://192.168.1.100:8080
  🔄 Live Reload: Enabled (no dynasty needed)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Access from any device on your network using the network URLs.

Tunnel Services

Share your local server with anyone, anywhere:

| Service | Command | Signup Required | |---------|---------|-----------------| | LocalTunnel | --tunnel | ❌ No | | Cloudflare | --tunnel-service=cloudflared | ❌ No | | Ngrok | --tunnel-service=ngrok --tunnel-authtoken=TOKEN | ✅ Yes | | Pinggy | --tunnel-service=pinggy | ❌ No |

Example:

# Default (LocalTunnel)
gib-runs --tunnel

# Cloudflare (fast and reliable)
gib-runs --tunnel-service=cloudflared

Troubleshooting

No reload on changes

Check browser console for WebSocket connection
Ensure files are being watched: gib-runs --verbose
Try increasing wait time: gib-runs --wait=500

Port already in use

GIB-RUNS will automatically try another port. Or specify one:

gib-runs --port=3000

ENOSPC error (Linux)

Increase file watchers limit:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE file for details

Author

sofinco

GitHub: @levouinse
Repository: gib-runs