English | 中文

soon-serve

A lightweight local development server tool for quickly starting static resource services or proxying backend interfaces, suitable for frontend development and debugging scenarios.

Features

• 🚀 Quickly start a local HTTP server
• 📁 Support for static file hosting
• 🔗 Built-in CORS support to solve cross-origin issues
• ⚙️ Command-line parameters for custom configuration (port, path, etc.)
• 🔁 API proxy functionality with path rewriting support
• 🌐 Automatically open browser
• 📦 Zero dependencies, pure Node.js implementation
• 📊 Merged request logging with configurable threshold
• 🎯 Prefixless proxy support for catch-all proxying
• 📝 Improved request handling order with 404-based fallthrough

Usage

Basic Usage

# Start service in current directory
soon-serve

# Start service with specified directory
soon-serve -s ./public

# Start service with specified port
soon-serve -p 3000

# Start service and automatically open browser
soon-serve -o

Command Line Parameters

| Parameter | Full Name | Description | Example | |-----------|-----------|-------------|---------| | -p | --port | Specify port number (append f to disable auto increment) | -p 3000 or -p 3000f | | -s | --serve | Specify serving directory | -s ./dist | | -r | --rewrites | Configure proxy rules | -r /api->http://localhost:8080/api | | -b | --base | Set base path | -b /app | | -o | --open | Automatically open browser (with optional path) | -o or -o /admin | | -l | --logThreshold | Set log threshold in milliseconds (default: 3000) | -l 1000 |

Proxy Rules Details

soon-serve supports powerful API proxy functionality to solve cross-origin issues during development. Here are several common proxy rule configuration methods:

1. Basic Proxy

Proxy all requests with a specific path to the target server:

# Proxy all requests starting with /api to http://localhost:8080
soon-serve -r /api->http://localhost:8080/api

# Examples:
# /api/users -> http://localhost:8080/api/users
# /api/products/123 -> http://localhost:8080/api/products/123

2. Multiple Paths to Same Target

Proxy requests from multiple path prefixes to the same target server:

# Proxy requests from both /api and /upload to http://localhost:8080
soon-serve -r /api,/upload->http://localhost:8080

# Or use multiple -r parameters
soon-serve -r /api->http://localhost:8080/api -r /upload->http://localhost:8080/upload

3. Prefixless Proxy (Catch-all)

Proxy all requests that don't match any prefixed proxy rules to a target server:

# Proxy all requests to http://localhost:8080
soon-serve -r http://localhost:8080

Request Handling Order

soon-serve processes requests in a specific order based on the request method:

For GET Requests:

1. Try prefixed proxy rules
2. Try static files
3. Try prefixless proxy (if configured)
4. Return default home page (index.html)

For Non-GET Requests:

1. Try prefixed proxy rules
2. Try prefixless proxy (if configured)
3. Return 404 Not Found

Logging System

soon-serve includes a merged request logging system with configurable threshold:

• Requests under threshold (default: 3000 milliseconds): Print one combined log
• Requests over threshold: Print two logs (start and end)
• Log order: Maintains chronological order of requests

Example:

# Set log threshold to 1000 milliseconds
soon-serve -l 1000

soon-serve

一个轻量级的本地开发服务器工具，用于快速启动静态资源服务或代理后端接口，适用于前端开发调试场景。

功能特点

• 🚀 快速启动本地 HTTP 服务器
• 📁 支持静态文件托管
• 🔗 内置 CORS 支持，解决跨域问题
• ⚙️ 命令行参数自定义配置（端口、路径等）
• 🔁 API 代理功能，支持路径重写
• 🌐 自动打开浏览器
• 📦 零依赖，纯 Node.js 实现
• 📊 合并请求日志，支持可配置的阈值
• 🎯 无前缀代理支持，实现全量代理
• 📝 改进的请求处理顺序，基于 404 的回退机制

使用方法

基础使用

# 在当前目录启动服务
soon-serve

# 指定目录启动服务
soon-serve -s ./public

# 指定端口启动服务
soon-serve -p 3000

# 启动服务并自动打开浏览器
soon-serve -o

命令行参数

| 参数 | 全称 | 描述 | 示例 | |------|------|------|------| | -p | --port | 指定端口号（末尾加 f 可禁用自动递增） | -p 3000 或 -p 3000f | | -s | --serve | 指定服务目录 | -s ./dist | | -r | --rewrites | 配置代理规则 | -r /api->http://localhost:8080/api | | -b | --base | 设置基础路径 | -b /app | | -o | --open | 自动打开浏览器（可指定路径） | -o 或 -o /admin | | -l | --logThreshold | 设置日志阈值（毫秒），默认值：3000 | -l 1000 |

代理规则详解

soon-serve 支持强大的 API 代理功能，可以解决开发过程中的跨域问题。以下是几种常见的代理规则配置方式：

1. 基础代理

将特定路径的所有请求代理到目标服务器：

# 将 /api 开头的所有请求代理到 http://localhost:8080
soon-serve -r /api->http://localhost:8080/api

# 示例：
# /api/users -> http://localhost:8080/api/users
# /api/products/123 -> http://localhost:8080/api/products/123

2. 多路径代理到同一目标

将多个路径前缀的请求代理到同一个目标服务器：

# 将 /api 和 /upload 的请求都代理到 http://localhost:8080
soon-serve -r /api,/upload->http://localhost:8080

# 或者使用多个 -r 参数
soon-serve -r /api->http://localhost:8080/api -r /upload->http://localhost:8080/upload

3. 无前缀代理（全量代理）

将所有未匹配到带前缀代理规则的请求代理到目标服务器：

# 将所有请求代理到 http://localhost:8080
soon-serve -r http://localhost:8080

请求处理顺序

soon-serve 根据请求方法按照特定顺序处理请求：

对于 GET 请求：

1. 尝试带前缀的代理规则
2. 尝试静态文件
3. 尝试无前缀代理（如果配置）
4. 返回默认首页（index.html）

对于非 GET 请求：

1. 尝试带前缀的代理规则
2. 尝试无前缀代理（如果配置）
3. 返回 404 Not Found

日志系统

soon-serve 包含一个合并请求日志系统，支持可配置的阈值：

• 阈值以下的请求（默认：3000 毫秒）：打印一个合并日志
• 阈值以上的请求：打印两个日志（开始和结束）
• 日志顺序：保持请求的时间顺序

示例：

# 设置日志阈值为 1000 毫秒
soon-serve -l 1000