Docs

File System APIBeta

A reference of the .output directory consumed by Vercel's Build Step with every Deployment, which is expected to contain your app's compiled code and instructions for how to serve it to visitors.

As a beta feature, the File System API requires an Environment Variable named ENABLE_FILE_SYSTEM_API to be set to 1 in order to function.

How does it work?

Whenever a new Deployment is created on Vercel, its source files will be retrieved from their origin location (a Git repository, for example) and processed within the Build Step, after which they are made available on the Edge Network.

Inside of this Build Step, the vercel build command provided by Vercel CLI is automatically invoked, which will retrieve the Project Settings and invoke the Build Command specified for the Project. This will make the respective Framework transform the source code and prepare it for delivery.

Afterwards, vercel build will handle features natively provided by Vercel (such as Node.js Serverless Functions in the api directory or _middleware.js) and produce several files that it combines with the files produced by the Project's Build Command.

The outcome of this process is a .output directory that is passed on to the File System API at the end of the Build Step, containing instructions of which files to deliver to visitors and their respective configuration manifests.

When should I use it?

Most commonly, the File System API is not something you need to worry about.

Frameworks that support Vercel without any additional configuration (like Next.js, Nuxt, or SvelteKit) are automatically producing a .output directory that instructs the platform how to behave. They pass on all of the resources created within your source code (such as Pages or API Routes).

If you are a framework author looking to integrate with Vercel, you can use this reference as a way to understand which files you would want to create within the .output directory, for the platform to understand them.

Additionally, if you are not using a framework and would like to still take advantage of any of the features that those frameworks provide, you can create the directory yourself, using a custom command-line interface or by including it in your source files.

Resources

Relevant Directories:

.output/server/pages
.output/server/pages/api
.output/static

If you'd like to expose resources to your visitors once the Deployment has finished, it is required to place them inside one of the directories mentioned below. Files outside of these directories are ignored and will not be served to visitors.

Pages

Relevant Directory: .output/server/pages

Regardless of whether the Pages you'd like to serve to your visitors are generated on-demand (whenever a request arrives) or statically generated ahead of time, including them as part of your Deployment can be done by creating a single file for every page, and Vercel will handle the rest for you.

More specifically, you can place the source of Pages that you have statically generated ahead of time in the form of HTML files in the directory shown above and they will automatically be served at the root of the URL of your Deployment.

The same is the case for Pages that you would like to generate on-demand using Server-Side Rendering: Place a Node.js Function in the directory and it will be invoked whenever a request arrives for the path defined in its file name.

In favor of performance, it is recommended to statically generate Pages ahead of time as much as possible. If the need for dynamism arises, feel free to switch to Page Functions and ideally even enable Pre-Rendering, to retain as much performance as possible.

Exposed Files

All files within the pages directory are considered files that should be mounted to the URL of the Deployment. If your Functions depend on other files, they have to be included via the Bundling Configuration and placed outside of pages (in a different arbitrary directory at the root of .output, for example).

It is recommended to leave the bundling of files to Vercel if a file is used by multiple Functions. If a file is only used by a single Function, you may combine those files into a single Function based on your own choosing.

The extensions of the files within the pages directory are automatically stripped before the Pages are made available in the URL of the Deployment, under the same name that was used for the file. This happens regardless of which extension was used.

If files are placed in sub directories within pages, those will become part of the URL too, and be included before the page name.

Custom Runtimes

By default, only files with the extensions .html (statically generated ahead of time) and .js (Node.js Function, so generated on-demand with every incoming request) may be placed inside of the pages directory.

If you would like to provide Page Functions that use a different runtime than Node.js, you can do so using the Function Configuration, which also includes other options.

Example

If you were to add file named about.html inside of the pages directory, it will be served at /about in the URLs assigned to your Deployment.

Respectively, if you were to place a file named blog.js inside of the directory, it will be served at /blog and the Function contained inside of the file will be invoked whenever a request arrives for that URL path.

Placing a file in test/about.html would mount it to /test/about in the URL.

This is what the directory could look like in a real scenario (you can learn more about the purpose of the .nft.json file in Exposed Files above):

Static Files

Relevant Directory: .output/static

If you would like to provide static files that should be served without any transformation as part of your Deployment, you can do so by including them in this directory.

The files will be made available at the root (/) of the Deployment's URL and neither their contents, nor their file name or extension will be mutated in any way. Sub directories within static are also retained in the URL, and are appended before the file name.

If a Page or API Route with the same name in the final URL exists, they will be overwritten by the Static File and therefore won't be accessible through the URL anymore.

Usage Exceptions

It is therefore recommended to use this directory for files that are not directly accessed by visitors, but instead loaded on Pages (like client-side JavaScript bundles) or accessed by machines (like robots.txt). Files that are directly accessed by visitors are considered Pages and shouldn't be placed here.

Since all of the files in this directory are exposed as part of the Deployment's URL, you also shouldn't use it for files that your Page or API Route Functions might depend on for execution. Those can be included via Bundling Configuration instead.

Example

This is what the directory could look like in a real scenario:

API Routes

Relevant Directory: .output/server/pages/api

If one of your Pages relies on data that should be delivered from, or to the client-side (the browser), you can use this directory to include API Routes as part of your Deployment that will send and accept this data.

They can also be helpful in scenarios where third-parties or other types of clients (like native mobile apps) wish to access this data, or any other types of actions that have to be performed that were triggered by a visitor.

API Routes are designed to be accessed by Pages or machines, but not by humans. If you'd like to display something to visitors, create a Page instead.

Under the hood, like on-demand Pages, API Routes are powered by Functions.

When it comes to the files in the directory that are exposed in the Deployment's URL and custom runtimes, API Routes behave like Pages. Otherwise, they are completely separate concepts and should be separated distinctively.

Example

This is what the directory could look like in a real scenario:

Middleware

Relevant Directory: .output/server/pages

Generating Pages on-demand using Serverless Functions bears a significant performance drawback, because their HTML markup has to be generated again for every incoming request, which is slower than delivering HTML that was statically generated ahead of time.

Even if your Page returns the Cache-Control header and its responses are cached on Vercel's Edge Network, the first request per region would still be slow, which means that the first visitor in a certain region would see a slower response.

Performance Implications

Thankfully, however, Vercel offers two different types of Functions: Serverless Functions and Edge Functions. The former are the traditional kind powered by Lambdas, whereas the latter runs directly on the Edge Network and can respond much quicker.

You can place Middleware in .output/server/pages, and it sits between the client (the browser), and a Page or API Route. This means you can statically generate those ahead of time or cache their responses on the Edge Network, while still executing code on every request.

Because Middleware has almost no noticable impact on performance, it is run on every request and can perform lightweight operations such as forwarding visitors to a different URL, resolving to a different URL, or performing any sort of validation.

Exposed Files

Unlike all other Resources, Middleware requires Function Configuration to work, as it determines the URL paths that the Middleware should be responsible for. For the other Resources, this is inferred based on the location and name of the files.

Middleware files are never directly exposed as part of the Deployment's URL. Instead, based on their configuration, they are made available on existing URL paths that resolve to Pages or API Routes, which is the part that makes them the "middle-ware".

Custom Runtime

Currently, only JavaScript (invoked by V8) is supported as a runtime for Middleware.

Example

This is what the directory could look like in a real scenario:

For the above example, you could place the following in functions-manifest.json:

{
  "version": 1,
  "pages": {
    "_middleware.js": {
      "runtime": "web",
      "env": [],
      "files": ["server/pages/_middleware.js"],
      "name": "pages/_middleware",
      "page": "/",
      "regexp": "^/.*$",
      "sortingIndex": 1
    }
  }
}

Additionally, this is what you could place in _middleware.js:

const getResult = (body, options) => ({
  promise: Promise.resolve(),
  waitUntil: Promise.resolve(),
  response: new Response(body, options),
});

_ENTRIES = typeof _ENTRIES === 'undefined' ? {} : _ENTRIES;

_ENTRIES['middleware_pages/_middleware'] = {
  default: async function ({ request }) {
    // Body
    if (request.url.endsWith('/middleware-body')) {
      return getResult('hi from the edge', {});
    }

    // Rewrite
    if (request.url.endsWith('/middleware-rewrite')) {
      return getResult(null, {
        headers: {
          'x-middleware-rewrite': '/blog',
        },
      });
    }

    // Redirect
    if (request.url.endsWith('/middleware-redirect')) {
      return getResult(null, {
        status: 308,
        headers: {
          Location: '/blog',
          'x-middleware-redirect': '/blog',
        },
      });
    }

    // Don't do anything
    return getResult(null, {
      headers: {
        'x-middleware-next': '1',
      },
    });
  },
};

Configuration

Relevant Files:

.output/routes-manifest.json
.output/functions-manifest.json
.output/server/pages/**/[function].nft.json
.output/images-manifest.json
.output/prerender-manifest.json
.output/build-manifest.json

If you would like to customize the behavior of any of the Resources you have provided with your Deployment, or control Vercel's behavior in general, you can provide several optional configuration files within the .output directory.

Routes

Relevant File: .output/routes-manifest.json

If you'd like to point certain URL paths to others on your Deployment or attach headers to some of them, you can do so using this configuration file.

You can forward visitors to different URLs (if you've changed the URL of a blog post, for example), change the URL that is displayed for them (if you'd like multiple URLs to resolve to a single one, for example), or customize the behavior of the client that sent the request through headers.

Supported Properties

The following configuration properties are allowed within the configuration file:

Key
Required
Description
version
Yes
The version of the configuration that should be used. The most recent one for this file is currently 3.
basePath
Yes
A path that is prepended to all Routes and Routes. For example, you might want to mount your entire application to /something.
pages404
Yes
Whether or not a Page named 404 (can be HTML or a Function) should be served if a path isn't found for an incoming request.
redirects
No
A list of Maps for forwarding requests from one URL path to another, whose properties are described below.
headers
No
A list of Maps for returning headers for certain URL paths, whose properties are described below.
rewrites
No
A list of Maps for ensuring that certain URL paths resolve to other URLs, whose properties are described below.
dynamicRoutes
No
A list of Maps that describe Pages or API Routes that include path segments (like blog/[slug]) and therefore result in rewrites, whose properties are described below.

Within redirects, every Map can contain the following properties:

Key
Required
Description
source
Yes
The URL path on which the redirect will be made available.
destination
Yes
The URL path to which the visitor should be redirected.
statusCode
Yes
The HTTP status code that should be returned as part of the response for redirecting the visitor. Possible values are either 301, 302, 307, or 308. The last two are recommended, while the first two should ideally only be used for backwards-compatibility with legacy clients (e.g. browsers).
regex
Yes
A regular expression describing the URL path on which the redirect should be served. While source is only a String representation of the path, regex is the value that is used for actually validating whether the redirect should apply to an incoming request, or not.

Within headers, every Map can contain the following properties:

Key
Required
Description
source
Yes
The URL path on which the headers will be made available.
headers
Yes
A list of Maps containing headers that should be returned from URL paths that match regex, where key is a String containing the name of the header, and value is a String containing its respective value.
regex
Yes
A regular expression describing the URL path on which the headers should be served. While source is only a String representation of the path, regex is the value that is used for actually validating whether the headers should apply to an incoming request, or not.

Within rewrites, every Map can contain the following properties:

Key
Required
Description
source
Yes
The URL path on which the rewrite will be made available.
has
No
A list of Maps containing rules that the incoming request has to match before the rewrite applies. Within them, type is an Enum with header, cookie, host or query as the value, key is a String containing the respective key that should be asserted, and value is the same, but for the value that should be asserted.
destination
Yes
The URL path that should be served to the visitor when a URL path that matches regex is accessed.
regex
Yes
A regular expression describing the URL path on which the rewrite should be served. While source is only a String representation of the path, regex is the value that is used for actually validating whether the rewrite should apply to an incoming request, or not.

Within dynamicRoutes, every Map can contain the following properties:

Key
Required
Description
page
Yes
The name (in the same format as used in Function Configuration) of the Page or API Route that should receive the incoming request if its URL matches the pattern provided in regex.
regex
Yes
A regular expression describing the URL path on which the Page or API Route should be served.
routeKeys
No
Query string parameters that should be passed to the destination Page or API Route, where every key is the segment in namedRegex that should be captured and every value is the name of the query string parameter that should receive its value.
namedRegex
No
A regular expression describing the URL path on which the Page or API Route should be served. The difference to regex is that this property can contain path segments (like <post>) that will automatically be transformed into query string parameters using routeKeys.

Example

This is what the configuration file could look like in a real scenario:

{
  "version": 3,
  "basePath": "",
  "pages404": true,
  "redirects": [
    {
      "source": "/nice/",
      "destination": "/stuff",
      "statusCode": 308,
      "regex": "^/nice.*$"
    }
  ],
  "headers": [
    {
      "source": "/",
      "headers": [
        {
          "key": "x-custom-header",
          "value": "my custom header value"
        }
      ],
      "regex": "^.*$"
    }
  ],
  "rewrites": [
    {
      "source": "/admin",
      "has": [
        {
          "type": "cookie",
          "key": "authorized",
          "value": "true"
        }
      ],
      "destination": "/secret",
      "regex": "^/admin.*$"
    }
  ],
  "dynamicRoutes": [
    {
      "page": "/blog/[post]",
      "regex": "^/blog/([^/]+?)(?:/)?$",
      "routeKeys": {
        "post": "post"
      },
      "namedRegex": "^/blog/(?<post>[^/]+?)(?:/)?$"
    }
  ]
}

Functions

Relevant File: .output/functions-manifest.json

If you have provided on-demand Pages or API Routes as part of your Deployment, you might find yourself needing to customize their behavior on Vercel.

With this configuration file, you can customize the memory size of their underlying Functions, which region on the Edge Network they are deployed to, and how long they should be able to run.

Additionally, it allows for customizing which runtime should be used for those Functions in cases where you would like to run your code in a non-Node.js Environment. This means that on-demand Pages and API Routes can be written in any language.

Before configuring the Functions created in your Deployment, it is recommended to first learn about the conceptual models for Serverless Functions and Edge Functons (depending on which ones you'd like to use), as it will help you make the right decisions while customizing their default behavior along the way.

Supported Properties

The following configuration properties are allowed within the configuration file:

Key
Required
Description
version
Yes
The version of the configuration that should be used. The most recent one for this file is currently 1.
pages
Yes
A map of on-demand Pages (Functions), API Routes or Middlewares and the respective configuration properties for each one. The keys are Strings containing the names of the Functions, without their extensions. The values are Maps, whose properties are described below.

Within pages, every key can have the following Map as its value:

Key
Required
Description
memory
No
How much memory (in MB) should be made available to the Function. Only Integers between 128 and 3008 in intervals of 64 are allowed. The CPU configuration will scale linearly in proportion to the memory configuration (at 1792 MB memory, for example, a Function has the equivalent of one full vCPU).
maxDuration
No
How long the Function should be allowed to run for every request in seconds. Only Integers between 1 and the Serverless Function Execution Timeout limit of your plan are allowed. It is recommended to use a small value, as larger values will keep visitors waiting for longer.
regions
No
The regions on our Edge Network that the Function should be deployed to. It is recommended to keep your Functions close to your visitors, but also close to your data source, to keep latency for both at a minimum.
runtime
No
The identifier of the Lambda runtime that you'd like to use for your Function. Defaults to the Node.js Version configured in the Project Settings. If this property is used, handler is required alongside it. It can also be web if you'd like to deploy an Edge Function (does not require handler).
handler
No
The name of the file that should be invoked by the Lambda runtime defined above whenever a request arrives.

Additionally, the Map mentioned above should contain the following properties if runtime is web and the respective Function is used as Middleware (if it's not used as Middleware and runtime is still web, the properties are optional):

Key
Required
Description
env
Yes
A list of Strings that represent the names of Environment Variables that should be retrieved from the Project Settings and made available to the code at execution time with their values.
files
Yes
A list of Strings that represent source files that are relevant for the Middleware. It has to contain at least one item that matches the name property. Any additional entry will be concatenated (learn more about Edge Function Bundling) together with the contents of the file present at this path. All paths have to begin with server/.
name
Yes
The path of the respective Middleware file that the configuration Map is responsible for. It is required to begin with pages/ and end in _middleware.
page
Yes
The path in the URL for which the respective Middleware file is responsible. If it's responsible for multiple sub paths, you don't need to consider those here – only their parent path.
regexp
Yes
A regular expression describing the URL path for which the respective Middleware file is responsible. This value is considered every time a request arrives, to determine whether to execute the Middleware, or not.
sortingIndex
Yes
If multiple Middlewares were defined for the same path, this value defines in which order they should be executed.

Example

This is what the configuration file could look like in a real scenario:

{
  "version": 1,
  "pages": {
    "my-page.js": {
      "memory": 128,
      "maxDuration": 3,
      "regions": ["hkg1"]
    },
    "api/date.go": {
      "runtime": "go1.x",
      "handler": "my-go-api.bin"
    },
    "api/hello.js": {
      "runtime": "web"
    },
    "_middleware.js": {
      "runtime": "web",
      "env": [],
      "files": ["server/pages/_middleware.js"],
      "name": "pages/_middleware",
      "page": "/",
      "regexp": "^/.*$",
      "sortingIndex": 1
    }
  }
}

Bundling

Relevant File: .output/server/pages/**/[function].nft.json

If you are expecting scenarios in which multiple Pages or API Routes are making use of the same code for their Functions (which might apply for utility files), you can inform Vercel about those files, so that it can automatically determine the most efficient way to make the files available where needed.

Instead of having to ensure that every Page and API Route Function includes all of the code it requires for being able to run, you can inform the platform which Functions depend on which files, instead of copying code into multiple places (which increases disk usage in the final Function). Vercel can then automatically figure out the most efficient placement for these files.

The configuration file can be placed alongside Pages and API Routes on any level within pages, and [path] in the configuration file name (see the "Relevant File" example above) has to match them. The dependency files of your Functions can be placed inside of the .output/inputs directory.

Edge Functions

In the case that the runtime property of a Function is set to web using Function Configuration, it is considered an Edge Function and will not be able to make use of the .nft.json configuration standard for bundling files.

Instead, the files property in the respective Function Configuration entry can be used to inform the platform which files the Edge Function might depend on, so that multiple Edge Functions can make use of the same shared source code files, if needed.

As mentioned in Function Configuration, the first entry of files is required to be the Edge Function's entrypoint file, but all other items in the List will have their file contents appended to the entrypoint file.

Note that the _ENTRIES property within the entrypoint file will not receive additional properties. Instead, the entrypoint file and the other files are joined together as strings and create a new entrypoint file.

If multiple Edge Functions are making use of the same source code, use this property to help Vercel understand which Edge Function depends on which files, so that it can apply smart and efficient bundling, just like for Serverless Functions.

Supported Properties

The following configuration properties are allowed within the configuration file:

Key
Required
Description
version
Yes
The version of the configuration that should be used. The most recent one for this file is currently 1.
files
Yes
A list of Strings representing the paths that a Page and API Route Function might depend on, relative to their location. If a list of Maps is used instead, this is reflected in their input properties, and their output properties would be the paths within the final Lambda to which the files should be mounted (relative to the root). Only use Maps if necessary.

Example

If a Page were to be located at pages/about.js, its respective configuration file for bundling would be located at pages/about.nft.json.

If your application contains dependencies within a node_modules directory which multiple Functions need to access, you don't need to copy those dependencies into multiple places. Instead, Vercel will automatically bundle the files in a smart way, so that disk usage of the final Functions is kept to a minimum.

This is what the configuration file could look like in a real scenario:

{
  "version": 1,
  "files": [
    {
      "input": "../../../data.txt",
      "output": "my-folder/data.txt"
    }
  ]
}

Images

Relevant File: .output/images-manifest.json

If you would like to provide images as part of your Deployment ahead of time, you can include them as Static Files. Those images will be made available without modifications on your Deployment's URL, so you can load them from anywhere (like your frontend).

For optimital performance, however, it is recommended to load your images through Vercel's native Image Optimization endpoint, which automatically adjusts the size and quality of your images, to make sure they are served to your visitors as quickly as possible.

HTTP Endpoint

The endpoint is available at the /_vercel/image path of the respective Deployment and accepts the following query string parameters:

Key
Required
Description
url
Yes
The URL of the image that should be optimized (like /static/image.png). If it's an external URL, its domain must be included as part of domains in the configuration file.
w
Yes
The width that the image should be resized to (like 200). Only the Integer passed through sizes in the images configuration property are allowed as the value.
q
No
The quality level that the image should be reduced to (like 70). Any Integer between 100 (maximum quality) and 1 (lowest quality) is allowed as the value.

Supported Properties

The following configuration properties are allowed within the configuration file:

Key
Required
Description
version
Yes
The version of the configuration that should be used. The most recent one for this file is currently 1.
images
Yes
A map of configuration properties (described below) that are considered every time an image is optimized.

Within images, the following Map has to be replaced:

Key
Required
Description
sizes
Yes
A list of Integers containing the allowed widths for when images are resized.
domains
Yes
A list of Strings containing the domains to be allowed as part of the URL when optimizing images.
minimumCacheTTL
No
The amount of time (in seconds) that should pass before an image is marked as stale. If an image is marked as stale, the next time a new request for it comes in, it will asynchronously be optimized again in the background.
formats
No
A list of Strings that represent potential values of the Accept header of an incoming request (defaults to image/webp, but allows image/avif as an additional entry). If an incoming request has a matching Accept header, the image will be transformed into this format. If no matching header is found, the image's original format remains unchanged.

Example

This is what the configuration file could look like in a real scenario:

{
  "version": 1,
  "images": {
    "sizes": [256, 384],
    "domains": ["external-site.com"],
    "minimumCacheTTL": 60,
    "formats": ["image/webp", "image/avif"]
  }
}

Pre-Rendering

Relevant File: .output/prerender-manifest.json

When providing Pages for your Deployment, you can choose between statically generating them ahead of time (and supplying Vercel with HTML files), or generating them on-demand, every time a request comes in.

It is generally recommended to opt for providing HTML files to the platform. This provides significant performance advantages because the Pages don't have to be rendered on-demand.

If you are dealing with a large amount of Pages, statically generating them all ahead of time can be slow. To solve this, you can provide Pre-Rendering configuration, which allows you to generate some of the Pages (for example, the ones that are commonly visited) ahead of time, while automatically generating the rest on-demand.

Furthermore, it allows you to easily keep statically generated Pages up-to-date, without having to deploy every update again.

Incremental Static Regeneration

Pre-Rendering on Vercel consists of two major pieces.

The first and most important one, which includes keeping statically generated pages up to date and generating missing ones on-demand is Incremental Static Regeneration (ISR).

Preview Mode

The second and less important piece is Preview Mode, which allows for temporarily bypassing the performance-optimized caches of the Incremental Static Regeneration (ISR) to always receive a on-demand generated Page as a response.

More specifically, this is helpful while editing the content (in the sense of data) of a Page, for example, because it ensures that new content changes are always delivered immediately for the specific visitor that might be editing the Page.

Supported Properties

The following configuration properties are allowed within the configuration file:

Key
Required
Description
version
Yes
The version of the configuration that should be used. The most recent one for this file is currently 3.
routes
Yes
A map of statically generated Pages (HTML files) that should be kept up-to-date and configuration properties for each one. The keys are Strings containing the names of the HTML files, without their extensions. The values are Maps, whose properties are described below.
dynamicRoutes
Yes
A map of on-demand Pages (Functions) that should be used for statically generating missing Pages and configuration properties for each one. The keys are Strings containing the names of the Functions, without their extensions. The values are Maps, whose properties are described below.
preview
Yes
A map containing a single property named previewModeId, which is either null or a String containing any arbitrary characters. In the latter case, passing a cookie named __prerender_bypass with this value will bypass the ISR caches and force the Pages to be generated fresh on-demand.

routes

Used for associating statically generated Pages (HTML) with on-demand Pages (Functions). The statically generated Pages can be served to visitors, and their respective on-demand Page match is used for updating the HTML asynchronously in the background.

This means visitors never receive a slow response, and the HTML is kept up-to-date.

Within routes, every key can have the following Map as its value:

Key
Required
Description
initialRevalidateSeconds
Yes
The amount of seconds that a Page is allowed to be be delivered before the Function for updating its contents is invoked in the background.
srcRoute
Yes
The name of a on-demand Page (Function) without its extension, which is used for updating the HTML of the statically generated Page.
dataRoute
Yes
The name of a on-demand Page (Function) without its extension, which is used for updating the JSON of the statically generated Page. Can be used for client-side transitions, but can also be left as an empty String if not needed.

dynamicRoutes

Can be used in combination with routes, but also standalone.

Its purpose is to capture URL path segments and point them to on-demand Pages (Functions), which will then produce statically generated Pages (HTML) for the respective path. Before the on-demand Pages are invoked, you can also make the platform first consider Pages that were already generated ahead of time (HTML) via fallback, which is recommended for optimal performance.

Overall, this means that incoming requests would first result in the platform trying to find a matching Page that was statically generated ahead of time, after which the respective on-demand Page (Function) is invoked if no match was found.

Within dynamicRoutes, every key can have the following Map as its value:

Key
Required
Description
routeRegex
Yes
A regular expression describing the URL path under which a Page with Incremental Static Regeneration should be attached.
fallback
null or String
Yes
Describes whether the route captured above is only used for statically generating new Pages on-demand if they're missing (null), or if the platform should first consider Pages that were statically generated ahead of time before generating new ones (String referencing the Page without the HTML extension).
dataRoute
Yes
The same as the dataRoute property for routes, but for updating the JSON of the Page that was statically generated on-demand.
dataRouteRegex
Yes
A regular expression describing the URL path under which the JSON for the dataRoute property above should be served.

Example

This is what the configuration file could look like in a real scenario:

{
  "version": 3,
  "routes": {
    "/my-isr-page": {
      "initialRevalidateSeconds": 30,
      "srcRoute": "/my-isr-page",
      "dataRoute": ""
    }
  },
  "dynamicRoutes": {
    "/my-isr-page": {
      "routeRegex": "^/my-isr-page$",
      "dataRoute": "",
      "fallback": null,
      "dataRouteRegex": ""
    }
  },
  "preview": {
    "previewModeId": null
  }
}

Build

Relevant File: .output/build-manifest.json

If you'd like to configure the behavior of your Deployment's Build Step, you can do so by providing the file mentioned above.

Supported Properties

The following configuration properties are allowed within the configuration file:

Key
Required
Description
version
Yes
The version of the configuration that should be used. The most recent one for this file is currently 1.
cache
No
A list of Strings containing globs, where each one represents paths that should be cached.

Example

This is what the configuration file could look like in a real scenario:

{
  "version": 1,
  "cache": ["build/**/*"]
}

Presets

Framework Detection

You can add support for framework detection and define default values on Vercel by adding it to the @vercel/frameworks package:

  1. Fork the vercel/vercel repository on GitHub.
  2. Add your framework to the @vercel/frameworks package by editing the file ./packages/frameworks/src/frameworks.ts.
  3. Copy the structure of an existing framework and adjust the fields for the new framework.
  4. You can add default routes that will always be applied to Projects that use this framework or specify some paths that will be cached to speed up the build process (note that this step can be ignored if the framework makes use of the file system API).
  5. The settings property either contains a value or a placeholder. If the setting should allow the user to override it, use placeholder. To prevent the user from overriding, use value. For example, the Output Directory for Hugo is public by default, but can be changed through its config file, so we use placeholder with an explanation of what can be used.
  6. Add a template to the examples directory: The name of the directory should match the slug of the framework used in @vercel/frameworks. The /.github/EXAMPLE_README_TEMPLATE.md file is a template for creating a README.md file for the template.
  7. Create a Pull Request! After your Pull Request has been merged, someone from Vercel will enable the framework in the API so that anyone can select the framework on the Vercel dashboard and deploy it.