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.

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.

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.

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.

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 Serverless 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.

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 through 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.

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.

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):

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.

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 through Bundling Configuration instead.

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

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 Serverless 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.

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

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.

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 noticeable 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.

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".

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

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',
      },
    });
  },
};

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.

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.

The following configuration properties are allowed within the configuration file:

Within redirects, every Map can contain the following properties:

Within headers, every Map can contain the following properties:

Within rewrites, every Map can contain the following properties:

Within dynamicRoutes, every Map can contain the following properties:

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>[^/]+?)(?:/)?$"
    }
  ]
}

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 Functions (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.

The following configuration properties are allowed within the configuration file:

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

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):

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
    }
  }
}

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 "File Name" example above) has to match them. The dependency files of your Functions can be placed inside of the .output/inputs directory.

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.

The following configuration properties are allowed within the configuration file:

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"
    }
  ]
}

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 optimal 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.

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

The following configuration properties are allowed within the configuration file:

Within images, the following Map has to be replaced:

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/avif", "image/webp"]
  }
}

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 is a pre-rendering technique that enables you to update statically-generated pages on an interval, and generate missing pages on-demand. See our ISR docs to learn more.

Draft Mode allows you to set specific pages to bypass ISR caching and render at request time. This is useful for viewing draft content from a headless CMS without manually triggering page revalidation or waiting for the revalidation interval to pass.

The following configuration properties are allowed within the configuration file:

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:

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) through 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:

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
  }
}

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

The following configuration properties are allowed within the configuration file:

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

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

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.