host-this

The modern CLI server for developers

A powerful, zero-config development server combining the best features of live-server, nodemon, and rsync into one lightning-fast tool. Built on Fastify for maximum performance.

Why host-this?

Most developers juggle multiple tools for local development. host-this consolidates your workflow into a single, powerful command:

| Feature | host-this | live-server | http-server | webpack-dev-server | |---------|-----------|-------------|-------------|-------------------| | Static file serving | ✓ | ✓ | ✓ | ✓ | | Live reload | ✓ | ✓ | ✗ | ✓ | | SPA routing | ✓ | ✗ | ✗ | ✓ | | Configuration file support | ✓ | ✗ | ✗ | ✓ | | Execute commands on change | ✓ | ✗ | ✗ | Limited | | Copy files on change | ✓ | ✗ | ✗ | ✗ | | File server/directory browsing | ✓ | ✗ | ✓ | ✗ | | Custom watch patterns | ✓ | Limited | ✗ | ✓ | | Zero configuration | ✓ | ✓ | ✓ | ✗ | | Built on Fastify | ✓ | ✗ | ✗ | ✗ |

Performance: Built on Fastify, one of the fastest web frameworks available, ensuring minimal overhead even with live reload enabled.

Features

Core Capabilities

• Static & SPA Hosting - Serve static sites with smart file resolution (index.html, .html extensions) or SPAs with client-side routing support
• Instant Live Reload - WebSocket-based live reload with sub-second response times
• Smart File Watching - Monitor file changes with configurable patterns and execute custom commands
• Auto-Copy on Change - Sync files to destination directories automatically
• File Server Mode - Browse directories with a built-in file explorer
• Zero Configuration - Works out of the box with sensible defaults
• CORS Built-in - Pre-configured CORS support for API development
• Cross-Platform - Runs seamlessly on Linux, macOS, and Windows

Developer Experience

• Regex Pattern Matching - Fine-tune what files to watch and ignore
• Manual Reload - Press r + Enter to trigger reload manually
• Verbose Logging - Debug mode for detailed operational insights
• Auto Browser Open - Launch your browser automatically on server start
• Custom Commands - Run build scripts, linters, or any command on file changes
• Multiple Directory Support - Serve from one directory, watch another

Installation

npm install -g host-this

Requirements: Node.js 18 or higher

Quick Start

Get up and running in seconds:

# Navigate to your project
cd my-project

# Start a basic static server
hostthis

# Development mode with live reload
hostthis -D

# SPA mode with live reload
hostthis -S -D

# File server with directory browsing
hostthis -F

Your site is now live at http://localhost:3000

Real-World Examples

React/Vue/Angular Development

Watch files, rebuild on changes, and live reload:

hostthis -S -D -e "npm run build"

Static Site with Live Preview

Perfect for HTML/CSS/JS projects:

hostthis -D

SSG Development (Hugo, Jekyll, VuePress)

Watch source files and serve the built directory:

hostthis -S -D \
  -R "./docs" \
  -B "./docs/.vuepress/dist" \
  -i ".vuepress/.cache/,.vuepress/.temp/" \
  -e "npm run build"

API Development with CORS

Test your API from different origins:

hostthis -d ./api -p 8080 -H 0.0.0.0

Local File Sharing

Share files on your network:

hostthis -F -H 0.0.0.0 -p 8080

Custom Build Pipeline

Watch source files, build, and sync to dist:

hostthis -D \
  -R "./src" \
  -B "./dist" \
  -w "src/.*\.(js|css|html)" \
  -i "node_modules/,\.git/" \
  -e "npm run build" \
  -c "./dist"

Multi-Step Build Process

Chain multiple commands on file changes:

hostthis -D -e "npm run lint && npm run build && npm test"

CLI Options

Server Options

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --spa | -S | false | SPA mode - enables client-side routing with fallback to index.html | | --dev | -D | false | Development mode - enables live reload via WebSocket | | --web | -W | true | Enable/disable the web server | | --fileserver | -F | false | File server mode - browse directories with listings | | --host | -H | localhost | Hostname to bind (use 0.0.0.0 for network access) | | --port | -p | 3000 | Port number to bind |

Directory Options

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --dir | -d | ./ | Base directory for all operations | | --webdir | -B | (uses --dir) | Directory to serve web content from | | --devdir | -R | (uses --dir) | Directory to watch for changes |

File Watching Options

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --watch | -w | .* | Watch pattern (regex) - comma separated for multiple patterns | | --ignore | -i | /[.].+/ | Ignore pattern (regex) - comma separated for multiple patterns | | --copy | -c | false | Copy changed files to specified directory | | --exec | -e | false | Execute command on file changes (e.g., build scripts) |

Additional Options

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --init | | | Generate a .hostthisrc configuration file and exit | | --open | -O | false | Automatically open default browser on start | | --consolereload | -C | false | Disable manual reload (type 'r' + Enter) | | --verbose | -V | false | Enable verbose logging for debugging | | --version | | | Show version number | | --help | | | Show help message |

How It Works

host-this is architected for performance and reliability:

1. Fastify Server - Lightning-fast HTTP server with automatic MIME type detection
2. WebSocket Live Reload - Persistent connection for instant browser updates (dev mode)
3. Chokidar File Watching - Efficient, cross-platform file system monitoring
4. Smart File Resolution - Mimics nginx/Apache behavior (index.html, .html extensions)
5. Command Execution - Run custom scripts with configurable timeout and error handling
6. Async File Operations - Non-blocking file copying and manipulation

Development Mode Features

When running with the -D flag:

• Automatic Code Injection - Inserts live reload script into HTML files
• WebSocket Connection - Maintains persistent connection for instant updates
• File Change Detection - Monitors changes using efficient OS-level APIs
• Custom Command Execution - Run build tools, linters, tests on every change
• Automatic File Syncing - Copy files to destination directories
• Manual Reload Trigger - Press r + Enter for manual page refresh

Use Cases by Workflow

Frontend Development

• React, Vue, Angular, Svelte applications
• Vanilla JavaScript projects
• CSS/SCSS development with live preview

Static Site Generators

• Hugo, Jekyll, Eleventy
• VuePress, Docusaurus, MkDocs
• Custom static site builders

Prototyping

• Quick HTML/CSS mockups
• Design system development
• Component library testing

Backend Development

• API testing with CORS
• Static asset serving for backend frameworks
• Mock server for frontend development

Team Collaboration

• Local network file sharing
• Demo presentations
• Team code reviews

Technical Stack

• Fastify - High-performance web framework
• Chokidar - Efficient file watching
• WebSocket - Real-time browser communication
• Sade - Lightweight CLI framework
• Chalk - Terminal styling
• ES Modules - Modern JavaScript architecture

Configuration File

host-this supports configuration files to eliminate repetitive command-line arguments. This is especially useful for projects with consistent hosting requirements.

Generating a Configuration File

Create a .hostthisrc template with all available options:

hostthis --init

This generates a .hostthisrc file in your current directory:

{
  "spa": false,
  "dev": true,
  "web": true,
  "fileserver": false,
  "host": "localhost",
  "port": 3000,
  "dir": "./",
  "webdir": "./dist",
  "devdir": "./src",
  "copy": false,
  "watch": ".*\\.(js|css|html)",
  "ignore": "node_modules/,\\.git/,dist/",
  "exec": false,
  "open": false,
  "verbose": false,
  "compress": false,
  "cache": false,
  "consolereload": false
}

Edit the values to match your project, then simply run:

hostthis

No command-line arguments needed!

Configuration Priority

Configuration is merged in this order (highest priority wins):

1. Explicit command-line arguments - Only override if different from default
2. Configuration file - .hostthisrc or .hostthisrc.json in current directory
3. Default values - Built-in defaults

Example:

• Config file: "port": 8080
• Run hostthis → Uses port 8080 (from config)
• Run hostthis -p 3000 → Uses port 3000 (explicit CLI arg overrides)
• Run hostthis -V → Uses port 8080 from config, enables verbose from CLI

Available Configuration Options

All CLI options can be used in the configuration file:

{
  "spa": false,
  "dev": true,
  "web": true,
  "fileserver": false,
  "host": "localhost",
  "port": 3000,
  "dir": "./",
  "webdir": "./dist",
  "devdir": "./src",
  "copy": "./backup",
  "watch": ".*\\.(js|css|html)",
  "ignore": "node_modules/,\\.git/",
  "exec": "npm run build",
  "open": true,
  "verbose": false,
  "compress": false,
  "cache": false,
  "consolereload": false
}

Real-World Configuration Examples

React/CRA Development:

{
  "spa": true,
  "dev": true,
  "port": 3000,
  "webdir": "./build",
  "devdir": "./src",
  "exec": "npm run build",
  "ignore": "node_modules/,\\.git/,build/,coverage/",
  "open": true
}

Run with: hostthis (uses all settings from config)

VuePress Documentation:

{
  "spa": true,
  "dev": true,
  "webdir": "docs/.vuepress/dist",
  "devdir": "docs",
  "ignore": ".vuepress/.cache/,.vuepress/.temp/,.vuepress/dist/",
  "exec": "npm run build",
  "port": 8080
}

Run with: hostthis (builds and serves on change)

Next.js Static Export:

{
  "spa": true,
  "dev": true,
  "webdir": "./out",
  "devdir": "./pages",
  "exec": "npm run build",
  "ignore": "node_modules/,.next/,out/",
  "watch": "pages/.*\\.(js|jsx|ts|tsx),styles/.*\\.css"
}

Static Site with Live Reload:

{
  "dev": true,
  "port": 8080,
  "open": true,
  "verbose": false
}

Run with: hostthis for instant development server

File Server for Network Sharing:

{
  "fileserver": true,
  "host": "0.0.0.0",
  "port": 8080,
  "dir": "./public"
}

Run with: hostthis to share files on local network

Configuration Tips

1. Version control: Commit .hostthisrc to share settings with your team
2. Local overrides: Add .hostthisrc.local to .gitignore for personal settings
3. Multiple configs: Use different config files for different environments (copy/rename as needed)
4. Regex escaping: Remember to escape backslashes in JSON strings (\\. instead of \.)

Troubleshooting Config Files

Config not loading?

• Ensure file is named exactly .hostthisrc or .hostthisrc.json
• Check JSON syntax (use npx jsonlint .hostthisrc to validate)
• Verify you're running hostthis in the same directory as the config file
• Try hostthis -V to see if config is loaded (shows in output)

Config option not working?

• Check spelling matches exactly (case-sensitive)
• See warning messages for unknown options
• CLI arguments only override if explicitly different from defaults

Advanced Configuration

Environment-Specific Configs

Create npm scripts for different environments:

{
  "scripts": {
    "dev": "hostthis -S -D -e 'npm run build'",
    "preview": "hostthis -S -d ./dist",
    "share": "hostthis -F -H 0.0.0.0 -p 8080"
  }
}

Or use configuration files with script overrides:

{
  "scripts": {
    "dev": "hostthis",
    "dev:verbose": "hostthis -V",
    "preview": "hostthis --web true --dev false"
  }
}

Complex Watch Patterns

Watch specific file types across multiple directories:

hostthis -D \
  -w "src/.*\.(js|jsx|ts|tsx),styles/.*\.scss,public/.*\.html" \
  -i "node_modules/,\.git/,dist/,build/,coverage/"

Serve Different Directories

Watch source files but serve the built output:

hostthis -D \
  --devdir "./src" \
  --webdir "./dist" \
  -e "npm run build"

Troubleshooting

Live Reload Not Working

1. Check browser console for WebSocket connection errors
2. Ensure you're using -D flag
3. Verify firewall isn't blocking WebSocket connections
4. Try verbose mode: hostthis -D -V

Command Not Executing on Changes

1. Check that files match your watch pattern: hostthis -D -V -e "your-command"
2. Verify command works standalone in terminal
3. Check ignore patterns aren't excluding your files
4. Use absolute paths for complex commands

SPA Routes Returning 404

1. Ensure you're using -S flag
2. Check that index.html exists in your web directory
3. Try verbose mode to see path resolution: hostthis -S -V

Performance Issues

1. Add specific watch patterns instead of watching everything
2. Exclude large directories: -i "node_modules/,\.git/,dist/"
3. Use --copy only when necessary
4. Disable compression if serving locally only

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Development Setup

# Clone the repository
git clone https://github.com/MRIncWorld/host-this.git
cd host-this

# Install dependencies
npm install

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run format

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

License

GNU AGPLv3 - See LICENSE file for details

Author

Mitchell R

• GitHub: @MRIncWorld
• npm: host-this

Related Projects

• live-server - Simple development server with live reload
• http-server - Simple, zero-configuration HTTP server
• browser-sync - Keep multiple browsers in sync
• serve - Static file serving and directory listing

Changelog

See CHANGELOG.md for detailed version history.

Made with care for the developer community

Repository: https://github.com/MRIncWorld/host-this