Front-End Web & Mobile

Introducing Support for Hosting Any SSR app on AWS Amplify Hosting

We’re excited to announce the general availability of a new deployment specification that enables developers and frontend framework authors to deploy fully managed server-side rendering (SSR) applications on AWS Amplify Hosting. The deployment specification opens up Amplify Hosting’s SSR capabilities to all frameworks. By following these documented conventions, developers or framework authors can deploy applications built with popular SSR frameworks like Nuxt, SvelteKit, Astro, and even Express servers. The specification defines convention-based primitives for Compute, Image optimization, Routing rules, and Static assets. The key features include:

  • Static assets – Provides frameworks the ability to host static files.
  • Compute – Provides frameworks the ability to run a Node.js HTTP server on port 3000.
  • Image optimization – Provides frameworks a service to optimize images at runtime.
  • Routing Rules – Provides frameworks a mechanism to map incoming request paths to specific targets.

The new SSR deployment specification is designed for developers and framework authors to build adapters to take advantage of the SSR primitives, like Nuxt has with the Nitro server preset. Additionally, this opens up possibilities for developers to explore similar implementations with other frameworks and technologies, like Express.js, to take full advantage of the primitives.

The specification and its convention-based primitives for Compute, Image optimization, Routing rules, and Static assets are documented in the Amplify Hosting SSR deployment specification documentation.

Support for Nuxt

Today, we’re launching with support for Nuxt using this built-in adapter pattern within the Nitro server. Now, you can get started deploying Nuxt SSR apps on Amplify Hosting without any additional dependencies in your project. Using the new deployment spec, the Nuxt team has created an adapter that makes it possible to deploy a Nuxt app to Amplify Hosting with zero-configuration. We’ll show how below.

Solution Overview

To leverage this new feature, we have partnered with the Nuxt team to add built-in support for Nuxt SSR deployments on Amplify Hosting. The spec is implemented in the built-in deployment preset within the Nitro server that powers Nuxt, and extends support to any framework built on Nitro.

This post will focus on deploying a Nuxt SSR application to Amplify Hosting. The Nuxt app uses the built-in zero-config adapter available from the Nitro server. In just a few steps, we can create and deploy a Nuxt SSR app to Amplify Hosting.

Deploying a Nuxt SSR App

Now, deploying a Nuxt app to Amplify Hosting is straightforward. To get started, only the Nuxt the dependencies are required. Since Nuxt has implemented a built-in adapter via the Nitro server, it’s possible to deploy to Amplify Hosting with minimal setup.

Once your application is running and tested locally, you can deploy to Amplify Hosting with the continuous CI/CD. During the build process in Amplify CI/CD, the Nitro server recognizes it’s in the Amplify CI/CD pipeline and automatically selects the zero-config Nitro preset as aws_amplify. This step adjusts the app’s build output to align with the Amplify Hosting deployment specification. This is entire process is done by the Nuxt built in adapter.

Getting started with a new Nuxt app

To get started, we’ll create a new Nuxt app using nuxi :

npx nuxi@latest init

In this example, we’re using npm as the package manager. You’ll see a message about the completion of the installation, along with a prompt to initialize a Git repository, which you should accept.

✔ Which package manager would you like to use?
npm
◐ Installing dependencies...                                       

> postinstall
> nuxt prepare

✔ Types generated in .nuxt                                        

✔ Installation completed.                                         

✔ Initialize git repository?
Yes
ℹ Initializing git repository...                                  

Initialized empty Git repository in ...
                                                                   
✨ Nuxt project has been created with the v3 template. Next steps:
 › cd nuxt-app                                                     
 › Start development server with npm run dev

The package.json file in your project will resemble the example below, containing the typical development dependencies for Nuxt and Vue.

{
  "name": "nuxt-app",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare"
  },
  "devDependencies": {
    "@nuxt/devtools": "latest",
    "nuxt": "^3.8.1",
    "vue": "^3.3.8",
    "vue-router": "^4.2.5"
  }
}

Create a new repository in GitHub and push your local repo to it.

GitHub repo

 

Now, the app can be created in Amplify Hosting. In Amplify Hosting, create a new app using the Host web app flow.

Amplify Hosting Host web app

Connect to your GitHub repo and branch.

Connect to the GitHub repo branch

Provide an App name for your new application. For Nuxt, the Build and test settings will be automatically populated via auto-detection. Make sure this matches the following example, adjusting the install command as needed for your package manager. This configuration sets up the build environment and specifies the baseDirectory as .amplify-hosting for the artifacts to be deployed.

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - nvm use 18
        - corepack enable
        - npx --yes nypm i
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .amplify-hosting
    files:
      - '**/*'

App build settings

The Nitro server adapter automates the process of organizing and moving files into the .amplify-hosting directory according to the deployment specification.

Enabling SSR App Logs in Build Settings

It’s possible to enable server-side logging for the app. Once the app is deployed, this enables server-side logging out to your Amazon CloudWatch account. This means any logging from the server or Nuxt server routes in your application will be captured there.

To enable, in Build and test settings, check the Enable SSR app logs checkbox. After selecting the checkbox, an IAM Role selection or creation option will show. Choose or create an IAM role for Server-side rendering logs. If you choose to allow Amplify Hosting to create an IAM role for you, the role will already have the permissions to create CloudWatch Logs.

select or create an IAM role

On the next screen, select Save and deploy.

Navigate to the Amplify app URL after the app has successfully deployed. The Nuxt app is now live!

Nuxt SSR app deployed on Amplify Hosting

 

Nuxt image

To fully utilize the <NuxtImg> and <NuxtPicture> components, install and configure your app with the @nuxt/image module. Once you’ve set up your app with the module, deploy the changes. Amplify Hosting will automatically enable Image optimization and it will be possible to resize and transform your images when you use the components.

Viewing Nuxt server-side logs

Optionally, we can test server-side logging out to CloudWatch in a few steps. First, add a Nuxt server route in the app in server/api/hello.ts. This is a “Hello, World” example that also adds an extra console.log() when the route receives a request.

export default defineEventHandler((event) => {
  console.log('server route requested')
  return {
    hello: "world",
  };
});

Save the application, and push the new changes to your GitHub repo. This will start a new CI/CD process to to build and deploy the app.


Once deployed, visit the new server endpoint (i.e. main.<app-id>.amplifyapp.com/api/hello). The server will return a JSON response, which in our case is a simple { hello: "world" }.

Nuxt server API response

Now, to view the server-side logs, navigate to the CloudWatch log stream for your Amplify app in Monitoring > Hosting compute logs. Click on the most recent CloudWatch log stream.

Amplify hosting compute logs

This will open the CloudWatch console. Click on the most recent Log stream.

Amplify hosting compute log stream

In these logs, the statement added in the server route will be logged out.

Amplify hosting compute console log

Deploying a Nuxt app on Amplify Hosting is streamlined thanks to the zero-config adapter that takes advantage of the new Amplify Hosting SSR deployment spec. If you’re using a framework that has a compatible adapter, Amplify Hosting will automatically recognize and deploy your application using the SSR primitives, making the process efficient and developer friendly.

Clean up

To wrap up, delete the application if it’s no longer needed. To do this, go into App settings > General in the Amplify Hosting Console for this app and click Delete app. You will also need to delete IAM role for SSR logging if you created one during the app deployment set up. The name of the role will follow the pattern AmplifySSRLoggingRole-<app-id>.

Conclusion

In just a few steps it’s now possible to build and deploy a Nuxt app to Amplify Hosting using the zero-config provider for aws_amplify in the Nitro server. This method simplifies the deployment process, requiring only a validation of build settings for Nuxt apps on Amplify Hosting. It’s a straightforward and fast way to get a Nuxt 3 app up and running on Amplify Hosting.

The new deployment specification opens up the possibility for any developer or framework author to build their own adapter(s) to take advantage of the SSR primitives outlined in the spec. This means that any SSR framework, with a custom-built adapter, can utilize the same streamlined, efficient deployment process on Amplify Hosting.

To dive deeper into Amplify Hosting’s extended SSR capabilities and documentation on building adapters, visit the Deploying server-side rendered apps with Amplify Hosting documentation.

Additional Resources