This page describes how you can ensure that your framework works perfectly on Vercel. The platform provides APIs and configurations that help authors to support features they need for their framework, or to automatically detect if their framework is being used.

A subset of frameworks that is supported and can be automatically detected can be found in the @vercel/frameworks package. More information about this can be found in the Framework Detection section.

The file system API allows the framework to place its build outputs inside of specific directories during the build step. The files will then be used depending on which directory they have been put in.

As shown in the sections below, a number of features are supported.

Files placed in .vercel_build_output/static will be served as static files. All other output directories for static files will be ignored if this directory is present and contains files inside of it.

Files that match the path .vercel_build_output/functions/<language>/<name>/index.<extension> will become Serverless Functions. The language part is the programming language used for the Serverless Function, the extension part would be the file extension for that language. At the moment only node is supported as language and js as extension. The name is the name of the Serverless Function under which it'll be available.

The index file inside of the name directory will be the entrypoint of the Serverless Function. All other files in that directory and subdirectories will be bundled with the Serverless Function, so they'll be available at runtime. As a result, it's not possible to use a name that's more than one path segment, meaning my-function is valid, but my/function would not be.

The Serverless Functions will be accessible at /.vercel/functions/<name> on the deployment. Routes can then be used to create rewrites for those Serverless Functions.

The file .vercel_build_output/config/routes.json can be used to create Routes for the deployment.

A common use case would be to add a catch-all route that acts as a rewrite to a Serverless Function – and serving a few static assets.

The routes.json file could then look like this:

[
  { "handle": "filesystem" },
  {
    "src": "/(.*)",
    "dest": "/.vercel/functions/renderer"
  }
]

The "handle": "filesystem" part is required in this case, as the catch-all route would otherwise rewrite all requests for the static assets to the renderer Serverless Function.

All Serverless Functions can be configured through a single JSON file located at .vercel_build_output/config/functions.json.

The file must contain an object where each key matches the name of a Serverless Function in .vercel_build_output/functions/node/<name>/index.<extension>.

Each Serverless Function can then be configured with the following properties:

• memory (optional): An integer defining the memory in MB for your Serverless Function (between 128 and 3009).
• maxDuration (optional): An integer defining how long your Serverless Function should be allowed to run on every request in seconds (between 1 and the maximum limit of your plan).

If no configuration was provided, the following defaults will be used:

• Memory: 1024 MB (1 GB)
• Execution Duration: 10 seconds (Hobby), 15 seconds (Pro), 15 seconds (Enterprise)

As an example, if the Serverless Function .vercel_build_output/functions/node/my-function/index.js requires more than the default 1024 MB of memory, then it can be increased to 3009 MB by creating the file .vercel_build_output/config/functions.json with the following content:

{
  "my-function": {
    "memory": 3009
  }
}

The file .vercel_build_output/config/images.json can be used to enable Image Optimization for the deployment.

Once enabled, you can optimize an image by visiting /_vercel/image with the following query string paramaeters:

• url (required): The path or URL of the source image. This can be a local image URL like /logo.png or an external image URL like https://assets.example.com/logo.png.
• w (required): The desired width of the image. The aspect ratio is maintained so the height will scale proportionally to the width.
• q (required): The desired quality of the image. This is an integer between 1 and 100 where 1 is the lowest quality and 100 is the highest quality.

For example, visiting /_vercel/image?url=%2Flogo.png&w=640&q=75 will resize the logo.png file to 640px width at 75% quality.

Below is an example images.json file:

{
  "domains": ["assets.example.com"],
  "sizes": [640, 750, 828, 1080, 1200, 1920]
}

• domains (optional): A list of hostnames. This is necessary in order to enable external images using the url parameter.
• sizes (required): A list of image widths. This is necessary in order to enable resizing an image to a given width using the w parameter.

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.