Deployment previews

Learn about how deployment previews work with your Custom Applications.

This page applies only to Custom Applications.

To test your Custom Application features before releasing them to the production environment, you can add a deployment preview. For example, you can add a deployment preview to try new features in your Custom Application's staging branch.

You must host the deployment previews separately from one another and assign a unique but static URL. You can add as many deployment previews as you like. In the Merchant Center, the deployment previews are available on a unique URL that is different from the production environment.

The process involves building and deploying your preview, then adding the preview to the Custom Application settings.

Build a deployment preview

Each deployment preview has a unique and static deployment URL. The Merchant Center uses this URL to render the deployment preview. Therefore, to build a deployment preview, you must set the env.production.url value to the deployed application's URL in the Custom Application config file. We recommend that you use environment variable references.

custom-application-config.jsonjson

{
  "env": {
    "production": {
      "url": "${env:APP_URL}"
    }
  }
}

With this configuration, you can build deployment previews based on the APP_URL environment variable value and then set up the environment. For example, you could set the APP_URL to different values in different hosting environments or create a .env file in your project and commit different values for the APP_URL variable in different branches.

Deploy a Custom Application preview

After you've built your Custom Application using the correct env.production.url value, you can deploy the Custom Application preview the same way you deploy your Custom Application. The only requirement is that the deployed application URL (APP_URL) is static, so you can specify it in the Merchant Center when adding the deployment preview.

You must set the APP_URL environment variable on your hosting provider.

To get started with hosting providers, see Deployment Examples.

Add a deployment preview to the Custom Application

To use the Custom Application deployment preview inside the Merchant Center, you must add the deployment preview in your Custom Application settings. When you add the deployment preview, you'll need to fill the APP_URL value in the Application URL field.

For example, to add a deployment preview hosted at https://staging.example.com, you would do the following:

Set the APP_URL environment variable to https://staging.example.com in the staging deployment environment.
Set the Application URL to https://staging.example.com when adding the deployment preview in the Merchant Center.