⚡ airun

Instant live-reload dev server for static HTML/CSS/JS projects.
No config. No subcommands. Just point it at a file.

airun index.html

Install

npm install -g airun

Or without installing:

npx airun index.html

Usage

airun <entry-file> [options]

Examples

# Basic usage
airun index.html
airun index.html --port 8080

# Advanced features
airun index.html --spa --https --compress
airun index.html --proxy "/api/*:http://localhost:3001"
airun index.html --auth "user:pass" --cors
airun index.html --build "npm run build" --watch-build

Options

| Flag | Default | Description | |---|---|---| | --port <port> | 3000 | Port or port range (e.g., 3000-3010) | | --host <host> | 0.0.0.0 | Host to bind to | | --no-open | (opens by default) | Skip browser auto-open | | --no-reload | (reload on by default) | Disable live-reload | | --spa | | Enable SPA mode (serve index.html for all routes) | | --https | | Enable HTTPS with self-signed certificate | | --cert <cert> | | Path to SSL certificate file | | --key <key> | | Path to SSL private key file | | --compress | | Enable gzip compression | | --cors | | Enable CORS headers | | -H, --header <header> | | Add custom header (e.g., "X-Custom: value") | | --auth <user:pass> | | Enable basic authentication | | --proxy <target> | | Proxy API requests (e.g., /api/*:http://localhost:3001) | | --list | | Enable directory listing | | --inject <file> | | Inject custom script file | | --build <command> | | Run build command before serving | | --watch-build | | Rebuild on file changes | | --include <patterns> | **/* | File patterns to watch (comma-separated) | | --exclude <patterns> | node_modules/**,.git/** | File patterns to ignore (comma-separated) | | --delay <ms> | 120 | Delay before reload (ms) | | --verbose | | Enable verbose logging | | --config <file> | | Load configuration from JSON file |

Features

• ⚡ Instant live reload via WebSockets — no polling
• 📁 Serves any static directory — HTML, CSS, JS, images, fonts
• 🌐 LAN access — network URL for testing on phones/tablets
• 🔄 Auto port fallback — switches if port is busy
• 🎨 Colored terminal output
• 🛑 Graceful shutdown on Ctrl+C

Advanced Features

• 🖥️ SPA Support — serve index.html for all routes (React/Vue/Angular)
• 🔒 HTTPS — self-signed certificates or custom certs
• 🗜️ Compression — automatic gzip for text files
• 🌐 CORS — cross-origin resource sharing headers
• 🔐 Basic Auth — simple authentication
• 🔀 API Proxy — proxy requests to backend servers
• 📂 Directory Listing — browse directories when no index.html
• 💉 Script Injection — inject custom JavaScript files
• 🔨 Build Integration — run build commands automatically
• 👀 Custom Watching — include/exclude specific file patterns
• ⚙️ Configuration Files — JSON config for complex setups

Configuration File

Create an .airunrc.json file in your project root:

{
  "spa": true,
  "https": true,
  "compress": true,
  "cors": true,
  "headers": ["X-Custom: value"],
  "proxy": "/api/*:http://localhost:3001",
  "inject": ["analytics.js"],
  "build": "npm run build",
  "watchBuild": true,
  "include": ["src/**/*", "public/**/*"],
  "exclude": ["node_modules/**", ".git/**", "dist/**"]
}

Examples

React Development

airun index.html --spa --port 3000-3010

Full-Stack with API Proxy

airun index.html --proxy "/api/*:http://localhost:3001" --cors

HTTPS Development

airun index.html --https --cert cert.pem --key key.pem

Build Integration

airun dist/index.html --build "npm run build" --watch-build

Custom Headers & Auth

airun index.html --auth "admin:secret" --header "X-API-Key: abc123"

Requirements

Node.js >= 18

License

MIT © xklaim

Features

• ⚡ Instant live reload via WebSockets — no polling
• 📁 Serves any static directory — HTML, CSS, JS, images, fonts
• 🌐 LAN access — network URL for testing on phones/tablets
• 🔄 Auto port fallback — switches if 3000 is busy
• 🎨 Colored terminal output
• 🛑 Graceful shutdown on Ctrl+C

Requirements

Node.js >= 18

License

MIT © xklaim