AWS Amplify CLI Hosting Plugin

3.4.10 · active · verified Wed Apr 22

This package is a core plugin for the AWS Amplify Command Line Interface (CLI), specifically designed to manage the hosting services for Amplify projects. It empowers developers to seamlessly add, update, push, and remove web hosting capabilities, primarily leveraging services like AWS Amplify Console (for full-stack deployments) or Amazon S3/CloudFront (for static site hosting). While the overall Amplify CLI is in its `v14.x` major version, this specific plugin (`amplify-category-hosting`) is at version `3.4.10`, indicating a stable and less frequently updated internal component. The Amplify CLI generally follows a frequent release cadence, often weekly or bi-weekly, for bug fixes and minor improvements across its various categories. Its key differentiator is deeply integrating hosting with other Amplify backend categories (Auth, API, Storage) and providing a streamlined CI/CD pipeline for frontend web applications, simplifying the deployment process for developers.

Common errors

```
The Amplify Console displays the “build” step of one of your environments as failed and shows other environments as successfully deployed.
```
cause Inconsistent deployments across environments, often in multi-account or CI/CD pipelines, where one environment fails to update.

fix Using the Amplify CLI, deploy the application specifically in the failing account/environment. Get the App ID from a working environment (e.g., 'dev') and then run `amplify pull --appId <APP_ID> --envName <FAILING_ENV_NAME>` followed by `amplify publish` or `amplify push` in the context of the failing environment.
```
Push failures from unmanaged changes to cloud resources - Drift
```
cause Amplify-managed cloud resources (e.g., DynamoDB tables, Cognito Roles, IAM policies) were modified outside of the Amplify CLI or Amplify Studio, leading to a mismatch between the CloudFormation stack and the actual AWS resources.

fix Avoid manual changes to Amplify-generated resources. If drift occurs, `amplify status` might indicate discrepancies. In some cases, `amplify push --force` may help synchronize, but for complex drift, manual intervention to revert changes in the AWS Console to match the CloudFormation template or even recreating the resource might be necessary as a last resort.
```
Deployment failed due to build error: The request entity is too large.
```
cause Your build artifact, particularly for Server-Side Rendered (SSR) applications using AWS Lambda, exceeds the maximum allowed deployment package size (e.g., 50MB for Lambda).

fix Reduce the size of your deployment artifact. This often involves ensuring that development dependencies are not bundled into the production build, using external modules provided by the Lambda runtime where possible, or excluding large unnecessary files from the deployment package.
```
Deployment failed due to build error: 'out of memory' or 'Build timed out'
```
cause The build process exhausted the memory allocated to the Amplify build container or exceeded the maximum build duration. This is common for large React/Next.js applications.

fix In the Amplify Console, navigate to 'App settings' -> 'Build settings'. Increase the 'Build compute type' from 'Standard' to 'Large' to provide more memory. Also, increase the 'Build timeout' setting to 60 or 120 minutes.

Warnings

breaking The Amplify CLI introduced a major version `14.0.0` which updated the default Node.js runtime to Node.js 18 and removed support for .NET Core 3.1. Ensure your local environment and Amplify Console build settings match this requirement to avoid build failures.
Fix: Update Node.js to version 18 or higher in your local development environment and in your Amplify Console build settings. Configure the `runtime` in your build specification if necessary.
gotcha Modifying Amplify-managed cloud resources (e.g., S3 buckets, CloudFront distributions, IAM roles) directly through the AWS Console can cause 'drift' and lead to `amplify push` failures or unexpected behavior during subsequent deployments.
Fix: Always use the Amplify CLI or Amplify Studio to manage resources provisioned by Amplify. If drift occurs, a `amplify status` and `amplify push --force` might sometimes resolve it, but it's best to avoid manual changes. For complex cases, consider rolling back or recreating the environment.
gotcha When migrating between Amplify CLI major versions or working in multi-account/multi-environment setups, ensure consistent `amplifyconfiguration.json` (or `aws-exports.js`) files across all environments and that build environments have correct credentials. Discrepancies can lead to deployment failures in CI/CD pipelines.
Fix: Regularly run `amplify pull --force` in each environment to synchronize local configurations with the backend. For CI/CD, ensure environment variables or IAM roles provide appropriate permissions to deploy to the target Amplify App ID and environment. Verify `platform` type in Amplify Hosting settings is correct for SSR (WEB_COMPUTE/WEB_DYNAMIC) vs static (WEB) apps.
gotcha Build failures in Amplify Hosting are common and can stem from various issues, including Node.js version mismatches, insufficient memory for large applications, exceeding artifact size limits (especially for SSR apps), or build timeouts.
Fix: Check the build logs in the Amplify Console for specific error messages. Ensure your Node.js version is consistent (e.g., set `NVM_VERSION` environment variable). Increase the build compute type (Standard to Large) or build timeout in the Amplify Console. Optimize build artifacts to stay within size limits for SSR Lambda functions (e.g., remove dev dependencies from deployment package).

Install

npm install amplify-category-hosting npm
yarn add amplify-category-hosting yarn
pnpm add amplify-category-hosting pnpm

Imports

amplify hosting add
wrong:
```
import { addHosting } from 'amplify-category-hosting'
```
correct:
```
amplify hosting add
```
This package is a CLI plugin and not designed for programmatic import in client-side or server-side JavaScript/TypeScript applications. Its functionalities are accessed exclusively via `amplify` CLI commands.
amplify hosting push
wrong:
```
import { pushHostingChanges } from 'amplify-category-hosting'
```
correct:
```
amplify hosting push
```
Amplify CLI plugins are invoked as subcommands of the `amplify` executable. Attempting to `import` or `require` this package directly will result in runtime errors.
amplify hosting remove
wrong:
```
import { removeHosting } from 'amplify-category-hosting'
```
correct:
```
amplify hosting remove
```
The primary interaction pattern is through the terminal, running commands like `amplify hosting remove` to manage cloud resources.

Quickstart

Demonstrates initializing an Amplify project, adding Amplify Console hosting for manual deployment, building the frontend, and publishing it to the cloud. It also shows how to remove the hosting category.

npx amplify-cli init --amplify-config '{"projectName":"myamplifyapp","envName":"dev","defaultEditor":"code","frontend":"javascript","framework":"react","srcDir":"src","distDir":"build","buildCommand":"npm run-script build","startCommand":"npm run-script start"}' --force
cd myamplifyapp
# Add hosting for a Single Page App (SPA) or PWA
amplify hosting add
# Choose 'Hosting with Amplify Console (Managed hosting and CI/CD)'
# Choose 'Manual deployment'
# Or integrate with a Git repository for continuous deployment.

# After adding hosting and building your frontend, deploy it:
npm run build
amplify publish

# To remove hosting later:
amplify hosting remove

view raw JSON →