Deploy and host server-side rendered apps with Amplify - AWS Amplify

Deploy and host server-side rendered apps with Amplify

You can use AWS Amplify to deploy and host web apps that use server-side rendering (SSR). Currently, Amplify supports SSR apps created using the Next.js framework. When you deploy your app, Amplify automatically detects SSR–you do not have to perform any manual configuration in the AWS Management Console.

To learn about how Amplify supports SSR, review the following topics.

What is server-side rendering

Previously, Amplify supported the deployment and hosting of static web apps only. These include apps created with single-page application (SPA) frameworks such as React, and apps created with a static site generator (SSG) such as Gatsby. Static web apps consist of a combination of files, such as HTML, CSS, and JavaScript files, that are stored on a content delivery network (CDN). When a client browser makes a request to the website, the server returns a page to the client with an HTTP response and the client browser interprets the content and displays it to the user.

Amplify now supports web apps with server-side rendering (SSR). When a client sends a request to an SSR page, the HTML for the page is created on the server on each request. SSR enables a developer to customize a website per request and per user. In addition, SSR can improve performance and search engine optimization (SEO) for a website.

Amplify support for Next.js SSR

Currently Amplify supports deployment and hosting for server-side rendered (SSR) web apps created using Next.js only. Next.js is a React framework for developing SPAs with JavaScript.

Developers can use Next.js to combine static site generation (SSG) and SSR in a single project. SSG pages are prerendered at build time, and SSR pages are prerendered at request time. In a hybrid project, developers choose which type of prerendering to use for each page.

Prerendering can improve performance and search engine optimization. Because Next.js prerenders all pages on the server, the HTML content of each page is ready when it reaches the client's browser. This content can also load faster. Faster load times improve the end user's experience with a website and positively impact the site's SEO ranking. Prerendering also improves SEO by enabling search engine bots to find and crawl a website's HTML content easily.

Next.js provides built-in analytics support for measuring various performance metrics, such as Time to first byte (TTFB) and First contentful paint (FCP). For more information about Next.js, see Getting started on the Next.js website.

Pricing for Next.js SSR apps

When deploying your Next.js SSR app, Amplify creates additional backend resources in your AWS account, including:

  • An Amazon Simple Storage Service (Amazon S3) bucket that stores the resources for your app's static assets. For information about Amazon S3 charges, see Amazon S3 Pricing.

  • An Amazon CloudFront distribution to serve the app. For information about CloudFront charges, see Amazon CloudFront Pricing.

  • A Lambda@Edge function to customize the content that CloudFront delivers.

When you use the Amplify Framework (Libraries, CLI, UI components), you pay only for the underlying AWS services you use. For more information about Amplify deployment and hosting charges, see AWS Amplify Pricing.

Deploying a Next.js SSR app with Amplify

To deploy a Next.js SSR app with Amplify Console, follow the same workflow for setting up a static app with continuous deployments. For detailed instructions, see Getting started with existing code. Note that you can't set up an SSR app in Amplify with manual deploys.

Package.json file settings

When you deploy a Next.js app, Amplify inspects the app's build script in the package.json file to detect whether the app is SSR or SSG.

The following is an example of the build script for a Next.js SSR app. The build script "next build" indicates that the app supports both SSG and SSR pages.

"scripts": { "dev": "next dev", "build": "next build", "start": "next start" },

The following is an example of the build script for a Next.js SSG app. The build script "next build && next export" indicates that the app supports only SSG pages.

"scripts": { "dev": "next dev", "build": "next build && next export", "start": "next start" },

Amplify build settings

After inspecting your app's package.json file to determine whether you are deploying an SSG or SSR app, Amplify checks the build settings for the app. You can save build settings in the Amplify console or in an amplify.yml file in the root of your repository. For more information, see Configuring build settings.

If Amplify detects that you are deploying a Next.js SSR app, and no amplify.yml file is present, it generates a buildspec for the app and sets baseDirectory to .next. If you are deploying an app where an amplify.yml file is present, the build settings in the file override any build settings in the console. Therefore, you must manually set the baseDirectory to .next in the file.

The following is an example of the build settings for an app where baseDirectory is set to .next. This indicates that the build artifacts are for a Next.js app that supports SSG and SSR pages.

version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/*

If Amplify detects that you are deploying an SSG app, it generates a buildspec for the app and sets baseDirectory to out. If you are deploying an app where an amplify.yml file is present, you must manually set the baseDirectory to out in the file.

The following is an example of the build settings for an app where baseDirectory is set to out. This indicates that the build artifacts are for a Next.js app that supports only SSG pages.

version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: out files: - '**/*' cache: paths: - node_modules/**/*

Adding SSR functionality to a static Next.js app

You can add SSR functionality to an existing static (SSG) Next.js app deployed with Amplify Console. This requires three steps. First, add a service role to the app. Next, update the output directory in the app's build settings. Lastly, update the app's package.json file to indicate that the app uses SSR.

Add a service role

A service role is the AWS Identity and Access Management (IAM) role that Amplify Console assumes when calling other services on your behalf. Follow these steps to add a service role to an SSG app that's already deployed with Amplify Console.

To add a service role

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

  2. If you haven't already created a service role in your Amplify account, see create a service role to complete this prerequisite step.

  3. Choose the static Next.js app that you want to add a service role to.

  4. In the navigation pane, choose App settings, General.

  5. On the App details page, choose Edit

  6. For Service role, choose the name of an existing service role or the name of the service role that you created in step 2.

  7. Choose Save.

Update build settings

Before you redeploy your app with SSR functionality, you must update the build settings for the app to set the output directory to .next. You can edit the build settings in the Amplify console or in an amplify.yml file stored in your repo. For more information see, Configuring build settings.

The following is an example of the build settings for an app where baseDirectory is set to .next.

version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/*

Update the package.json file

After you add a service role and update the build settings, update the app's package.json file. As in the following example, set the build script to "next build" to indicate that the Next.js app supports both SSG and SSR pages.

"scripts": { "dev": "next dev", "build": "next build", "start": "next start" },

Amplify detects the change to the package.json file in your repo and redeploys the app with SSR functionality.

Troubleshooting SSR deployment issues

If you experience unexpected issues when deploying an SSR app with Amplify, review the following troubleshooting topics.

Your output directory is overridden

The output directory for a Next.js app deployed with Amplify must be set to .next. If your app's output directory is being overridden, check the next.config.js file. To have the build output directory default to .next, remove the following line from the file:

distDir: 'build'

Verify that the output directory is set to .next in your build settings. For information about viewing your app's build settings, see Configuring build settings.

The following is an example of the build settings for an app where baseDirectory is set to .next.

version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/*

You get a 404 error after deploying your SSR site

If you get a 404 error after deploying your site, the issue could be caused by your output directory being overridden. To check your next.config.js file and verify the correct build output directory in your app's build spec, follow the steps in the previous topic, Your output directory is overridden.

Your app is missing the rewrite rule for CloudFront SSR distributions

When you deploy an SSR app, Amplify creates a rewrite rule for your CloudFront SSR distributions. If you can't access your app in a web browser, verify that the CloudFront rewrite rule exists in your AWS account. If it's missing, you can either add it manually or redeploy your app.

To view or edit an app's rewrite and redirect rules in the Amplify console, in the navigation pane, choose App settings, then Rewrites and redirects. The following screenshot shows an example of the rewrite rules that Amplify creates for you when you deploy an SSR app.


          The rewrites and redirects pane in the Amplify console.

Your app is too large to deploy

If you try to deploy a Next.js SSR app to Amplify and get a RequestEntityTooLargeException error, your app is too large to deploy. You can attempt to work around this issue by adding cache cleanup code to your next.config.js file.

The following is an example of code in the next.config.js file that performs cache cleanup.

module.exports = { webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => { config.optimization.splitChunks.cacheGroups = { } config.optimization.minimize = true; return config }, }

Your app stores static files in a folder with a reserved path

Next.js can serve static files from a folder named public that's stored in the project's root directory. When you deploy and host a Next.js app with Amplify, your project can't include folders with the path public/static. Amplify reserves the public/static path for use when distributing the app. If your app includes this path, you must rename the static folder before deploying with Amplify.

Your app has reached a CloudFront limit

CloudFront service quotas limit your AWS account to 25 distributions with attached Lambda@Edge functions. If you exceed this quota, you can either delete any unused CloudFront distributions from your account or request a quota increase. For more information, see Requesting a quota increase in the Service Quotas User Guide.

Access control isn't available for your app

Currently, Amplify doesn't support access control for Next.js apps that use SSR. If you are working with an SSR app in the Amplify console, Access control isn't available in the App settings menu in the navigation pane.

Your Next.js app uses unsupported features

You can deploy an app created with Next.js version 10. However, Amplify doesn't currently support the full feature set. Amplify supports all features of Next.js versions 9.x.x, except for Incremental Static Regeneration (ISR).

Unsupported Regions

Amplify doesn't support Next.js SSR app deployment in every AWS region where Amplify Console is available. Currently, Next.js SSR isn't supported in the following Regions: Europe (Milan) eu-south-1, Middle East (Bahrain) me-south-1, and Asia Pacific (Hong Kong) ap-east-1.