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.
Now, the app can be created in Amplify Hosting. In Amplify Hosting, create a new app using the Host web app flow.
Connect to your GitHub repo and 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:
- '**/*'
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.
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 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" }
.
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.
This will open the CloudWatch console. Click on the most recent Log stream.
In these logs, the statement added in the server route will be logged out.
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
- Amplify Hosting support for SSR frameworks
- Deploying an Express server to Amplify Hosting using the deployment manifest
- Advanced configuration for the Nitro server AWS Amplify provider