How to Use AWS Amplify with Astro: Complete Guide

Step-by-step guide to integrating AWS Amplify with your Astro website.

AWS Amplify is Amazon's full-stack development platform for building and deploying web and mobile apps. For Astro developers, Amplify Hosting is the main draw. It gives you CI/CD from Git, automatic branch previews, custom domains with free SSL, and all of it backed by AWS infrastructure. If your organization already runs on AWS, Amplify keeps everything under one roof without introducing another vendor.

The setup is simpler than most AWS services. You connect a Git repo, Amplify detects the framework, builds your site, and deploys it to a global CDN. It handles both static Astro sites and SSR if you enable server-side rendering.

Versions in this guide were checked on 2026-05-29 against the npm registry and the official AWS Amplify and Astro docs. Astro is on the v6 line (latest astro@6.4.2). AWS does not maintain an Amplify-owned Astro adapter, so SSR uses the community astro-aws-amplify adapter. See the Sources list at the bottom.

Prerequisites

Node.js 22.12.0 or higher (the astro-aws-amplify adapter requires it, and Astro v6 expects a modern Node release). Note that Amplify's default build image uses an older Node that is not supported, so you will set a custom build image (see Common Errors and Fixes).
An Astro project (npm create astro@latest)
An AWS account (free tier available, pay-as-you-go after that)
Your project in a GitHub, GitLab, or Bitbucket repository

Static vs On-Demand Rendering

Astro is a static site by default. In Astro v6 the valid values for the output config option are static (the default) and server. The old hybrid value was removed in Astro 5, so do not use it. To mix static and on-demand pages, leave the project on the default static output and add export const prerender = false to the individual pages or endpoints you want rendered on demand. The rest of the site stays static.

For a purely static Astro site you do not need any adapter or extra packages. Amplify builds your dist/ output and serves it from the CDN.

Installation

For a static Astro site, no additional packages are needed. Skip ahead to Configuration.

For server-side rendering on Amplify, install the community adapter. AWS Amplify does not ship an official Astro adapter, and the AWS tutorial explicitly recommends the community astro-aws-amplify adapter (latest astro-aws-amplify@0.4.1, peer astro@^6.0.0):

npm install astro-aws-amplify

Then add the adapter and set output: 'server' in your config. This matches the snippet in the AWS tutorial:

// astro.config.mjs
import { defineConfig } from "astro/config";
import awsAmplify from "astro-aws-amplify";

export default defineConfig({
  site: "https://example.com",
  output: "server",
  adapter: awsAmplify(),
});

If you only need a few dynamic routes, keep output: 'static' and mark just those pages with export const prerender = false. The adapter still handles the on-demand routes while everything else ships as static HTML.

Configuration

For a static Astro site, the build spec points at the dist/ output. Amplify usually auto-detects Astro and fills this in for you, but you can set it explicitly with an amplify.yml build specification file in your project root:

# amplify.yml (static SSG)
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci --cache .npm --prefer-offline
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - "**/*"
  cache:
    paths:
      - .npm/**/*

For SSR deployments the build spec is different, and getting it wrong is the most common reason an Astro SSR deploy fails on Amplify. The astro-aws-amplify adapter emits a deployment bundle into a .amplify-hosting directory, so the artifact baseDirectory must be .amplify-hosting (not dist). You also have to move node_modules into the compute bundle so the server function has its runtime dependencies. This is exactly the build spec from the official AWS tutorial:

# amplify.yml (SSR via astro-aws-amplify)
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci --cache .npm --prefer-offline
    build:
      commands:
        - npm run build
        - mv node_modules ./.amplify-hosting/compute/default
  artifacts:
    baseDirectory: .amplify-hosting
    files:
      - "**/*"
  cache:
    paths:
      - .npm/**/*

In the Amplify Console, set the Build output directory to .amplify-hosting for SSR apps (under App settings then Build settings, or via Edit YML file). If you want Amplify to deliver server logs to Amazon CloudWatch, open Advanced settings during setup and choose Enable SSR app logs.

Now connect your repository in the AWS Amplify Console:

Go to AWS Amplify in the AWS Console
Click "New app" then "Host web app"
Connect your Git provider and select your repository
Amplify auto-detects Astro and suggests build settings
Review and deploy

You can also do this via the AWS CLI:

aws amplify create-app --name my-astro-site --repository https://github.com/user/repo --access-token YOUR_GITHUB_TOKEN

Basic Usage

Once deployed, Amplify gives you a URL like https://main.d1234abcde.amplifyapp.com. Set up a custom domain through the Amplify Console under Domain management.

Environment variables are set in the Amplify Console under App settings > Environment variables:

# In Amplify Console, add these environment variables
SITE_URL=https://yourdomain.com
API_KEY=your-api-key

Access them in your Astro code normally:

---
// src/pages/index.astro
const siteUrl = import.meta.env.SITE_URL;
---

<html>
  <head>
    <link rel="canonical" href={siteUrl} />
  </head>
  <body>
    <h1>Deployed on AWS Amplify</h1>
  </body>
</html>

For branch-based deployments, push to different branches and Amplify creates separate environments automatically:

# Production
git push origin main

# Preview/staging
git push origin develop

Each branch gets its own URL and can have different environment variables.

Production Tips

Use branch previews for pull requests. Enable "Previews" in Amplify settings to automatically deploy each pull request to a unique URL. This lets your team review changes before merging. Each preview gets its own environment and URL.

Set up custom headers and redirects. Configure security headers and redirects in the Amplify Console under App settings then Rewrites and redirects, or in customHttp.yml. For SPA-style fallbacks on a static site, an Amplify redirect rule sending unmatched routes to index.html is the typical pattern.

Monitor build performance. Amplify shows build logs and timing for each deployment. If builds are slow, cache the npm download directory by listing .npm/**/* under cache.paths in amplify.yml (as shown above) and use npm ci --cache .npm --prefer-offline instead of npm install for faster, reproducible installs.

Enable access control for staging. Amplify supports password-protecting branch deployments. Use this for staging environments so only your team can access preview deployments.

Set up notifications. Configure build notifications through Amazon SNS or connect to Slack. This way your team knows immediately when a deploy succeeds or fails without checking the console.

Common Errors and Fixes

Build fails with an unsupported Node version. Amplify's default build image runs an older Node release that does not satisfy the astro-aws-amplify adapter or Astro v6. The fix recommended by the adapter is to set the environment variable _CUSTOM_IMAGE=amplify:al2023 in the Amplify Console (App settings then Environment variables) so the build runs on Amazon Linux 2023 with a current Node. You can also pin a Node version explicitly in the preBuild phase if your image supports nvm.

SSR deploy succeeds but every route 404s or returns a server error. This almost always means the artifact baseDirectory is still dist instead of .amplify-hosting, or the mv node_modules ./.amplify-hosting/compute/default build step is missing. The adapter writes the compute bundle under .amplify-hosting/compute/default, and Amplify will not find a server function without it. Use the SSR amplify.yml shown above verbatim.

Using output: 'hybrid' throws a config error. The hybrid value was removed in Astro 5. In Astro v6 use static (default) or server, and control per-page rendering with export const prerender = false (in a static project) or export const prerender = true (in a server project).

Installing @astrojs/node and expecting Amplify SSR to work. The Node adapter targets a self-managed Node server, not Amplify's compute model. For Amplify SSR you need the astro-aws-amplify adapter, which produces the .amplify-hosting output format Amplify expects.

Environment variables are undefined at runtime. Variables set in the Amplify Console are available at build time. To expose a value to client code it must be prefixed appropriately and accessed through import.meta.env; values without a PUBLIC_ prefix are server-only in Astro and will not appear in the browser bundle.

Official Docs and Examples

AWS Amplify support for Astro.js: https://docs.aws.amazon.com/amplify/latest/userguide/astro-support.html
AWS tutorial, Deploy an Astro.js app to Amplify Hosting: https://docs.aws.amazon.com/amplify/latest/userguide/get-started-astro.html
Astro official deploy-to-AWS guide: https://docs.astro.build/en/guides/deploy/aws/
Astro on-demand rendering reference (output modes, prerender): https://docs.astro.build/en/guides/on-demand-rendering/
Community adapter source and quickstart, astro-aws-amplify: https://github.com/alexnguyennz/astro-aws-amplify

Alternatives to Consider

Vercel if you want a simpler deployment experience with zero configuration and better framework-specific optimizations for Astro.
Netlify if you prefer a similar CI/CD platform with more built-in features like forms, identity, and serverless functions without AWS complexity.
Cloudflare Pages if you want edge deployment with unlimited bandwidth on the free tier and faster build times.

Wrapping Up

AWS Amplify is a solid choice for deploying Astro sites, especially if your stack is already on AWS. The CI/CD pipeline is mature, branch previews are useful for team workflows, and the global CDN keeps your static assets fast worldwide. The setup takes a few more clicks than Vercel or Netlify, but the AWS integration and pay-as-you-go pricing make it worthwhile for teams that need to stay within the AWS ecosystem. For simple static Astro sites, the free tier covers most small to medium projects comfortably. If you need SSR, just remember the three things that trip people up: install astro-aws-amplify (not the Node adapter), point the artifact baseDirectory at .amplify-hosting, and set a modern build image.