diff --git a/.yarnrc.yml b/.yarnrc.yml index 3186f3f0795..1ca75809184 100644 --- a/.yarnrc.yml +++ b/.yarnrc.yml @@ -1 +1,3 @@ nodeLinker: node-modules + +npmMinimalAgeGate: 0 diff --git a/cspell.json b/cspell.json index 74ecac7788d..9ce934f6254 100644 --- a/cspell.json +++ b/cspell.json @@ -428,6 +428,7 @@ "Cocoapods", "CocoaPods", "CodeCommit", + "codeconnections", "codegen", "CODEGENJOB", "COGNITO_USERPOOL_ID", @@ -945,6 +946,7 @@ "nextsteps", "ng-recaptcha", "Nkjd", + "nitro", "nitropack", "node_modules", "Node.js.", "node.js", @@ -997,6 +999,7 @@ "OpenID", "OpenSearch", "opensearchservice", + "opennextjs", "openssl", "orderId", "osis", @@ -1157,6 +1160,7 @@ "ROOT_QUERY.listPosts", "ROOT_QUERY", "rootstack", + "rollouts", "Route53", "runOnUiThread", "runtime's", @@ -1460,6 +1464,7 @@ "xcworkspace", "xfbml", "xib", + "xlarge", "xml", "XR.start", "xr", diff --git a/next-env.d.ts b/next-env.d.ts index ddb76465e52..19709046afd 100644 --- a/next-env.d.ts +++ b/next-env.d.ts @@ -1,6 +1,6 @@ /// /// -import "./client/www/next-build/dev/types/routes.d.ts"; +import "./.next/types/routes.d.ts"; // NOTE: This file should not be edited // see https://nextjs.org/docs/pages/api-reference/config/typescript for more information. diff --git a/public/images/gen2/deploy-cycle-self-hosted.svg b/public/images/gen2/deploy-cycle-self-hosted.svg new file mode 100644 index 00000000000..23c2789a69e --- /dev/null +++ b/public/images/gen2/deploy-cycle-self-hosted.svg @@ -0,0 +1,90 @@ + + + + + + + + + + + + + + + + + + + + + DEVELOP + + + + Dev A + localhost:3000 + + + + + + ampx sandbox + + + + ☁ Cloud Sandbox A + + + + Dev B + localhost:3000 + + + + + + ampx sandbox + + + + ☁ Cloud Sandbox B + + + + + + git push + + + + GIT REPOSITORY + + + + beta + + + main + + + + + + auto deploy + + + + YOUR AWS ACCOUNT + + + Each branch deploys its own stack + + + + beta.example.com + + + app.example.com + + diff --git a/public/images/gen2/deploy-cycle.svg b/public/images/gen2/deploy-cycle.svg new file mode 100644 index 00000000000..4bd146a2e60 --- /dev/null +++ b/public/images/gen2/deploy-cycle.svg @@ -0,0 +1,90 @@ + + + + + + + + + + + + + + + + + + + + + DEVELOP + + + + Dev A + localhost:3000 + + + + + + ampx sandbox + + + + ☁ Cloud Sandbox A + + + + Dev B + localhost:3000 + + + + + + ampx sandbox + + + + ☁ Cloud Sandbox B + + + + + + git push + + + + GIT REPOSITORY + + + + beta + + + main + + + + + + auto deploy + + + + AMPLIFY HOSTING + + + Each branch deploys its own environment + + + + beta.example.com + + + app.example.com + + diff --git a/redirects.json b/redirects.json index 9fbc2da6f97..4c59ad2ed4b 100644 --- a/redirects.json +++ b/redirects.json @@ -9656,12 +9656,12 @@ }, { "source": "/gen2/deploy-and-host/fullstack-branching/", - "target": "/gen1/gen2/deploy-and-host/fullstack-branching/", + "target": "/react/deploy-and-host/amplify-hosting/", "status": "301" }, { "source": "/gen2/deploy-and-host/hosting/", - "target": "/gen1/gen2/deploy-and-host/hosting/", + "target": "/react/deploy-and-host/amplify-hosting/", "status": "301" }, { @@ -9836,12 +9836,12 @@ }, { "source": "/gen1/gen2/deploy-and-host/hosting/", - "target": "/react/deploy-and-host/hosting/", + "target": "/react/deploy-and-host/amplify-hosting/", "status": "301" }, { "source": "/gen1/gen2/deploy-and-host/fullstack-branching/", - "target": "/react/deploy-and-host/fullstack-branching/", + "target": "/react/deploy-and-host/amplify-hosting/", "status": "301" }, { @@ -10433,5 +10433,60 @@ "source": "//start/mcp-server/<*>", "target": "//develop-with-ai/mcp-server/<*>", "status": "301" + }, + { + "source": "//deploy-and-host/hosting/", + "target": "//deploy-and-host/amplify-hosting/", + "status": "301" + }, + { + "source": "//deploy-and-host/hosting/<*>", + "target": "//deploy-and-host/amplify-hosting/<*>", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/", + "target": "//deploy-and-host/amplify-hosting/", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/branch-deployments/", + "target": "//deploy-and-host/amplify-hosting/branch-deployments/", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/pr-previews/", + "target": "//deploy-and-host/amplify-hosting/pr-previews/", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/secrets-and-vars/", + "target": "//deploy-and-host/amplify-hosting/secrets-and-vars/", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/share-resources/", + "target": "//deploy-and-host/amplify-hosting/share-resources/", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/custom-pipelines/", + "target": "//deploy-and-host/amplify-hosting/custom-pipelines/", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/cross-account-deployments/", + "target": "//deploy-and-host/amplify-hosting/cross-account-deployments/", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/mono-and-multi-repos/", + "target": "//deploy-and-host/amplify-hosting/mono-and-multi-repos/", + "status": "301" + }, + { + "source": "//deploy-and-host/fullstack-branching/monorepos/", + "target": "//deploy-and-host/amplify-hosting/monorepos/", + "status": "301" } ] \ No newline at end of file diff --git a/src/components/FeatureLists/__tests__/FeatureLists.test.tsx b/src/components/FeatureLists/__tests__/FeatureLists.test.tsx index d6b8ce77a53..75d8c7d5c81 100644 --- a/src/components/FeatureLists/__tests__/FeatureLists.test.tsx +++ b/src/components/FeatureLists/__tests__/FeatureLists.test.tsx @@ -19,11 +19,11 @@ describe('FeatureLists', () => { const featureListComponent = ( - Deploy apps in Next.js, Nuxt.js, Gatsby, React, Vue, Angular (and more) - by simply connecting your Git repository. + Connect your Git repository to Amplify Hosting. Your app builds and + deploys on every push with SSR, SSG, and ISR support. ); @@ -41,7 +41,7 @@ describe('FeatureLists', () => { render(featureListComponent); const link = await screen.findByRole('link', { - name: 'SSR/SSG/ISR hosting support' + name: 'Managed hosting with Git CI/CD' }); expect(link).toBeInTheDocument(); diff --git a/src/components/NextPrevious/index.tsx b/src/components/NextPrevious/index.tsx index 1da4310d835..117ee3c464f 100644 --- a/src/components/NextPrevious/index.tsx +++ b/src/components/NextPrevious/index.tsx @@ -127,5 +127,5 @@ export const NEXT_PREVIOUS_SECTIONS = [ '/[platform]/build-a-backend/add-aws-services/', '/[platform]/build-ui/formbuilder/', '/[platform]/deploy-and-host/sandbox-environments/', - '/[platform]/deploy-and-host/fullstack-branching/' + '/[platform]/deploy-and-host/amplify-hosting/' ]; diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index 8661100b5bb..ae9214fa4d2 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -1188,48 +1188,65 @@ export const directory = { section: 'hosting', children: [ { - path: 'src/pages/[platform]/deploy-and-host/hosting/index.mdx' - }, - { - path: 'src/pages/[platform]/deploy-and-host/sandbox-environments/index.mdx', + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/index.mdx', children: [ { - path: 'src/pages/[platform]/deploy-and-host/sandbox-environments/setup/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/branch-deployments/index.mdx' }, { - path: 'src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/pr-previews/index.mdx' }, { - path: 'src/pages/[platform]/deploy-and-host/sandbox-environments/seed/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/secrets-and-vars/index.mdx' + }, + { + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/share-resources/index.mdx' + }, + { + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/custom-pipelines/index.mdx' + }, + { + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/cross-account-deployments/index.mdx' + }, + { + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/mono-and-multi-repos/index.mdx' + }, + { + path: 'src/pages/[platform]/deploy-and-host/amplify-hosting/monorepos/index.mdx' } ] }, { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/index.mdx', + path: 'src/pages/[platform]/deploy-and-host/self-hosting/index.mdx', children: [ { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/branch-deployments/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/self-hosting/getting-started/index.mdx' }, { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/self-hosting/frameworks/index.mdx' }, { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/share-resources/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/self-hosting/define-hosting/index.mdx' }, { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/mono-and-multi-repos/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/self-hosting/define-pipeline/index.mdx' }, { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/monorepos/index.mdx' - }, + path: 'src/pages/[platform]/deploy-and-host/self-hosting/external-pipelines/index.mdx' + } + ] + }, + { + path: 'src/pages/[platform]/deploy-and-host/sandbox-environments/index.mdx', + children: [ { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/pr-previews/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/sandbox-environments/setup/index.mdx' }, { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/custom-pipelines/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx' }, { - path: 'src/pages/[platform]/deploy-and-host/fullstack-branching/cross-account-deployments/index.mdx' + path: 'src/pages/[platform]/deploy-and-host/sandbox-environments/seed/index.mdx' } ] } diff --git a/src/fragments/gen2/quickstart/deploy-and-host.mdx b/src/fragments/gen2/quickstart/deploy-and-host.mdx index ca452d631d0..fad02e525f6 100644 --- a/src/fragments/gen2/quickstart/deploy-and-host.mdx +++ b/src/fragments/gen2/quickstart/deploy-and-host.mdx @@ -1,22 +1,26 @@ ## Deploy and host a fullstack branch -Now that your app is working, let's deploy it to a shared fullstack branch so you can share the project with your team. Amplify offers a fully managed hosting service with CI/CD built in, making it easy to set up production and staging environments with Git branches. In Gen 2, every Git branch in your repository maps 1:1 to a fullstack branch in Amplify. +Now that your app is working, deploy it to a shared fullstack branch so you can share the project with your team. Amplify provides two hosting options: + +- **Amplify Hosting** provides managed CI/CD with Git-based deployments. Connect your Git repository and Amplify builds, deploys, and serves your app on every push. +- **Self-managed hosting** gives you full CDK control over CloudFront, S3, and Lambda@Edge in your own AWS account, with your own CI/CD pipeline. ### Create remote Git repository If you already have your project remotely hosted in a Git repository, you can skip this step. Otherwise, navigate to your preferred Git provider, and add your project to a new repository. Amplify supports [GitHub](https://docs.github.com/en/get-started/quickstart/create-a-repo), [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-create-repository.html), [GitLab](https://docs.gitlab.com/ee/user/project/index.html), and [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/create-a-git-repository/). -### Connect branch in the Amplify console +### Option 1: Deploy with Amplify Hosting -1. To get started with Gen 2, log in to the [Amplify console](https://console.aws.amazon.com/amplify/home) and navigate to your preferred AWS Region. (The Amplify console is available in [19 AWS Regions](https://docs.aws.amazon.com/general/latest/gr/amplify.html#amplify_region)). -2. From the **Public Preview** banner, choose **Try Amplify Gen 2**. +1. Log in to the [Amplify console](https://console.aws.amazon.com/amplify/home) and navigate to your preferred AWS Region. +2. Choose **Create new app**, then select your Git provider and repository. +3. Pick a branch and click through the flow to **Save and deploy**. -![Amplify console showing the "Public Preview" banner with "Try Amplify Gen 2" button](/images/gen2/getting-started/console1.png) +Every Git branch maps 1:1 to a fullstack branch in Amplify. Your frontend and backend deploy together on every push. -3. In the Git provider screen, choose **Option 2: Start with an existing app**. Connect the repository you just deployed and pick a branch. +### Option 2: Deploy with self-managed hosting -4. Review all of your settings to ensure everything is set up correctly. Choose **Save and deploy** to deploy your web app. +Run `ampx deploy` from your CI/CD pipeline or local machine to deploy your frontend and backend to your own AWS account. See the [self-managed hosting guide](/[platform]/deploy-and-host/self-hosting/) for full setup instructions. -### Manage fullstack branch +### Manage your deployed app -The new Amplify console gives you a central place to manage your branches, hosting settings, CI/CD builds, and backend resources. Even though you can access backend resources directly from AWS service consoles, the Amplify console offers built-in user and data administration. +The Amplify console gives you a central place to manage your branches, hosting settings, CI/CD builds, and backend resources. You can also access backend resources directly from AWS service consoles. The Amplify console offers built-in user and data administration. diff --git a/src/pages/[platform]/README.mdx b/src/pages/[platform]/README.mdx index d330cb92a23..2f246b3f684 100644 --- a/src/pages/[platform]/README.mdx +++ b/src/pages/[platform]/README.mdx @@ -42,16 +42,15 @@ gen2 ├── build-ui │ └── index.mdx ├── deploy-and-host -│ ├── fullstack-branching +│ ├── amplify-hosting │ │ ├── branch-deployments │ │ │ └── index.mdx -│ │ └── sandbox-deployments -│ │ └── index.mdx -│ ├── hosting-features +│ │ └── index.mdx +│ ├── self-hosting +│ │ └── index.mdx +│ ├── sandbox-environments │ │ └── index.mdx │ ├── index.mdx -│ └── local-development -│ └── index.mdx ├── how-amplify-works │ ├── concepts │ │ └── index.mdx diff --git a/src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx b/src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx index 1efa65df3f9..af132d768db 100644 --- a/src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx +++ b/src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx @@ -128,7 +128,7 @@ npx ampx generate schema-from-database --connection-uri-secret SQL_CONNECTION_ST The Lambda function will then use the specified root CA to validate connections to the database. -When deploying your app to production, you need to [add the PEM-encoded public CA certificate as a secret](/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/#set-secrets). Make sure to add the certificate with the same secret name you used in the sandbox environment. For example, we used `CUSTOM_SSL_CERT` above. Make sure to preserve the newlines and the `------BEGIN CERTIFICATE------` and `------END CERTIFICATE------` delimiters in the value. Finally, make sure the size of the entire value does not exceed 4KB. +When deploying your app to production, you need to [add the PEM-encoded public CA certificate as a secret](/[platform]/deploy-and-host/amplify-hosting/secrets-and-vars/#set-secrets). Make sure to add the certificate with the same secret name you used in the sandbox environment. For example, we used `CUSTOM_SSL_CERT` above. Make sure to preserve the newlines and the `------BEGIN CERTIFICATE------` and `------END CERTIFICATE------` delimiters in the value. Finally, make sure the size of the entire value does not exceed 4KB. @@ -201,7 +201,7 @@ const { data: events } = await client.models.event.list() ## Step 5 - Configuring database connection for production -When deploying your app to production, you need to [add the database connection string as a secret](/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/#set-secrets). Make sure to add the appropriate database connection string with the same secret name you used in the sandbox environment. For example, we used `SQL_CONNECTION_STRING` above. +When deploying your app to production, you need to [add the database connection string as a secret](/[platform]/deploy-and-host/amplify-hosting/secrets-and-vars/#set-secrets). Make sure to add the appropriate database connection string with the same secret name you used in the sandbox environment. For example, we used `SQL_CONNECTION_STRING` above. diff --git a/src/pages/[platform]/build-a-backend/functions/environment-variables-and-secrets/index.mdx b/src/pages/[platform]/build-a-backend/functions/environment-variables-and-secrets/index.mdx index 0aeaa35dc7a..2e0e0e50248 100644 --- a/src/pages/[platform]/build-a-backend/functions/environment-variables-and-secrets/index.mdx +++ b/src/pages/[platform]/build-a-backend/functions/environment-variables-and-secrets/index.mdx @@ -59,7 +59,7 @@ export const sayHello = defineFunction({ Any environment variables specified here will be available to the function at runtime. -Some environment variables are constant across all branches and deployments. But many environment values differ between deployment environments. [Branch-specific environment variables can be configured for Amplify hosting deployments](/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/). +Some environment variables are constant across all branches and deployments. But many environment values differ between deployment environments. [Branch-specific environment variables can be configured for Amplify hosting deployments](/[platform]/deploy-and-host/amplify-hosting/secrets-and-vars/). Suppose you created a branch-specific environment variable in hosting called "API_ENDPOINT" which had a different value for your "staging" vs "prod" branch. If you wanted that value to be available to your function you can pass it to the function using @@ -152,7 +152,7 @@ Encountering issues with this file? [Visit the troubleshooting guide for `Cannot Sometimes it is necessary to provide a secret value to a function. For example, it may need a database password or an API key to perform some business use case. Environment variables should NOT be used for this because environment variable values are included in plaintext in the function configuration. Instead, secret access can be used. -Before using a secret in a function, you need to [define a secret](/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/#set-secrets). After you have defined a secret, you can reference it in your function config. +Before using a secret in a function, you need to [define a secret](/[platform]/deploy-and-host/amplify-hosting/secrets-and-vars/#set-secrets). After you have defined a secret, you can reference it in your function config. ```ts title="amplify/functions/say-hello/resource.ts" import { defineFunction, secret } from '@aws-amplify/backend'; diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/branch-deployments/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/branch-deployments/index.mdx similarity index 100% rename from src/pages/[platform]/deploy-and-host/fullstack-branching/branch-deployments/index.mdx rename to src/pages/[platform]/deploy-and-host/amplify-hosting/branch-deployments/index.mdx diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/cross-account-deployments/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/cross-account-deployments/index.mdx similarity index 100% rename from src/pages/[platform]/deploy-and-host/fullstack-branching/cross-account-deployments/index.mdx rename to src/pages/[platform]/deploy-and-host/amplify-hosting/cross-account-deployments/index.mdx diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/custom-pipelines/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/custom-pipelines/index.mdx similarity index 100% rename from src/pages/[platform]/deploy-and-host/fullstack-branching/custom-pipelines/index.mdx rename to src/pages/[platform]/deploy-and-host/amplify-hosting/custom-pipelines/index.mdx diff --git a/src/pages/[platform]/deploy-and-host/amplify-hosting/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/index.mdx new file mode 100644 index 00000000000..5cf5570955b --- /dev/null +++ b/src/pages/[platform]/deploy-and-host/amplify-hosting/index.mdx @@ -0,0 +1,56 @@ +import { getChildPageNodes } from '@/utils/getChildPageNodes'; +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Amplify Hosting', + description: + 'Managed CI/CD and hosting for static and server-rendered apps. Auto-deploy from Git with per-branch environments and PR previews.', + route: '/[platform]/deploy-and-host/amplify-hosting', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export const getStaticPaths = async () => { + return getCustomStaticPath(meta.platforms); +}; + +export function getStaticProps(context) { + const childPageNodes = getChildPageNodes(meta.route); + return { + props: { + meta, + childPageNodes + } + }; +} + +AWS Amplify Hosting is a fully managed CI/CD and hosting service for static and server-side rendered apps. Connect your Git repository and Amplify builds, deploys, and serves your application on every push. + +Amplify Hosting supports frameworks like Next.js, React, Vue, Angular, Nuxt, and Gatsby. It provisions SSL certificates, manages custom domains, and handles cache invalidation automatically. + +## Key capabilities + +**Git-based deployments** — Push to your repository and Amplify builds and deploys both your frontend and backend resources together. Each branch gets its own environment. + +**PR previews** — Open a pull request and get a preview URL with the proposed changes deployed to an isolated environment. + +**Secrets and environment variables** — Store API keys, configuration values, and secrets that are injected at build time without committing them to your repository. + +**Multi-repo and monorepo support** — Deploy from monorepos with multiple apps, or coordinate deployments across separate repositories. + +**Custom CI/CD pipelines** — Override the default build process with your own pipeline configuration for advanced build requirements. + +**Cross-account deployments** — Deploy backend resources to different AWS accounts while keeping your hosting in a central account. + +## Get started + + diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/mono-and-multi-repos/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/mono-and-multi-repos/index.mdx similarity index 100% rename from src/pages/[platform]/deploy-and-host/fullstack-branching/mono-and-multi-repos/index.mdx rename to src/pages/[platform]/deploy-and-host/amplify-hosting/mono-and-multi-repos/index.mdx diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/monorepos/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/monorepos/index.mdx similarity index 100% rename from src/pages/[platform]/deploy-and-host/fullstack-branching/monorepos/index.mdx rename to src/pages/[platform]/deploy-and-host/amplify-hosting/monorepos/index.mdx diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/pr-previews/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/pr-previews/index.mdx similarity index 100% rename from src/pages/[platform]/deploy-and-host/fullstack-branching/pr-previews/index.mdx rename to src/pages/[platform]/deploy-and-host/amplify-hosting/pr-previews/index.mdx diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/secrets-and-vars/index.mdx similarity index 100% rename from src/pages/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/index.mdx rename to src/pages/[platform]/deploy-and-host/amplify-hosting/secrets-and-vars/index.mdx diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/share-resources/index.mdx b/src/pages/[platform]/deploy-and-host/amplify-hosting/share-resources/index.mdx similarity index 100% rename from src/pages/[platform]/deploy-and-host/fullstack-branching/share-resources/index.mdx rename to src/pages/[platform]/deploy-and-host/amplify-hosting/share-resources/index.mdx diff --git a/src/pages/[platform]/deploy-and-host/fullstack-branching/index.mdx b/src/pages/[platform]/deploy-and-host/fullstack-branching/index.mdx deleted file mode 100644 index 5b8432e4ee4..00000000000 --- a/src/pages/[platform]/deploy-and-host/fullstack-branching/index.mdx +++ /dev/null @@ -1,35 +0,0 @@ -import { getChildPageNodes } from '@/utils/getChildPageNodes'; -import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; - -export const meta = { - title: 'Fullstack workflows', - description: 'Overview of fullstack branching capabilities.', - route: '/[platform]/deploy-and-host/fullstack-branching', - platforms: [ - 'android', - 'angular', - 'flutter', - 'javascript', - 'nextjs', - 'react', - 'react-native', - 'swift', - 'vue' - ] -}; - -export const getStaticPaths = async () => { - return getCustomStaticPath(meta.platforms); -}; - -export function getStaticProps(context) { - const childPageNodes = getChildPageNodes(meta.route); - return { - props: { - meta, - childPageNodes - } - }; -} - - diff --git a/src/pages/[platform]/deploy-and-host/hosting/index.mdx b/src/pages/[platform]/deploy-and-host/hosting/index.mdx deleted file mode 100644 index 34867c80296..00000000000 --- a/src/pages/[platform]/deploy-and-host/hosting/index.mdx +++ /dev/null @@ -1,42 +0,0 @@ -import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; - -export const meta = { - title: 'Frontend hosting', - description: - 'Host static and server-rendered web apps built with modern JS frameworks like Next.js, Vue, and React.', - platforms: [ - 'android', - 'angular', - 'flutter', - 'javascript', - 'nextjs', - 'react', - 'react-native', - 'swift', - 'vue' - ] -}; - -export const getStaticPaths = async () => { - return getCustomStaticPath(meta.platforms); -}; - -export function getStaticProps(context) { - return { - props: { - meta - } - }; - -} - -AWS Amplify Hosting is a fully managed CI/CD and hosting service for fast, secure, and reliable static and server-side rendered apps that scale with your business. This service supports modern web frameworks such as React, Angular, Vue, Next.js, Nuxt.js, Gatsby, and more. - -Because AWS Amplify Hosting is a fully managed service, its documentation lives on the AWS Documentation site. To learn about hosting features such as custom domains, redirects, and more, please visit the Hosting documentation. - - - View Hosting Docs - diff --git a/src/pages/[platform]/deploy-and-host/index.mdx b/src/pages/[platform]/deploy-and-host/index.mdx index f7fcc4af346..cef6d31f3ae 100644 --- a/src/pages/[platform]/deploy-and-host/index.mdx +++ b/src/pages/[platform]/deploy-and-host/index.mdx @@ -1,5 +1,6 @@ import { getChildPageNodes } from '@/utils/getChildPageNodes'; import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; +import { Card } from '@aws-amplify/ui-react'; export const meta = { title: 'Deployment', @@ -32,4 +33,23 @@ export function getStaticProps(context) { }; } - +Amplify provides two ways to deploy and host your frontend application. You can use fully managed hosting through the Amplify console, or deploy to your own AWS account with full infrastructure control. + +## Choose your hosting approach + + + + **[Amplify Hosting](/[platform]/deploy-and-host/amplify-hosting/)** + + Managed CI/CD and hosting. Connect your Git repository and Amplify builds, deploys, and serves your app on every push. Includes custom domains, branch previews, and SSR support. + + + **[Self-managed hosting](/[platform]/deploy-and-host/self-hosting/)** + + Deploy to your AWS account with `defineHosting()`. Full AWS CDK control over Amazon CloudFront, Amazon S3, and Lambda@Edge. Use your own CI/CD pipeline or provision one with `definePipeline()`. + + + +## Cloud sandbox environments + +Regardless of which hosting approach you choose, you use [cloud sandbox environments](/[platform]/deploy-and-host/sandbox-environments/) for local development. Each team member gets an isolated set of backend resources that deploy in seconds, giving you a personal cloud environment to iterate against without affecting shared environments. diff --git a/src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx index def0f674872..dd6ad9c3235 100644 --- a/src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx @@ -130,7 +130,7 @@ The `secret()` function can only be used in specific places in your backend defi -To deploy a backend that uses `secret()` references via Amplify hosting, the secret values must be [configured for the Amplify app or branch](/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars) +To deploy a backend that uses `secret()` references via Amplify hosting, the secret values must be [configured for the Amplify app or branch](/[platform]/deploy-and-host/amplify-hosting/secrets-and-vars) diff --git a/src/pages/[platform]/deploy-and-host/self-hosting/define-hosting/index.mdx b/src/pages/[platform]/deploy-and-host/self-hosting/define-hosting/index.mdx new file mode 100644 index 00000000000..db12245b78b --- /dev/null +++ b/src/pages/[platform]/deploy-and-host/self-hosting/define-hosting/index.mdx @@ -0,0 +1,258 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Configure hosting', + description: 'Customize your hosting infrastructure with domains, AWS WAF, compute settings, and AWS CDK escape hatches.', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export const getStaticPaths = async () => { + return getCustomStaticPath(meta.platforms); +}; + +export function getStaticProps(context) { + return { + props: { + meta + } + }; +} + +{/* PREVIEW-BANNER-START */} + + +**This feature is in preview** and part of our [RFC](https://github.com/aws-amplify/amplify-backend/issues/3211). It is not recommended for production workloads yet, and APIs may change before general availability. See the RFC for instructions on installing the preview release. + + +{/* PREVIEW-BANNER-END */} + +In this guide, you will learn how to customize your self-hosted infrastructure with custom domains, WAF rules, compute and CDN configuration, custom adapters, and CDK escape hatches. + +## Framework detection + +By default, `defineHosting()` auto-detects your framework from `package.json`. You can override this explicitly: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + framework: 'nextjs', + buildCommand: 'npm run build', + buildOutputDir: '.next' +}); +``` + +The `buildCommand` and `buildOutputDir` options let you customize the build step if your project uses a non-standard setup. + +## Overriding the build output directory + +If your framework outputs to a non-standard directory, you can override `buildOutputDir` without changing any other defaults: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + buildOutputDir: './dist', +}); +``` + +This tells the construct where to find compiled assets after the build step completes. + +## Adding a custom domain + +Attach a custom domain to your Amazon CloudFront distribution with automatic ACM certificate provisioning: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + domain: { + domainName: 'app.example.com', + hostedZone: 'example.com' + } +}); +``` + +The construct creates a TLS certificate in `us-east-1` (required for Amazon CloudFront), validates it via DNS, and adds the appropriate Amazon Route 53 alias record. + +## Enabling WAF protection + +Add AWS WAF to your distribution to protect against common web exploits: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + domain: { + domainName: 'app.example.com', + hostedZone: 'example.com' + }, + waf: { + enabled: true + } +}); +``` + +This attaches an AWS WAF Web ACL with AWS managed rule groups to your Amazon CloudFront distribution. You can further customize WAF rules using CDK escape hatches on the generated resources. + +## Tuning compute settings + +Control the Lambda function that handles server-side rendering: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + compute: { + memorySize: 1024, + timeout: 30, + runtime: 'nodejs20.x' + } +}); +``` + +The `memorySize` is in MB, and `timeout` is in seconds. Increase these values for applications with heavy server-side rendering workloads. + +## Customizing CDN behavior + +Fine-tune Amazon CloudFront caching and behavior settings: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + cdn: { + cachePolicy: { + defaultTtl: 86400, + maxTtl: 31536000 + }, + geoRestriction: { + restrictionType: 'whitelist', + locations: ['US', 'CA', 'GB', 'DE'] + } + } +}); +``` + +## Adding a content security policy + +Set a Content-Security-Policy header on all responses from your Amazon CloudFront distribution: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + cdn: { + contentSecurityPolicy: "default-src 'self'; script-src 'self' 'unsafe-inline'", + }, +}); +``` + +You can combine this with the other `cdn` options like `cachePolicy` and `geoRestriction` in the same object. + +## Configuring logging + +Enable access logging to an Amazon S3 bucket for your Amazon CloudFront distribution: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + logging: { + enabled: true + } +}); +``` + +## Configuring storage + +Control how the Amazon S3 bucket backing your deployment stores and retains data: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + storage: { + encryption: 'KMS', + retainOnDelete: true, + buildRetentionDays: 30, + }, +}); +``` + +The `encryption` option sets the server-side encryption type (`S3` or `KMS`). Set `retainOnDelete` to `true` to preserve the Amazon S3 bucket when the stack is deleted. The `buildRetentionDays` value automatically removes old build artifacts after the specified number of days. + +## Using a custom adapter + +If your framework is not natively supported, provide a custom adapter: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; +import { myCustomAdapter } from './my-adapter'; + +export const hosting = defineHosting({ + customAdapter: myCustomAdapter +}); +``` + +A custom adapter is a function that transforms your framework's build output into the format expected by the hosting construct (static assets and a server handler). + +## AWS CDK escape hatches + +The `defineHosting()` return value exposes the underlying AWS CDK resources. Use these to apply any customization not covered by the high-level API: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting(); + +const { bucket, distribution, distributionUrl } = hosting.resources; + +// Add a custom response header to the distribution +distribution.addBehavior('/api/*', origin, { + viewerProtocolPolicy: ViewerProtocolPolicy.HTTPS_ONLY +}); + +// Access the underlying Amazon S3 bucket +bucket.addLifecycleRule({ + expiration: Duration.days(90), + prefix: 'logs/' +}); +``` + +You can also create additional AWS CDK stacks scoped to your hosting: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; +import * as wafv2 from 'aws-cdk-lib/aws-wafv2'; + +export const hosting = defineHosting(); + +const wafStack = hosting.createStack('WafStack'); + +new wafv2.CfnWebACL(wafStack, 'CustomWebAcl', { + defaultAction: { allow: {} }, + scope: 'CLOUDFRONT', + visibilityConfig: { + cloudWatchMetricsEnabled: true, + metricName: 'customWaf', + sampledRequestsEnabled: true + }, + rules: [] +}); +``` + +## Next steps + +- [Set up a CI/CD pipeline](/[platform]/deploy-and-host/self-hosting/define-pipeline/) to automate deployments +- [Use an external CI/CD pipeline](/[platform]/deploy-and-host/self-hosting/external-pipelines/) with GitHub Actions or GitLab CI diff --git a/src/pages/[platform]/deploy-and-host/self-hosting/define-pipeline/index.mdx b/src/pages/[platform]/deploy-and-host/self-hosting/define-pipeline/index.mdx new file mode 100644 index 00000000000..0eb956a48ef --- /dev/null +++ b/src/pages/[platform]/deploy-and-host/self-hosting/define-pipeline/index.mdx @@ -0,0 +1,311 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Set up a CI/CD pipeline', + description: 'Automate deployments with a self-mutating AWS CodePipeline.', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export const getStaticPaths = async () => { + return getCustomStaticPath(meta.platforms); +}; + +export function getStaticProps(context) { + return { + props: { + meta + } + }; +} + +{/* PREVIEW-BANNER-START */} + + +**This feature is in preview** and part of our [RFC](https://github.com/aws-amplify/amplify-backend/issues/3211). It is not recommended for production workloads yet, and APIs may change before general availability. See the RFC for instructions on installing the preview release. + + +{/* PREVIEW-BANNER-END */} + +In this guide, you will learn how to define a CI/CD pipeline that automatically deploys your application on every push, with support for multi-stage deployments, approval gates, and bake times. + +## Defining a basic pipeline + +Create a pipeline definition alongside your hosting configuration. The `definePipeline()` function provisions an AWS CodePipeline V2 that watches your repository and deploys on every push. + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + triggerOnPush: true + }, + branches: [ + { + branch: 'main', + stages: [ + { name: 'production' } + ] + } + ] +}); +``` + +The `connectionArn` references an AWS CodeConnections connection to your Git provider (GitHub, Bitbucket, or GitLab). Create one in the AWS Console under Developer Tools > Connections. + +## Multi-stage deployments + +Deploy through multiple stages to catch issues before they reach production: + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + triggerOnPush: true + }, + branches: [ + { + branch: 'main', + stages: [ + { name: 'staging' }, + { name: 'production', requireApproval: true, bakeTime: 30 } + ] + } + ] +}); +``` + +The `requireApproval` option pauses the pipeline before deploying to that stage, waiting for manual approval in the AWS CodePipeline console. The `bakeTime` value (in minutes) adds a waiting period after deployment to monitor for errors before proceeding. + +## Cross-account deployments + +Deploy stages to different AWS accounts by specifying `env` on each stage and enabling `crossAccountKeys` for KMS-encrypted artifact sharing: + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + }, + crossAccountKeys: true, + branches: [{ + branch: 'main', + stages: [ + { name: 'beta', env: { account: '111111111111', region: 'us-east-1' } }, + { name: 'prod', env: { account: '222222222222', region: 'us-west-2' } }, + ], + }], +}); +``` + +The `crossAccountKeys` option creates a KMS key that can be shared across accounts for encrypting pipeline artifacts. Each target account must have a trust relationship with the pipeline account. Refer to the [AWS CDK Pipelines documentation](https://docs.aws.amazon.com/cdk/v2/guide/cdk_pipeline.html) for bootstrapping details. + +## Per-stage configuration + +Use `getStageConfig()` in your hosting definition to vary configuration by stage. This lets you use different domains, compute sizes, or feature flags per environment. + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; +import { getStageConfig } from '@aws-amplify/hosting/pipeline'; + +const config = getStageConfig<{ + domain: string; + memorySize: number; +}>(); + +export const hosting = defineHosting({ + domain: { + domainName: config.domain, + hostedZone: 'example.com' + }, + compute: { + memorySize: config.memorySize + } +}); +``` + +Then provide the config values in your pipeline stages: + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + triggerOnPush: true + }, + branches: [ + { + branch: 'main', + stages: [ + { + name: 'staging', + config: { + domain: 'staging.example.com', + memorySize: 512 + } + }, + { + name: 'production', + requireApproval: true, + bakeTime: 30, + config: { + domain: 'app.example.com', + memorySize: 1024 + } + } + ] + } + ] +}); +``` + +## Filtering trigger paths + +Limit which file changes trigger a pipeline run using `triggerFilters`: + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + triggerOnPush: true, + triggerFilters: ['src/**', 'amplify/**', 'package.json'] + }, + branches: [ + { + branch: 'main', + stages: [{ name: 'production' }] + } + ] +}); +``` + +## Disabling automatic triggers + +By default the pipeline runs on every push to the tracked branch. Set `triggerOnPush` to `false` if you want to trigger deployments only through the AWS CodePipeline console or API: + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + triggerOnPush: false, + }, + branches: [{ branch: 'main', stages: [{ name: 'prod' }] }], +}); +``` + +## Custom build configuration + +Override the default synth step commands, compute type, or environment variables: + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + triggerOnPush: true + }, + synth: { + commands: [ + 'npm ci', + 'npm run build', + 'npx ampx deploy --identifier $STAGE_NAME --frontend --backend' + ], + computeType: 'large', + dockerEnabled: true, + env: { + NODE_OPTIONS: '--max-old-space-size=4096' + } + }, + branches: [ + { + branch: 'main', + stages: [{ name: 'production' }] + } + ] +}); +``` + +The `computeType` option accepts `small`, `medium`, `large`, or `xlarge` and controls the CodeBuild instance size. Enable `dockerEnabled` if your build process requires Docker (for example, building container images). + +## Custom install commands and output directory + +Use `installCommands` to run setup steps before the synth commands, and `primaryOutputDirectory` to specify a non-default CDK output location: + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + }, + synth: { + installCommands: ['npm ci', 'npx playwright install'], + commands: ['npm run build', 'npx cdk synth'], + primaryOutputDirectory: 'infrastructure/cdk.out', + }, + branches: [{ branch: 'main', stages: [{ name: 'prod' }] }], +}); +``` + +The `installCommands` run before `commands` in the synth step. Use them for dependency installation or tool setup that must complete before the build. The `primaryOutputDirectory` tells the pipeline where to find the synthesized cloud assembly if your CDK app outputs to a custom path. + +## Deploying the pipeline + +Deploy the pipeline itself with the `--pipeline` flag: + +```bash title="Terminal" +npx ampx deploy --identifier production --pipeline +``` + +Once deployed, the pipeline is self-mutating. Any changes to `amplify/pipeline.ts` are picked up on the next push and the pipeline updates itself. + +## Disabling self-mutation + +By default the pipeline updates itself when you change `amplify/pipeline.ts`. If you manage pipeline updates through a separate process (for example, a dedicated infrastructure repository), disable self-mutation: + +```ts title="amplify/pipeline.ts" +import { definePipeline } from '@aws-amplify/hosting/pipeline'; + +export const pipeline = definePipeline({ + source: { + repo: 'my-org/my-app', + connectionArn: 'arn:aws:codeconnections:us-east-1:123456789012:connection/abc-123', + }, + selfMutation: false, + branches: [{ branch: 'main', stages: [{ name: 'prod' }] }], +}); +``` + +With `selfMutation` set to `false`, changes to the pipeline definition require a manual `npx ampx deploy --pipeline` to take effect. + +## Next steps + +- [Configure hosting](/[platform]/deploy-and-host/self-hosting/define-hosting/) to customize domains, WAF, and compute +- [Use an external CI/CD pipeline](/[platform]/deploy-and-host/self-hosting/external-pipelines/) if you prefer GitHub Actions or GitLab CI diff --git a/src/pages/[platform]/deploy-and-host/self-hosting/external-pipelines/index.mdx b/src/pages/[platform]/deploy-and-host/self-hosting/external-pipelines/index.mdx new file mode 100644 index 00000000000..e6ff24ba49d --- /dev/null +++ b/src/pages/[platform]/deploy-and-host/self-hosting/external-pipelines/index.mdx @@ -0,0 +1,196 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Use an external CI/CD pipeline', + description: 'Deploy with GitHub Actions, GitLab CI, or any CI runner.', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export const getStaticPaths = async () => { + return getCustomStaticPath(meta.platforms); +}; + +export function getStaticProps(context) { + return { + props: { + meta + } + }; +} + +{/* PREVIEW-BANNER-START */} + + +**This feature is in preview** and part of our [RFC](https://github.com/aws-amplify/amplify-backend/issues/3211). It is not recommended for production workloads yet, and APIs may change before general availability. See the RFC for instructions on installing the preview release. + + +{/* PREVIEW-BANNER-END */} + +In this guide, you will learn how to deploy your self-hosted application using GitHub Actions, GitLab CI, or any CI runner that can execute shell commands with AWS credentials. + +## Understanding deployment flags + +The `ampx deploy` command accepts flags that control which stacks are deployed: + +| Flag | Description | +| --- | --- | +| `--backend` | Deploy only the backend stack (auth, data, functions) | +| `--frontend` | Deploy only the frontend hosting stack | +| `--pipeline` | Deploy only the pipeline stack | +| (no flag) | Deploy all stacks | + +In most CI workflows, you deploy the backend first, then the frontend. This ensures `amplify_outputs.json` is generated before the frontend build bundles it. + +## Deploying with GitHub Actions + +Configure AWS credentials using the `aws-actions/configure-aws-credentials` action with an IAM role that has permissions to deploy AWS CDK stacks. + +```yaml title=".github/workflows/deploy.yml" +name: Deploy + +on: + push: + branches: [main] + +permissions: + id-token: write + contents: read + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - run: npm ci + + - uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsDeployRole + aws-region: us-east-1 + + - name: Deploy backend + run: npx ampx deploy --identifier production --backend + + - name: Deploy frontend + run: npx ampx deploy --identifier production --frontend +``` + + + +The IAM role must have permissions for AWS CloudFormation, Amazon S3, Amazon CloudFront, AWS Lambda, and any other services your stacks use. Use OIDC federation to avoid storing long-lived credentials as secrets. + + + +## Deploying with GitLab CI + +Use GitLab's native OIDC support or set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as CI/CD variables in your project settings. + +```yaml title=".gitlab-ci.yml" +stages: + - deploy + +deploy: + stage: deploy + image: node:20 + rules: + - if: $CI_COMMIT_BRANCH == "main" + before_script: + - npm ci + script: + - npx ampx deploy --identifier production --backend + - npx ampx deploy --identifier production --frontend + variables: + AWS_REGION: us-east-1 +``` + +## Deploying with any CI runner + +The `ampx deploy` command works in any environment with Node.js and valid AWS credentials. The minimum requirements are: + +- Node.js 18 or later +- AWS credentials available as environment variables or through an IAM role +- The `@aws-amplify/hosting` package installed in your project + +```bash title="Generic CI script" +npm ci +npx ampx deploy --identifier production --backend +npx ampx deploy --identifier production --frontend +``` + +## Splitting backend and frontend across jobs + +For faster feedback, run backend and frontend deployments in separate parallel jobs (with the frontend waiting for the backend to complete): + +```yaml title=".github/workflows/deploy.yml" +name: Deploy + +on: + push: + branches: [main] + +permissions: + id-token: write + contents: read + +jobs: + deploy-backend: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + - run: npm ci + - uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsDeployRole + aws-region: us-east-1 + - run: npx ampx deploy --identifier production --backend + + deploy-frontend: + runs-on: ubuntu-latest + needs: deploy-backend + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + - run: npm ci + - uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsDeployRole + aws-region: us-east-1 + - run: npx ampx deploy --identifier production --frontend +``` + +## Environment-specific deployments + +Use branch names or environment variables to deploy to different environments: + +```yaml title=".github/workflows/deploy.yml" +- name: Deploy + run: npx ampx deploy --identifier ${{ github.ref_name == 'main' && 'production' || 'staging' }} +``` + +## Next steps + +- [Configure hosting](/[platform]/deploy-and-host/self-hosting/define-hosting/) to customize domains, AWS WAF, and compute settings +- [Set up a built-in pipeline](/[platform]/deploy-and-host/self-hosting/define-pipeline/) if you prefer a fully managed AWS CodePipeline diff --git a/src/pages/[platform]/deploy-and-host/self-hosting/frameworks/index.mdx b/src/pages/[platform]/deploy-and-host/self-hosting/frameworks/index.mdx new file mode 100644 index 00000000000..bc5ddeb80db --- /dev/null +++ b/src/pages/[platform]/deploy-and-host/self-hosting/frameworks/index.mdx @@ -0,0 +1,99 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Supported frameworks', + description: 'Frameworks supported by self-managed hosting and their feature capabilities.', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export const getStaticPaths = async () => { + return getCustomStaticPath(meta.platforms); +}; + +export function getStaticProps(context) { + return { + props: { + meta + } + }; +} + +{/* PREVIEW-BANNER-START */} + + +**This feature is in preview** and part of our [RFC](https://github.com/aws-amplify/amplify-backend/issues/3211). It is not recommended for production workloads yet, and APIs may change before general availability. See the RFC for instructions on installing the preview release. + + +{/* PREVIEW-BANNER-END */} + +When you call `defineHosting()`, the construct auto-detects your framework by inspecting `package.json` dependencies. Each framework maps to a specific build adapter that determines which hosting features are available. + +## Detected frameworks + +The following frameworks are detected automatically: + +**Next.js** — Detected when `next` is present in your dependencies. Uses the `@opennextjs/aws` adapter to deploy server-rendered pages, API routes, middleware, and image optimization as Lambda@Edge or AWS Lambda functions behind Amazon CloudFront. + +**Nuxt / Nitro** — Detected from `nuxt` or `nitropack` in dependencies. Uses the Nitro server engine with an AWS Lambda adapter for server routes, middleware, and hybrid rendering. + +**Astro** — Detected when `astro` is present in your dependencies. Supports both static output and on-demand server rendering through its SSR adapter. + +**Static / React SPA / Vite / CRA** — Fallback when no server framework is detected. Your app is built as static files and served directly from Amazon S3 through Amazon CloudFront with no server compute required. + +**Custom frameworks** — If your framework is not auto-detected, use the `customAdapter` option in `defineHosting()` to provide your own build and routing logic: + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting({ + customAdapter: { + buildCommand: 'npm run build', + outputDirectory: './dist', + serverEntry: './dist/server/entry.mjs' + } +}); +``` + +## Feature matrix + +The table below shows which features each framework supports when deployed with self-managed hosting. + +| Feature | Next.js | Nuxt / Nitro | Astro | Static / SPA | +|---------|---------|--------------|-------|--------------| +| Static hosting | ✅ | ✅ | ✅ | ✅ | +| Server-side rendering | ✅ | ✅ | ✅ | — | +| Streaming SSR | ✅ | ✅ | ✅ | — | +| Streaming (RSC) | ✅ | — | — | — | +| Middleware (edge) | ✅ | ✅ | ✅ | — | +| Image optimization | ✅ | ✅ | ✅ | — | +| ISR with revalidation | ✅ | — | — | — | +| SWR (stale-while-revalidate) | ✅ | ✅ | — | — | +| Atomic deployments | ✅ | ✅ | ✅ | ✅ | +| Custom domains | ✅ | ✅ | ✅ | ✅ | +| WAF | ✅ | ✅ | ✅ | ✅ | + +## Feature details + +**Streaming SSR** enables your application to send HTML to the browser in chunks as each component resolves, rather than waiting for the full page. This reduces time-to-first-byte and lets users see content sooner. + +**Streaming (RSC)** is a Next.js-specific capability that streams React Server Component payloads to the client. Server components render on the server without client-side JavaScript, and their output streams to the browser as it becomes ready. + +**ISR with revalidation** allows Next.js pages to be statically generated at build time and then regenerated on-demand after a configured time interval. Subsequent requests receive the updated page without a full redeploy. + +**SWR (stale-while-revalidate)** serves cached responses immediately while fetching updated content in the background. The next request after revalidation completes receives the fresh response. + +**Middleware (edge)** runs code at Amazon CloudFront edge locations before the request reaches your origin server. Use it for redirects, rewrites, authentication checks, A/B testing, and header manipulation. + +**Image optimization** automatically resizes, reformats, and caches images on-demand through an AWS Lambda function. Requests for images are processed at the configured quality and dimensions, then served through the CDN. + +**Atomic deployments** ensure that all assets for a deployment become available at the same instant. There is no window where old and new assets are mixed, preventing broken references during rollouts. diff --git a/src/pages/[platform]/deploy-and-host/self-hosting/getting-started/index.mdx b/src/pages/[platform]/deploy-and-host/self-hosting/getting-started/index.mdx new file mode 100644 index 00000000000..299306a6928 --- /dev/null +++ b/src/pages/[platform]/deploy-and-host/self-hosting/getting-started/index.mdx @@ -0,0 +1,101 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Getting started with self-hosting', + description: 'Install the hosting package and deploy your first app.', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export const getStaticPaths = async () => { + return getCustomStaticPath(meta.platforms); +}; + +export function getStaticProps(context) { + return { + props: { + meta + } + }; +} + +{/* PREVIEW-BANNER-START */} + + +**This feature is in preview** and part of our [RFC](https://github.com/aws-amplify/amplify-backend/issues/3211). It is not recommended for production workloads yet, and APIs may change before general availability. See the RFC for instructions on installing the preview release. + + +{/* PREVIEW-BANNER-END */} + +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](/[platform]/start/quickstart/) first. + +## Installing the hosting package + +Add the `@aws-amplify/hosting` package to your project: + +```bash title="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. + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting(); +``` + +By default, the framework is auto-detected from your `package.json`. Supported frameworks include `nextjs`, `nuxt`, `astro`, `nitro`, `spa`, and `static`. You can optionally override the framework detection if needed. + +## Deploying your application + +Run `ampx deploy` to synthesize and deploy both your backend and hosting stacks: + +```bash title="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: + +```bash title="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](/[platform]/deploy-and-host/self-hosting/define-hosting/) to add custom domains, WAF, and CDN tuning +- [Set up a CI/CD pipeline](/[platform]/deploy-and-host/self-hosting/define-pipeline/) with CodePipeline +- [Use an external CI/CD pipeline](/[platform]/deploy-and-host/self-hosting/external-pipelines/) with GitHub Actions or GitLab CI diff --git a/src/pages/[platform]/deploy-and-host/self-hosting/index.mdx b/src/pages/[platform]/deploy-and-host/self-hosting/index.mdx new file mode 100644 index 00000000000..cb42634ffa4 --- /dev/null +++ b/src/pages/[platform]/deploy-and-host/self-hosting/index.mdx @@ -0,0 +1,69 @@ +import { getChildPageNodes } from '@/utils/getChildPageNodes'; +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Self-managed hosting (Preview)', + description: 'Deploy your frontend to your own AWS account with full AWS CDK control.', + route: '/[platform]/deploy-and-host/self-hosting', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export const getStaticPaths = async () => { + return getCustomStaticPath(meta.platforms); +}; + +export function getStaticProps(context) { + const childPageNodes = getChildPageNodes(meta.route); + return { + props: { + meta, + childPageNodes + } + }; +} + +{/* PREVIEW-BANNER-START */} + + +**This feature is in preview** and part of our [RFC](https://github.com/aws-amplify/amplify-backend/issues/3211). It is not recommended for production workloads yet, and APIs may change before general availability. See the RFC for instructions on installing the preview release. + + +{/* PREVIEW-BANNER-END */} + +Self-managed hosting gives you full ownership of your frontend infrastructure. You deploy to your own AWS account using AWS CDK constructs, giving you complete control over Amazon S3 buckets, Amazon CloudFront distributions, Lambda@Edge functions, and every other resource in your stack. + +## How it works + +You define your hosting configuration in `amplify/hosting.ts` using `defineHosting()`. This generates an AWS CDK stack with all the resources needed to serve your application. You deploy with the `ampx deploy` CLI command, which synthesizes and deploys both backend and frontend stacks to your AWS account. + +```ts title="amplify/hosting.ts" +import { defineHosting } from '@aws-amplify/hosting'; + +export const hosting = defineHosting(); +``` + +## Deployment options + +You have three ways to deploy self-hosted applications: + +**Manual deployment** with `ampx deploy` runs directly from your local machine or any environment with AWS credentials. + +**Built-in pipeline** with `definePipeline()` provisions a self-mutating AWS CodePipeline V2 that deploys on every push to your repository. + +**External CI/CD** using GitHub Actions, GitLab CI, or any CI runner that can execute `ampx deploy` with the appropriate flags. + +## When to use self-managed hosting + +Self-managed hosting is the right choice when you need direct access to your infrastructure resources, want to customize CDN behavior, require AWS WAF protection, or need to integrate hosting into an existing AWS organization with specific compliance requirements. + + diff --git a/src/pages/[platform]/develop-with-ai/mcp-server/amplify-workflows/index.mdx b/src/pages/[platform]/develop-with-ai/mcp-server/amplify-workflows/index.mdx index c8dae7c9b05..d1bb1062915 100644 --- a/src/pages/[platform]/develop-with-ai/mcp-server/amplify-workflows/index.mdx +++ b/src/pages/[platform]/develop-with-ai/mcp-server/amplify-workflows/index.mdx @@ -266,6 +266,7 @@ The workflow guides continuous integration and deployment setup: - Setting up branch-based deployments (preview, staging, production) - Implementing pull request previews - Configuring build settings and environment variables +- Deploying to your own AWS account with self-managed hosting and CDK **Example prompt:** ``` @@ -318,7 +319,7 @@ to GitHub. I also want preview deployments for pull requests. ``` Your AI assistant uses the **Deployment Guide workflow** to: -1. Connect your GitHub repository to Amplify Hosting +1. Connect your GitHub repository to Amplify Hosting, or configure self-managed hosting with CDK 2. Configure branch-based deployments 3. Set up pull request previews 4. Configure production environment settings diff --git a/src/pages/[platform]/how-amplify-works/concepts/index.mdx b/src/pages/[platform]/how-amplify-works/concepts/index.mdx index b23d2735a01..26a17920508 100644 --- a/src/pages/[platform]/how-amplify-works/concepts/index.mdx +++ b/src/pages/[platform]/how-amplify-works/concepts/index.mdx @@ -30,7 +30,7 @@ export function getStaticProps(context) { } -AWS Amplify Gen 2 uses a TypeScript-based, code-first developer experience (DX) for defining backends. The Gen 2 DX offers a unified Amplify developer experience with hosting, backend, and UI-building capabilities and a code-first approach. Amplify empowers frontend developers to deploy cloud infrastructure by simply expressing their app’s data model, business logic, authentication, and authorization rules completely in TypeScript. Amplify automatically configures the correct cloud resources and removes the requirement to stitch together underlying AWS services. +AWS Amplify uses a TypeScript-based, code-first developer experience (DX) for defining backends. It offers a unified Amplify developer experience with hosting, backend, and UI-building capabilities and a code-first approach. Amplify empowers frontend developers to deploy cloud infrastructure by expressing their app's data model, business logic, authentication, and authorization rules completely in TypeScript. Amplify automatically configures the correct cloud resources and removes the requirement to stitch together underlying AWS services. ## Capabilities @@ -38,25 +38,27 @@ You can use Amplify for end-to-end fullstack development. ### Build fullstack apps with TypeScript -With the Gen 2 DX, you can provision backend infrastructure by authoring TypeScript. In the following diagram, the box at the bottom (outlined in pink), highlights the main difference in how you provision infrastructure compared to Gen 1. In Gen 1, you would use Studio's console or the CLI to provision infrastructure; in Gen 2, you author TypeScript code in files following a file-based convention (such as `amplify/auth/resource.ts` or `amplify/auth/data.ts`). With TypeScript types and classes for resources, you gain strict typing and IntelliSense in Visual Studio Code to prevent errors. A breaking change in the backend code immediately reflects as a type error in the co-located frontend code. The file-based convention follows the "convention over configuration" paradigm—you know exactly where to look for resource definitions when you group them by type in separate files. +You provision backend infrastructure by authoring TypeScript code in files following a file-based convention (such as `amplify/auth/resource.ts` or `amplify/data/resource.ts`). With TypeScript types and classes for resources, you gain strict typing and IntelliSense in Visual Studio Code to prevent errors. A breaking change in the backend code immediately reflects as a type error in the co-located frontend code. The file-based convention follows the "convention over configuration" paradigm. You know exactly where to look for resource definitions when you group them by type in separate files. ![How Amplify capabilities can be used together or independently.](/images/gen2/how-amplify-works/amplify-flow.png) ### Faster local development -Per-developer cloud sandbox environments are optimized for faster iterations. Each developer on a team gets an isolated cloud development environment against which they can test their changes. These cloud sandbox environments are meant for local development only, but they deploy high-fidelity AWS backends while you build. Depending on the workflow, iterative updates are now deployed up to 8X faster than Gen 1 deployments. In the diagram below, four developers are able to work on fullstack features independently without disrupting each other's environments. +Per-developer cloud sandbox environments are optimized for faster iterations. Each developer on a team gets an isolated cloud development environment against which they can test their changes. These cloud sandbox environments are meant for local development only, but they deploy high-fidelity AWS backends while you build. In the diagram below, four developers are able to work on fullstack features independently without disrupting each other's environments. ![How cloud sandbox environments work.](/images/gen2/how-amplify-works/sandbox.png) ### Fullstack Git-based environments -All shared environments (such as `production`, `staging`, `gamma`) map 1:1 to Git branches in your repository. New features can be tested in ephemeral environments with pull request previews (or feature branches) before they are merged into production. Unlike the Gen 1 experience, which requires users to configure a number of steps in the CLI or Console to set up a fullstack environment, the Gen 2 experience is zero-config. Because of our code-first approach, the Git repository is always the source of truth for the state of the fullstack app—all backend resources are defined as code for reproducibility and portability across branches. This, along with central management of environment variables and secrets, simplifies the promotion workflow from lower to upper environments. +When using Amplify Hosting, all shared environments (such as `production`, `staging`, `gamma`) map 1:1 to Git branches in your repository. New features can be tested in ephemeral environments with pull request previews (or feature branches) before they are merged into production. Because of the code-first approach, the Git repository is always the source of truth for the state of the fullstack app. All backend resources are defined as code for reproducibility and portability across branches. This, along with central management of environment variables and secrets, simplifies the promotion workflow from lower to upper environments. ![How fullstack deployments work.](/images/gen2/how-amplify-works/fullstack.png) +If you prefer to manage your own infrastructure, you can use self-managed hosting to deploy your frontend and backend to your own AWS account. You get full CDK control over CloudFront, S3, and Lambda@Edge, and you can use your own CI/CD pipelines or provision one with `definePipeline()`. + ### Unified management console -All branches can be managed in the new Amplify console. The Amplify Gen 2 console provides a single place for you to manage your builds, hosting settings (such as custom domains), deployed resources (such as data browser or user management), and environment variables and secrets. Even though you can access deployed resources directly in other AWS service consoles, the Amplify console will offer a first-party experience for the categories almost every app needs—data, auth, storage, and functions. For example, with Data, Amplify offers an API playground and a data manager (coming soon) with relationship building, seed data generation, and file upload capabilities. +All branches can be managed in the Amplify console. It provides a single place for you to manage your builds, hosting settings (such as custom domains), deployed resources (such as data browser or user management), and environment variables and secrets. You can access deployed resources directly in other AWS service consoles, but the Amplify console offers a first-party experience for the categories almost every app needs: data, auth, storage, and functions. For example, with Data, Amplify offers an API playground and a data manager with relationship building, seed data generation, and file upload capabilities.