serve

You can use serve without installing it by using npx, or you can install it globally to use the serve command directly in your terminal.

Note: serve v14+ requires Node v14 or higher. If you are on an older Node version, use serve v13.

The serve CLI is used for static file serving and directory listing. By default, it listens on 0.0.0.0:3000 and serves the current working directory.

Basic Usage Patterns:

• Serve the current directory: serve
• Serve a specific folder: serve folder_name
• Show help: serve --help
• Check version: serve --version

The core logic of serve is provided by serve-handler, which can be integrated into existing HTTP servers (like Node's http module or micro) as middleware.

const handler = require('serve-handler');
const http = require('http');

const server = http.createServer((request, response) => {
  // You pass two more arguments for config and middleware
  // More details here: https://github.com/vercel/serve-handler#options
  return handler(request, response);
});

server.listen(3000, () => {
  console.log('Running at http://localhost:3000');
});

By default, serve serves the current directory. You can specify a different folder to serve by passing the folder name as an argument.

serve folder-name/

The following environment variables affect the serve CLI behavior:

• PORT: Sets the default port if no --listen argument is provided. Defaults to 3000 if not set.
• NODE_ENV: If set to production, the CLI will suppress the interactive 'fancy box' output and instead print a single line of text for the server address to stdout.

The --listen (or -l) option allows you to specify one or more interfaces, ports, UNIX domain sockets, or Windows named pipes. Specifying multiple --listen arguments allows the server to listen in multiple places simultaneously.

Supported Endpoint Formats:

• Port number only (defaults to localhost): serve -l 1234
• TCP (host:port): serve -l tcp://hostname:1234
• UNIX domain socket: serve -l unix:/path/to/socket.sock
• Windows named pipe: serve -l pipe:\\.\pipe\PipeName

The following CLI flags are available to control the behavior of the serve command:

• --help: Displays the help text and exits.
• --version: Displays the current version of the package and exits.
• --listen <port>: Specifies the port(s) to listen on. (Note: The implementation expects a specific format, typically used via the internal parser).
• --single: Enables Single Page Application (SPA) mode by rewriting all requests to /index.html as the highest priority rule.
• --no-clipboard: Disables the automatic copying of the local server address to the clipboard.
• --debug: Enables debug logging for errors (e.g., when checking for updates).

The startServer function accepts an args object (of type Partial<Options>) that mimics CLI flags to toggle specific features: