serve-handler

serve-handler

This package represents the core of serve and static deployments running on Now. It can be plugged into any HTTP server and is responsible for routing requests and handling responses.

In order to customize the default behaviour, you can also pass custom routing rules, provide your own methods for interacting with the file system and much more.

Usage

Get started by installing the package using yarn:

yarn add serve-handler

You can also use npm instead, if you'd like:

npm install serve-handler

Next, add it to your HTTP server. Here's an example with micro:

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

module.exports = async (request, response) => {
  await handler(request, response);
};

That's it! :tada:

Options

If you want to customize the package's default behaviour, you can use the third argument of the function call to pass any of the configuration options listed below. Here's an example:

await handler(request, response, {
  cleanUrls: true
});

You can use any of the following options:

• public (set sub directory to serve)
• cleanUrls (strip .html and .htm from paths)
• rewrites (rewrite paths to different paths)
• redirects (forward paths to different paths or URLs)
• headers (set custom headers)
• directoryListing (disable directory listing or restrict it to certain paths)
• unlisted (exclude paths from the directory listing)
• trailingSlash (remove or add trailing slashes to all paths)

public (Boolean)

By default, the current working directory will be served. If you only want to serve a specific path, you can use this options to pass a custom directory to be served relative to the current working directory.

For example, if serving a Jekyll app, it would look like this:

{
  "public": "_site"
}

cleanUrls (Boolean|Array)

Assuming this is true, all .html and .htm files can be accessed without their extension (shown below).

If one of these extensions is used at the end of a filename, it will automatically perform a redirect with status code 301 to the same path, but with the extension dropped.

{
  "cleanUrls": true
}

However, you can also restrict this behavior to certain paths:

{
  "cleanUrls": [
    "/app/**",
    "/!components/**"
  ]
}

rewrites (Array)

If you want your visitors to receive a response under a certain path, but actually serve a completely different one behind the curtains, this option is what you need.

It's perfect for single page applications (SPAs), for example:

{
  "rewrites": [
    { "source": "app/**", "destination": "/index.html" },
    { "source": "projects/*/edit", "destination": "/edit-project.html" }
  ]
}

You can also use so-called "routing segments" as follows:

{
  "rewrites": [
    { "source": "/projects/:id/edit", "destination": "/edit-project-:id.html" },
  ]
}

Now, if a visitor accesses /projects/123/edit, it will respond with the file /edit-project-123.html.

redirects (Array)

In order to redirect visits to a certain path to a different one (or even an external URL), you can use this option:

{
  "redirects": [
    { "source": "/from", "destination": "/to" },
    { "source": "/old-pages/**", "destination": "/home" }
  ]
}

By default, all of them are performed with the status code 301, but this behavior can be adjusted by setting the type property directly on the object (see below).

Just like with rewrites, you can also use routing segments:

{
  "redirects": [
    { "source": "/old-docs/:id", "destination": "/new-docs/:id" },
    { "source": "/old", "destination": "/new", "type": 302 }
  ]
}

In the example above, /old-docs/12 would be forwarded to /new-docs/12 with status code 301. In addition /old would be forwarded to /new with status code 302.

headers (Array)

Allows you to set custom headers (and overwrite the default ones) for certain paths:

{
  "headers": [
    {
      "source" : "**/*.@(jpg|jpeg|gif|png)",
      "headers" : [{
        "key" : "Cache-Control",
        "value" : "max-age=7200"
      }]
    }, {
      "source" : "404.html",
      "headers" : [{
        "key" : "Cache-Control",
        "value" : "max-age=300"
      }]
    }]
  }
}

directoryListing (Boolean|Array)

For paths are not files, but directories, the package will automatically render a good-looking list of all the files and directories contained inside that directory.

If you'd like to disable this for all paths, set this option to false. Furthermore, you can also restrict it to certain directory paths if you want:

{
  "directoryListing": [
    "/assets/**",
    "/!assets/private"
  ]
}

unlisted (Array)

In certain cases, you might not want a file or directory to appear in the directory listing. In these situations, there are two ways of solving this problem.

Either you disable the directory listing entirely (like shown here), or you exclude certain paths from those listings by adding them all to this config property.

{
  "unlisted": [
    ".DS_Store",
    ".git"
  ]
}

The items shown above are excluded from the directory listing by default.

trailingSlash (Boolean)

By default, the package will try to make assumptions for when to add trailing slashes to your URLs or not. If you want to remove them, set this property to false and true if you want to force them on all URLs:

{
  "trailingSlash": true
}

With the above config, a request to /test would now result in a 301 redirect to /test/.

Middleware

If you want to replace the methods the package is using for interacting with the file system, you can pass them as the fourth argument to the function call.

This comes in handy if you're dealing with simulating a file system, for example.

These are the methods used by the package (they can all return a Promise or be asynchronous):

await handler(request, response, undefined, {
  stat(path) {},
  createReadStream(path) {},
  readdir(path) {}
});

Real-World Use Cases

There are two environments in which ZEIT uses this package:

Development

When running static applications or sites on your local device, we suggest using serve.

Since it comes with support for serve-handler out of the box, you can create a serve.json file to customize its behavior. It will also read the configuration from static inside now.json.

Production

When deploying your site to Now, both the serve.json file or the static property inside now.json will be parsed and used to handle requests on the platform.

Author

Leo Lamprecht (@notquiteleo) - ZEIT