astro-aws-amplify

Astro AWS Amplify is an Astro adapter for deploying server-side Astro sites on AWS Amplify Hosting.

View Demo

Prerequisites

• an Astro site - v4.x or higher (may also work on v3.x sites)

Installation

# Using NPM
npm install astro-aws-amplify
# Using Yarn
yarn add astro-aws-amplify
# Using PNPM
pnpm add astro-aws-amplify

In your Astro config, add the adapter:

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

export default defineConfig({
+ output: 'server', // output: 'hybrid'
+ adapter: awsAmplify()
})

Configuration

Astro

Server and hybrid modes are supported. For static sites, remove the adapter and follow these instructions.

AWS Amplify

AWS Amplify Hosting uses Node.js v16 by default which isn't supported.

You can use the newer Amazon Linux:2023 by adding an environment variable of:

_CUSTOM_IMAGE=amplify:al2023

Build specifications

You can use the following build specifications as-is or customize it to your liking. Moving the node_modules folder is required for npm and Yarn deployments.

npm

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
        - mv node_modules ./.amplify-hosting/compute/default
  artifacts:
    baseDirectory: .amplify-hosting
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

pnpm

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm i -g pnpm
        - pnpm config set store-dir .pnpm-store
        - pnpm i
    build:
      commands:
        - pnpm run build
  artifacts:
    baseDirectory: .amplify-hosting
    files:
      - '**/*'
  cache:
    paths:
      - .pnpm-store/**/*

Yarn

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - yarn install
    build:
      commands:
        - yarn run build
        - mv node_modules ./.amplify-hosting/compute/default
  artifacts:
    baseDirectory: .amplify-hosting
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

Features

Supported

• server and hybrid mode
• image optimization with <Image> and <Picture />
• base paths
• middleware

Unsupported or untested

• Amplify Image optimization
• build previews (npm run preview)
• ???

Limitations

Static or prerendered pages

Static or prerendered pages (that are defined with export const prerender = true or default for hybrid) will need a rewrite rule.

For example, if you have a static /about page, create a rewrite of:

/about/ /about/index.html 200 (Rewrite)

If you don't use trailing slashes, you will need to also add:

/about /about/index.html 200 (Rewrite)

For static dynamic routes, like a route of /blog/[slug].astro, create a rewrite of:

/blog/<slug>/ /blog/<slug>/index.html 200 (Rewrite)

Base path rewrites

/base/about/ /base/about/index.html 200 (Rewrite)

404 Pages

Custom 404 pages (like 404.astro) need to be server-side rendered (not prerendered) to work. This is a limitation with Amplify.

Static files without extensions

Due to limitations with Amplify routing, to serve public files without extensions, place them in a folder called assets (/public/assets/) and reference them with /assets/filename:

somefile

Any other static files with extensions will work as usual.

License

MIT

Acknowledgements

Uses code from the @astrojs/node adapter to establish a Node.js server required for AWS Amplify SSR environments.