Skip to content
Astro AWS

Getting Started

What is Astro AWS

Section titled “What is Astro AWS”

Astro AWS is an Astro SSR adapter and AWS CDK constructs for deploying your Astro application to AWS. It provides everything you need to deploy your Astro application to AWS Lambda with CloudFront, handling both server-side rendered (SSR) and static content.

IMPORTANT NOTE: These packages only provide the bare minimum AWS CDK configuration to get your application running. Everything that does not need to be configured uses the default values AWS provides.

Prerequisites

Section titled “Prerequisites”

Before you begin, make sure you have the following:

  • Node.js 22.x or higher
  • AWS Account with appropriate permissions
  • AWS CLI installed and configured with your credentials
  • AWS CDK CLI (we’ll install this in the guide)
  • AWS Region that supports Lambda function URLs

Step 1: Create your Astro project

Section titled “Step 1: Create your Astro project”

Create a new Astro project using the create-astro CLI, then add the Astro AWS adapter.

Terminal window
npm create astro@latest
npx astro add @astro-aws/adapter

The adapter will automatically configure your astro.config.mjs file with the necessary settings.

Step 2: Build your Astro project

Section titled “Step 2: Build your Astro project”

Build your Astro project to generate the deployment artifacts:

Terminal window
npm run build

This creates a dist directory containing your built application that will be deployed to AWS.

Step 3: Set up your AWS CDK project

Section titled “Step 3: Set up your AWS CDK project”

Install AWS CDK CLI

Section titled “Install AWS CDK CLI”
Terminal window
npm install -g aws-cdk

Create a new CDK project

Section titled “Create a new CDK project”
Terminal window
mkdir my-cdk-project
cd my-cdk-project
cdk init app --language typescript

Install dependencies

Section titled “Install dependencies”

Install the @astro-aws/constructs package and its peer dependencies:

Terminal window
npm install @astro-aws/constructs constructs aws-cdk-lib

Configure your CDK stack

Section titled “Configure your CDK stack”

Update the stack file (typically lib/my-cdk-project-stack.ts or similar) with the following:

import { Stack } from "aws-cdk-lib"
import type { StackProps } from "aws-cdk-lib"
import { Construct } from "constructs"
import { AstroAWS } from "@astro-aws/constructs"


export interface AstroSiteStackProps extends StackProps {}


export class AstroSiteStack extends Stack {
  public constructor(scope: Construct, id: string, props: AstroSiteStackProps) {
    super(scope, id, props)


    new AstroAWS(this, "AstroAWS", {
      websiteDir: "../my-astro-project", // Path to your Astro project directory
    })
  }
}

Note: Update websiteDir to point to the relative path of your Astro project from the CDK project directory. The construct will look for the dist directory inside this path.

Step 4: Bootstrap AWS CDK (first time only)

Section titled “Step 4: Bootstrap AWS CDK (first time only)”

Before bootstrapping, confirm that your configured AWS region supports Lambda function URLs. Deployments to unsupported regions fail with an Unrecognized resource types: [AWS::Lambda::Url] error.

If this is your first time using AWS CDK in this account and region, you need to bootstrap it:

Terminal window
cdk bootstrap

This creates the necessary resources for CDK to deploy your application.

Step 5: Deploy your application

Section titled “Step 5: Deploy your application”

Deploy your CDK stack to AWS:

Terminal window
cdk deploy

The deployment process will:

  1. Create an S3 bucket to host static assets
  2. Create a Lambda function with your Astro application (SSR only)
  3. Set up a CloudFront distribution
  4. Configure Origin Access Control (OAC) to restrict S3 access to CloudFront only
  5. Configure the necessary IAM roles and permissions
  6. Output the CloudFront distribution URL

After deployment completes, you’ll see the CloudFront distribution URL in the output. Your Astro application is now live on AWS!

Next Steps

Section titled “Next Steps”