Amplify support for SSR frameworks

Amplify Hosting supports any JavaScript based SSR framework with a deployment bundle that conforms to the build output that Amplify expects. Amplify Hosting provides a deployment specification that standardizes the files and directory structure for the output of an application's build for any SSR framework.

Framework authors can use the file system based deployment specification to develop open-source build adapters customized for their specific frameworks. These adapters will transform an app's build output into a deployment bundle that conforms to Amplify Hosting’s expected directory structure. This deployment bundle will include all the necessary files and assets to host an app, including runtime configuration, such as routing rules.

If you aren't using a framework or a framework adapter, you can develop your own solution to generate a deployment bundle that conforms to Amplify Hosting's expected directory structure.

Amplify Hosting supports the following primitive types: Static assets, Compute, Image optimization, and Routing rules. You can leverage these primitive types to deploy applications with richer functionality. For detailed information about each primitive type, see Amplify SSR primitive type support.

You can choose from the following scenarios to get started with deploying an SSR app to Amplify.

Deploy a Next.js app

Amplify supports applications created using Next.js without the need for an adapter or manual configuration in the console. For more information, see Amplify support for Next.js.

Deploy an app that uses a framework adapter

You can reference any available open source framework adapter to deploy your SSR app to Amplify Hosting. For more information, see Using a framework adapter.

An adapter is available for the Nuxt framework. For more information about using this adapter, see the Nuxt documentation.

Build a framework adapter

Framework authors that want to integrate features that a framework provides, can use the Amplify Hosting deployment specification to configure your build output to conform to the structure that Amplify expects. For more information, see Deploying an Express server using the deployment manifest.

Configure a post build script

You can can use the Amplify Hosting deployment specification to manipulate your build output as needed for specific scenarios. For more information, see Using the Amplify Hosting deployment specification to configure build output. For an example, see Deploying an Express server using the deployment manifest.

Deploy an SSR app to Amplify

You can use the instructions in this topic to deploy an app created with any framework with a deployment bundle that conforms to the build output that Amplify expects. If you're deploying a Next.js application, no adapter is needed.

If you're deploying an SSR app that uses a framework adapter, you must first install and configure the adapter. For instructions, see Using a framework adapter.

To deploy an SSR app to Amplify Hosting

1. Sign in to the AWS Management Console and open the Amplify console.

2. On the All apps page, choose Create new app.

3. On the Start building with Amplify page, choose your Git repository provider, then choose Next.

4. On the Add repository branch page do the following:

   1. Select the name of the repository to connect.

   2. Select the name of the repository branch to connect.

   3. Choose Next.

5. On the App settings page, Amplify automatically detects Next.js SSR apps.

   If you are deploying an SSR app that uses an adapter for another framework, you must explicitly enable Amazon CloudWatch Logs. Open the Advanced settings section, then choose Enable SSR app logs in the Server-Side Rendering (SSR) deployment section.

6. The app requires an IAM service role that Amplify assumes to deliver logs to your AWS account.

   The procedure for adding a service role varies depending on whether you want to create a new role or use an existing one.

   • To create a new role:

     1. Choose Create and use a new service role.

   • To use an existing role:

     1. Choose Use an existing role.

     2. In the service role list, select the role to use.

7. Choose Next.

8. On the Review page, choose Save and deploy.

Using a framework adapter

You can install and use any SSR framework build adapter that has been created for integration with Amplify Hosting. Each framework that offers an adapter determines how the adapter is configured and connected to their build process. Typically, you will install the adapter as an npm development dependency.

After you create an app with a framework, use the framework's documentation to learn how to install the Amplify Hosting adapter and configure it in your application's configuration file.

Next, create an amplify.yml file in your project's root directory. In the amplify.yml file, set the baseDirectory to your application's build output directory. The framework runs the adapter during the build process to transform the output into the Amplify Hosting deployment bundle.

The name of the build output directory can be anything, but the .amplify-hosting filename has significance. Amplify first looks for a directory defined as the baseDirectory. If it exists, Amplify looks for the build output there. If the directory doesn't exist, Amplify looks for the build output inside .amplify-hosting, even if it has not been defined by the customer.

The following is an example of the build settings for an app. The baseDirectory is set to .amplify-hosting to indicate that the build output is in the .amplify-hosting folder. As long as the contents of the .amplify-hosting folder match the Amplify Hosting deployment specification, the app will deploy successfully.

version: 1
frontend:
  preBuild:
    commands:
      - npm install
  build:
    commands:
      - npm run build
  artifacts:
    baseDirectory: .amplify-hosting

After your app is configured to use a framework adapter, you can deploy it to Amplify Hosting. For detailed instructions, see Deploy an SSR app to Amplify