Using the `serve` command (with examples)

This article provides code examples illustrating different use cases of the serve command, which is a static file serving and directory listing tool. Each use case is explained in detail, including the code, motivation, explanation of arguments, and example output.

Serve the current directory on the default port

The following command starts an HTTP server on the default port, serving the current directory:

serve

Motivation: This use case is useful when you simply want to serve the files in the current directory over HTTP. It can be handy for quickly sharing static files or testing web-related projects without the need for complex server setups.

Explanation:

• The serve command starts an HTTP server.
• The default behavior is to serve the current directory.
• If no additional arguments or options are provided, it listens on the default port (usually port 5000).

Example Output:

Serving! Current directory: /path/to/current/directory
Server running at http://localhost:5000

Serve a specific directory on a specific port

To serve a particular directory on a specific port, use the following command:

serve -p <port> <path/to/directory>

Motivation: This use case is helpful when you want to serve a specific directory over HTTP and specify a custom port for accessibility or to avoid conflicts with other services.

Explanation:

• The -p flag allows you to specify the port number to listen on.
• Replace <port> with the desired port number.
• Replace <path/to/directory> with the path to the directory you want to serve.

Example Output:

Serving! Current directory: /path/to/directory
Server running at http://localhost:<port>

Note: <port> will be replaced with the actual port number provided.

Enable CORS by including Access-Control-Allow-Origin header

The next example shows how to start an HTTP server with CORS enabled by including the Access-Control-Allow-Origin: * header in all responses:

serve --cors

Motivation: This use case is relevant when you want to allow cross-origin resource sharing (CORS) for the served files. CORS is necessary when accessing resources from different origins (e.g., different domains or ports) in web applications.

Explanation:

• The --cors option enables CORS support.
• It adds the Access-Control-Allow-Origin: * header to all responses.
• This header allows requests from any origin to access the served resources.

Example Output:

Serving! Current directory: /path/to/current/directory
Server running at http://localhost:5000

Rewrite not-found requests to index.html

The following example demonstrates how to start an HTTP server on the default port and rewrite all not-found requests to the index.html file:

serve --single

Motivation: This use case is useful when working with single-page applications (SPAs) that use client-side routing. By redirecting all not-found requests to the index.html file, it ensures that the SPA’s routing system handles the navigation to the correct page.

Explanation:

• The --single option enables the “single-page application” mode.
• It redirects all not-found requests to the index.html file.
• This behavior is commonly used in SPAs to handle client-side routing.

Example Output:

Serving! Current directory: /path/to/current/directory
Server running at http://localhost:5000

Start an HTTPS server with a custom SSL certificate

To start an HTTPS server on the default port using a specific SSL certificate, use the following command:

serve --ssl-cert <path/to/cert.pem> --ssl-key <path/to/key.pem>

Motivation: This use case is relevant when you need to serve the files securely over HTTPS. By providing a custom SSL certificate and private key, you can enable encryption and ensure secure communication between the server and clients.

Explanation:

• The --ssl-cert option expects the path to the SSL certificate file (cert.pem).
• The --ssl-key option expects the path to the private key file (key.pem).
• Replace <path/to/cert.pem> with the actual path to the SSL certificate file.
• Replace <path/to/key.pem> with the actual path to the private key file.

Example Output:

Serving! Current directory: /path/to/current/directory
Server running at https://localhost:5000

Use a custom configuration file

To start an HTTP server on the default port using a specific configuration file, use the following command:

serve --config <path/to/serve.json>

Motivation: This use case is useful when you have a custom configuration file (serve.json) that specifies various server settings. By using this option, you can easily load the desired configuration and start the server accordingly.

Explanation:

• The --config option expects the path to the configuration file (serve.json).
• Replace <path/to/serve.json> with the actual path to the configuration file.

Example Output:

Serving! Current directory: /path/to/current/directory
Server running at http://localhost:5000

Display help

To display the help message and learn about available options, use the following command:

serve --help

Motivation: This use case is helpful when you want to quickly refer to the command’s usage, available options, and their descriptions. The help message provides concise information about the serve command’s functionalities.

Example Output:

Usage: serve [options] [directory]

Static file serving and directory listing

Options:
  -p, --port <port>             specify the port to listen on (default: 5000)
  -C, --ssl-cert <path>         path to ssl certificate file
  -K, --ssl-key <path>          path to ssl key file
  -c, --config <path>           specify a path to a valid serve config file
  -s, --single                  rewrite all not-found requests to /index.html
  --cors                        enable CORS via the "Access-Control-Allow-Origin" header
  --help                        display help

In this article, we have covered different use cases of the serve command, including serving the current directory, specifying a custom directory or port, enabling CORS, rewriting not-found requests, setting up HTTPS, customizing with a configuration file, and accessing the help message. By understanding these various use cases and their examples, you can effectively utilize the serve command for your static file serving and directory listing needs.