0
# Live Server
1

2
Live Server is a development HTTP server with automatic live reload functionality for front-end web development. It serves static files from a directory and automatically refreshes the browser when files change, eliminating the need for manual page refreshes during development.
3

4
## Package Information
5

6
- **Package Name**: live-server
7
- **Package Type**: npm  
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g live-server` (recommended global installation)
10
- **Node.js Support**: >=0.10.0
11

12
## Core Imports
13

14
For programmatic use in Node.js:
15

16
```javascript
17
const liveServer = require("live-server");
18
```
19

20
For ES modules:
21

22
```javascript
23
import liveServer from "live-server";
24
```
25

26
## Basic Usage
27

28
### Command Line Usage
29

30
```bash
31
# Serve current directory
32
live-server
33

34
# Serve specific directory  
35
live-server /path/to/your/project
36

37
# Serve with custom port
38
live-server --port=3000
39

40
# Serve with HTTPS
41
live-server --https=path/to/https-config.js
42
```
43

44
### Node.js API Usage
45

46
```javascript
47
const liveServer = require("live-server");
48

49
// Start server with default options
50
liveServer.start();
51

52
// Start with custom configuration
53
liveServer.start({
54
  port: 8181,
55
  host: "0.0.0.0", 
56
  root: "/public",
57
  open: false,
58
  file: "index.html",
59
  wait: 1000
60
});
61

62
// Stop the server
63
liveServer.shutdown();
64
```
65

66
## Architecture
67

68
Live Server consists of several key components:
69

70
- **HTTP/HTTPS Server**: Built on Node.js `http`/`https` modules with Connect middleware stack
71
- **File Watcher**: Uses Chokidar for efficient file system monitoring
72
- **WebSocket Communication**: Faye-WebSocket for real-time browser-server communication  
73
- **Code Injection**: Automatically injects WebSocket client code into HTML files
74
- **Static File Server**: Custom static server with live reload integration
75
- **Middleware System**: Connect-compatible middleware support for extensibility
76

77
The live reload mechanism works by:
78
1. Watching for file changes using Chokidar
79
2. Injecting WebSocket client code into served HTML files
80
3. Sending reload/refresh messages to connected browsers via WebSocket
81
4. Handling CSS updates without full page reload when possible
82

83
## Capabilities
84

85
### Command Line Interface
86

87
Complete command-line tool for quick development server setup with extensive configuration options including port, host, HTTPS, authentication, proxying, and SPA support.
88

89
```bash { .api }
90
live-server [PATH] [OPTIONS]
91

92
# Core options
93
--port=NUMBER          # Port to use (default: 8080)
94
--host=ADDRESS         # Host address (default: 0.0.0.0)  
95
--open=PATH            # Browser path to open (default: server root)
96
--no-browser           # Suppress browser launch
97

98
# File handling
99
--watch=PATH           # Paths to watch (comma-separated)
100
--ignore=PATH          # Paths to ignore (comma-separated)
101
--entry-file=PATH      # Entry file for SPA routing
102

103
# Advanced features  
104
--https=PATH           # HTTPS configuration
105
--cors                 # Enable CORS
106
--htpasswd=PATH        # HTTP Basic authentication
107
--proxy=ROUTE:URL      # Proxy configuration
108
--middleware=PATH      # Custom middleware
109
--spa                  # Single Page App mode
110
```
111

112
[Command Line Interface](./cli.md)
113

114
### Node.js Programmatic API
115

116
Programmatic interface for integrating live server functionality into build tools, development environments, and custom applications.
117

118
```javascript { .api }
119
// Main API methods
120
liveServer.start(options?: LiveServerOptions): http.Server | https.Server;
121
liveServer.shutdown(): void;
122

123
// Configuration interface
124
interface LiveServerOptions {
125
  host?: string;           // Address to bind (default: '0.0.0.0')
126
  port?: number;           // Port number (default: 8080, 0 = random)
127
  root?: string;           // Root directory (default: process.cwd())
128
  open?: string | string[] | boolean; // Browser launch config
129
  file?: string;           // Entry point file for SPA
130
  wait?: number;           // Reload delay in ms (default: 100)
131
  logLevel?: number;       // 0=errors, 1=some, 2=lots (default: 2)
132
  
133
  // File watching
134
  watch?: string[];        // Paths to watch exclusively  
135
  ignore?: string[];       // Paths to ignore
136
  ignorePattern?: RegExp;  // Ignore pattern (deprecated)
137
  
138
  // Features
139
  cors?: boolean;          // Enable CORS
140
  noCssInject?: boolean;   // Disable CSS injection
141
  spa?: boolean;           // Enable SPA mode
142
  
143
  // Authentication & Security
144
  htpasswd?: string;       // Path to htpasswd file
145
  https?: string | object; // HTTPS configuration
146
  httpsModule?: string;    // Custom HTTPS module
147
  
148
  // Middleware & Proxying  
149
  middleware?: (string | Function)[]; // Connect middleware
150
  mount?: [string, string][]; // Mount point mappings
151
  proxy?: [string, string][]; // Proxy configurations
152
  
153
  // Legacy options
154
  browser?: string;        // Browser to launch
155
  noBrowser?: boolean;     // Deprecated: use open: false
156
}
157
```
158

159
[Node.js API](./nodejs-api.md)
160

161
## Types
162

163
```javascript { .api }
164
// Server instance (return type of liveServer.start())
165
interface LiveServerInstance extends http.Server {
166
  // Standard Node.js HTTP server with additional live server functionality
167
}
168

169
// Main LiveServer object structure
170
interface LiveServer {
171
  server: http.Server | https.Server | null;
172
  watcher: object | null; // Chokidar watcher instance  
173
  logLevel: number;
174
  start(options?: LiveServerOptions): http.Server | https.Server;
175
  shutdown(): void;
176
}
177
```