Introduction

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.

What's the File System API?

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.

Note: It's always possible to check the Output tab on the Dashboard for a deployment to see all created resources.

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

Assets

Static Files

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.

Serverless Functions

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.

Configuration

Routes

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.

Images

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.

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.