Getting started with self-hosting

In this guide, you will learn how to install the hosting package, configure your first defineHosting() definition, and deploy your frontend to your own AWS account.

Prerequisites

Before you begin, ensure that your AWS account has been bootstrapped with AWS CDK and that you have valid AWS credentials configured in your environment. Run cdk bootstrap aws://ACCOUNT_ID/REGION if you have not done so already.

You need an existing Amplify Gen 2 project with a backend already defined in amplify/backend.ts. If you do not have one yet, follow the quickstart guide first.

Installing the hosting package

Add the @aws-amplify/hosting package to your project:

Terminal

npm add @aws-amplify/hosting

Creating the hosting definition

Create a new file at amplify/hosting.ts. This file lives alongside your amplify/backend.ts but defines your frontend infrastructure separately.

amplify/hosting.ts
import { defineHosting } from '@aws-amplify/hosting';
export const hosting = defineHosting();

The framework is auto-detected from your package.json, so no framework configuration is required here. See Supported frameworks for the full list, and Configure hosting if you need to override detection.

Deploying your application

Run ampx deploy to synthesize and deploy both your backend and hosting stacks:

Terminal

npx ampx deploy --identifier production

The --identifier flag names your deployment environment. This command deploys everything: backend resources, the frontend build, and the hosting infrastructure (S3 bucket, CloudFront distribution, and compute layer).

Once complete, the CLI prints your CloudFront distribution URL where your application is live.

Deploying only the frontend

If your backend is already deployed and you only need to update the frontend:

Terminal

npx ampx deploy --identifier production --frontend

This skips the backend stack and only rebuilds and deploys your frontend assets.

Verifying your deployment

After deployment, the CLI outputs the distribution URL. Open it in a browser to confirm your application is serving correctly. You can also find the Amazon CloudFront distribution in the AWS Console under the Amazon CloudFront service.

Next steps

Configure hosting to add custom domains, WAF, and CDN tuning
Add secrets and environment variables for your server-side code
Set up a CI/CD pipeline with CodePipeline
Use an external CI/CD pipeline with GitHub Actions or GitLab CI