Programmatic Usage with serve-handler

The core of the serve CLI is a separate, powerful package called serve-handler. You can use this handler directly as middleware in your own Node.js HTTP servers, giving you the full power of serve within a custom application.

This is useful when you need to add custom server-side logic, API routes, or WebSocket connections alongside your static file serving.

Basic Example

Here's how you can use serve-handler with Node's built-in http module:

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

const server = http.createServer((request, response) => {
  // You can pass a configuration object to the handler.
  // See https://github.com/vercel/serve-handler#options for all options.
  return handler(request, response, {
    "public": "my-app"
  });
});

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

In this example, we create a standard Node.js HTTP server. For every incoming request, we pass the request and response objects to serve-handler.

The third argument to handler is a configuration object that accepts all the same properties as a serve.json file (e.g., public, rewrites, headers).

Integrating with Other Frameworks

serve-handler is compatible with any framework that follows the standard (request, response) signature for request listeners, including popular choices like micro.

Example with Custom Routing

If you want to handle certain routes yourself (e.g., for an API) and let serve-handler manage everything else, you can add conditional logic to your server.

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

const server = http.createServer(async (request, response) => {
  // Handle API routes
  if (request.url.startsWith('/api')) {
    response.setHeader('Content-Type', 'application/json');
    response.end(JSON.stringify({ message: 'Hello from the API!' }));
    return;
  }

  // Let serve-handler take care of the rest
  await handler(request, response, {
    public: 'public'
  });
});

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

For a complete list of all configuration options available, please refer to the official serve-handler documentation.