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 can be found in the Framework Detection section.

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.

The following features are supported:

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.

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.

Framework Detection

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

  1. Create a Pull Request on this Git repository and add your framework to the @vercel/frameworks package. The required file is located in ./packages/frameworks/frameworks.json. You can copy the structure of an existing one and adjust the required fields. Note that the settings property either contains a value or a placeholder. The value property is used when something is not configurable, the placeholder is used when something is configurable and can be changed with configuration. An example would be the Output Directory for Hugo, it's public by default but can be changed through its config file, so we use placeholder with an explanation of what can be used.
  2. Add a template to the ./examples directory: The name of the directory should equal the slug of the framework used in @vercel/frameworks. The .github/EXAMPLE_README_TEMPLATE.md file can be used to create a README.md file for the template.
  3. Update the @vercel/static-build package: The file ./packages/now-static-build/src/frameworks.ts has to be extended. 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.
  4. After your Pull Request has been merged and released, other users can select the template on the Vercel dashboard and deploy it.

Last Edited on January 12th 2021