Routes

Now uses routes to define the behavior of how a request is handled on the routing side. For example, you might use a route to rewrite a URL to another, redirect a user, or apply a header with the response to a request.

A route can be defined within a project's now.json configuration file as an object within an array assigned to the routes property, like the following which creates a simple rewrite from one path to another:

{
  "version": 2,
  "routes": [{ "src": "/about", "dest": "/about.html" }]
}

An example now.json file with a routes property that rewrites one path to another upon request.

Routes Properties

Now Routes has multiple properties for each route object that help define the behavior of a response to each request to a particular path.

src

Type: String supporting PCRE Regex and Route Parameters like /product/(?<id>[^/]+).

For each route, src is required to set the path which the behavior will affect.

The following example shows a now.json configuration that takes a src path and rewrites it to a destination dest path.

{
  "version": 2,
  "routes": [{ "src": "/about", "dest": "/about.html" }]
}

An example now.json file with a routes property that rewrites one path to another upon request.

dest

Type: String

dest is used to rewrite the src path to another path.

The example for the src property shows how both methods work together to create a rewrite.

{
  "version": 2,
  "routes": [{ "src": "/about", "dest": "https://about.me" }]
}

An example now.json file with a routes property that rewrites one path to another upon request.

Note: You can point the dest path to any URL, including non-Now hosted URLs as shown in the code below.

headers

Type: Object

The headers property is an object supporting HTTP headers as the keys, with the intended value as the key's value.

An example of using the headers property to add shared caching headers to all files in an images directory:

{
  "version": 2,
  "routes": [
    { "src": "/images/.+", "headers": { "cache-control": "s-maxage=604800" } }
  ]
}

Setting cache-control headers for all paths under an images directory with routes.

status

Type: Integer

The status property defines the status code that Now should respond with when a path is requested.

For example, you can use this property in combinations with the headers property to create a redirect with the initial status code of 301 (Moved Permanently).

{
  "version": 2,
  "routes": [
    {
      "src": "/about.html",
      "status": 301,
      "headers": { "Location": "/about-us.html" }
    }
  ]
}

Redirecting one path to another using the status property to provide a HTTP status code.

Note: In a redirect case as shown above, the Location property can also point to non-Now hosted URLs.

Read more about redirecting your www. subdomain to your root domain:

methods

Type: Array

The methods property can be used to define what HTTP request methods a particular path accepts.

The value of this property can be any HTTP request method, with the default being that the path can accept any method.

As an example, you can use this property when you have an API endpoint and only want to allow GET or POST request methods:

{
  "version": 2,
  "routes": [{ "src": "/api/user.js", "methods": ["POST", "GET"] }],
  "builds": [{ "src": "*.js", "use": "@now/node" }]
}

Accepting only POST and GET HTTP request methods on an API endpoint.

Note: The above example uses the @now/node Builder as an example of a now.json configuration that tells Now to build JavaScript files with Node.js and outputs them as lambdas.

Route Parameters

Using PCRE Named Subpatterns, or capture groups, you can capture part of a path and use it in either the dest or headers properties.

Using route parameters enables you to change the format of your URLs easily without needing complicated routing code.

For example, if you are using URL parameters but want to use a custom URL path you can use the following:

{
  "version": 2,
  "routes": [{ "src": "/product/(?<id>[^/]+)", "dest": "/product?id=$id" }]
}

Using a URL parameter in src and rewriting it as a custom URL path in dest.

This will take a URL, like /product/532004 and rewrites it to /product?id=532004 with the user seeing your custom URL in their browser.

Note: Both ^, asserting the start of the path string, and $, asserting the end of the path string, are implied and are not necessary to write.

As another example, if you want to redirect from all paths under a certain directory but want to keep the path in the new location, you can use the following:

{
  "version": 2,
  "routes": [
    {
      "src": "/posts/(.*)",
      "status": 301,
      "headers": { "Location": "/blog/$1" }
    }
  ]
}

Redirecting from all paths in the posts directory but keeping the path in the new location.

If you are using a Next.js app and want to learn more about using custom routes with Now, read our guide:

Testing Routes

You can use this online visual PCRE tester to quickly test your src paths before deploying them to Now.

An interactive PCRE Regex cheatsheet is also available at Debuggex.

Cascading Order

Routes are applied in the order they are given in the routes array. Take the following configuration, for example:

{
  ...
  "routes": [
    { "src": "/(.*)", "dest": "/" },
    { "src": "/first-page", "dest": "/first-page.html" }
  ]
}

An incorrect example now.json file that will match allroutes and rewrite them to /

In this configuration, since the first route matches all possible paths, the second route will never be applied. The order of these routes would have to switch for the latter route to apply to the /first-page path.

The correct configuration for all routes to take affect would be:

{
  ...
  "routes": [
    { "src": "/first-page", "dest": "/first-page.html" },
    { "src": "/(.*)", "dest": "/" }
  ]
}

A correct example now.json file that will match allroutes, only rewriting to / if there are no matches.

This type of configuration can be seen in single-page applications where custom paths need to route to the index.html file.

Read More

See more documentation or guides to help you get where you want: