feat: gen2 backend and datastore migration guides#8570
Merged
Conversation
Restructure the migrate-to-gen2 page into a landing page with two child pages: - Migrate an existing Gen 1 Application: full step-by-step migration guide including overall approach, prerequisites, modernization, 5-step process (assess, lock, generate, deploy, refactor), troubleshooting, and migration tool feature coverage - Build a new Gen 2 Application: Gen 1 vs Gen 2 feature matrix tables for auth, data, storage, functions, and other categories Add migration guide images to public/images/gen2-migration/ and update directory.mjs to register the new child pages.
- Add validation tables to lock, generate, and refactor steps - Show IAM policy JSON attached during lock step - Improve generate and refactor step descriptions - Restructure post-generate manual edits as Post Generate | <edit> headings - Add function secrets reference link in a Callout - Fix function secrets image size
- Rename 'Example assess report' to 'Example assessment' - Make validation tables collapsable with Accordion - Remove commas from partially supported feature entries
Add new child page covering Gen 1 to Gen 2 CLI command mapping,
custom pipeline setup for non-Git workflows, and UI Builder
migration from Studio to Figma Plugin. Also fix {Group} escaping
in feature coverage and restructure feature coverage as nested
CLI command lists with collapsible accordions.
- Merge CLI guide content into migrate-existing-app page - Remove standalone cli-guide page - Add UI Builder migration as separate child page - Rename feature matrix tile to Feature Parity - Various content edits: remove redundant sections, fix formatting, improve stateless/stateful resource headings
- Merge feature coverage and feature matrix into single 4-column tables (Feature | Gen 1 | Gen 2 | Migration Tool) - Add phase indicators for partial support (generate/refactor) - Replace feature coverage in migrate-existing-app with link - Move feature coverage link to top after Overall Approach - Split MFA and Analytics into separate rows - Update Data section migration tool values - Add block quote legend with bullet explanations
- Add Custom (CDK) and Custom (CFN) rows to Other categories - Link Custom (CDK) to custom resources docs - Link Custom (CFN) to CfnInclude docs - Mark both as unsupported by migration tool
- Restructure Backend Migration section with Generate and Refactor subsections and expanded descriptions - Move Frontend to its own top-level section - Consolidate Feature Parity page with Backend Categories and Tooling and Workflows groupings - Move CLI command mapping and UI Builder to Feature Parity page - Move Custom pipeline to its own child page - Remove standalone UI Builder page - Add collapsible Migration Tool legend - Add Data schema and Hosting buildspec callouts - Fix numerous feature support values across all tables - Various content and wording improvements
- Restructure migrate-existing-app: rename sections, add Backend intro, expand Refactor description, add Step 0 Clone with Environment Isolation callout, embed custom pipelines content into Deploy & Host section - Feature parity: move console/tooling features to new Console & Developer Experience section, fix numerous migration tool values, remove Migration Tool column from Hosting table, rename overrides - Remove standalone custom-pipelines page - Various wording and structure improvements
- Add DataStore prerequisite - Add holding stacks accordion to refactor step - Move validations accordions directly below step titles - Replace untested indicators with unsupported - Fix migration tool support for MFA, custom attributes, user pool group preference, configure memory size - Rename sections, fix AWS profile callout wording - Various feature parity table corrections
- Add conventions section to step-by-step migration - Move GraphQL IAM prerequisite to second position - Remove experimental-alpha package from refactor step - Add amplify pull and verification steps to setup - Add DataStore migration prerequisite wording fix
- Update landing page intro with Gen 1 deprecation and EOL date - Rephrase migration tool callout for developer preview tone - Add explainer to Console & Developer Experience section - Include user edits
- Mark Cron jobs as supported in migration tool - Add Email based user registration/forgot password row - Remove duplicate Email Verification - Link row
- Move critical post-refactor steps into Step 6 with CRITICAL label - Add explanation of why post-refactor deployment is required - Bump deploy to Step 7 - Red callout for critical warning - Remove redeploy image and redundant text - Fix commit message and downtime wording
- Add lock rollback and amplify push after refactor rollback - Move holding stacks accordion to after refactor description - Reorder for better reading flow
- Simplify landing page intro - Remove env checkout from Step 0 - Update hosting table with Amplify Console naming and links - Mark manual deployment as Gen 2 unsupported - Remove Step 0 checkout step
- Add Step 4 intro explaining why manual edits are needed - Add AI coding assistant tip - Group NodeJS ESM and Secrets under Functions heading - Move REST API and add Kinesis under Frontend - Move @auth directive content into Data section - Remove Post Generate prefix from headings - Fix secret() parameter - Rename Reuse Model Tables to Data
- Replace npx amplify with amplify throughout - Add Kinesis stream name change to post-refactor step - Fix secret() parameter - Remove images
- Expand Step 5 Deploy with detailed instructions and images - Add Decommission Gen 1 section with safety warnings - Add retain command with not-yet-available note - Add Kinesis post-refactor step - Add frontend code and REST API post-generate edits
- Add caution, confirmation prompts, and human supervision guidance to developer preview callout - Add permanent postRefactor() note - Bold 'not' in unattended warning
- Move detailed clone instructions from developer preview banner to Step 0 - Include user edits
- Add Step 6 with test examples and manual fix guidance - Upgrade DynamoDB callout to warning with clone imperative - Renumber steps 7-9
Replace reference to non-existent amplify gen2-migration retain command with general instructions on manually applying DeletionPolicy: Retain. Add note that a CLI command to automate this is in progress.
…ures (#8583) * feat: add links * chore * chore * chore: mid work * chore: mid work
Add testing as explicit step in migration approach, mark Step 6 as CRITICAL with warning callout, move pipeline disable advice before lock command, and various copy improvements.
cadivus
previously approved these changes
Apr 30, 2026
bobbor
previously approved these changes
Apr 30, 2026
cadivus
previously approved these changes
Apr 30, 2026
sai-ray
previously approved these changes
Apr 30, 2026
iankhou
previously approved these changes
Apr 30, 2026
Update deployment reference to point to the Hosting section in the feature parity page instead of a broken anchor link. Change wording from 'Deployment examples' to 'Deployment instructions refer to'.
sai-ray
previously approved these changes
May 1, 2026
Document that the refactor step creates a .amplify/gen2-migration/ refactor.operations/ directory with CloudFormation operation snapshots for auditing and troubleshooting purposes.
sai-ray
previously approved these changes
May 1, 2026
Include amplify pull after git checkout main to restore the Amplify configuration before running the refactor command. Remove the now-redundant warning callout about the lost profile.
jiayiwang7
approved these changes
May 1, 2026
sai-ray
approved these changes
May 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
9 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description of changes:
Backend Migration
Adds the Gen 1 → Gen 2 backend migration guide and feature parity page under
/[platform]/start/migrate-to-gen2/.DataStore
Merged from #8581 so it will be published together. Explanations can be found there.
Related GitHub issue #, if available:
Which product(s) are affected by this PR (if applicable)?
Which platform(s) are affected by this PR (if applicable)?
Checks
When this PR is ready to merge, please check the box below
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.