Skip to content

Performing a Migration in AWS Amplify

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

Back-end migrations can be a tricky task if you're going in blind, and it may take a few attempts before you know the ins and outs of a specific technology being used. Those with experience in AWS will understand that sometimes things don't always go according to plan when performing even the most common tasks in Amplify, and migration of an app from one app ID to another can seem like a huge undertaking.

In this guide, we'll look at how to:

  • Reference a new app
  • Create a new back-end environment for the migration
  • And verify our deployment works

This guide assumes you have an existing application created.

Before Attempting a Migration

Migration can be seen as a refactor of sorts, except it's the entire project that needs to move and work. In any refactoring effort, taking into account all the moving parts is key. But with Amplify, these parts are all tied to policies while creating the environment. What this means for Amplify is that with an existing app, we have the option to use already generated policies or perform a manual shifting of resources.

With the first option, policies and references are already mapped for how the BE would rebuild. However, in option two, there may not be an easy transition of resources especially if the application is large and/or is being upgraded as part of the migration processes. In the case of an older application, it may be easier to manually migrate because the upgrade process might not take into account some older pattern.

We'll use the first option of a simpler migration by referencing the new app id.

Initial Setup

Amplify behaves similarly to git. To get started, first follow a git-like workflow by fetching the latest:

$ amplify pull

It's recommended to commit the latest stable code to your source control of choice in case the migration goes wrong.

In the new AWS account, where this app will live, we need to create a space for it to live. Thankfully, Amplify docs give a step-by-step guide on configuring a new app space.

Referencing the New AWS App

At this point, if you've created a new app in a new account, then there should be a default staging environment. We won't use that one because we want at least one working, clean environment in case we need to start over (by deleting the environment).

Clear old environments

Take a look at the contents of team-provider-info.json and look for AmplifyAppId under any existing environments. Depending on the current environment selected, Amplify Actions will be performed against that environment at that app id.

This isn't useful to use because generating a new develop environment will have:

  1. A name conflict in this file
  2. New environments created in the same app

If you used the wrong credentials creating the env, a new app under the old account will be created at the new app id.

Generate an env at the new app id

Typically we'd perform amplify env add to add an environment to an existing app. However, we need to reference the new app. So we'll initialize a new app instead:

$ amplify init --appId <Amplify-Service-Project-AppId>

Found in the Amplify Docs for commands amplify-cli here

The Amplify-Service-Project-AppId can be found by:

  1. Navigating to AWS Amplify
  2. Selecting the app
  3. Selecting App settings > General
  4. Selecting the end part of the App ARN
Amplify APP ARN

Because there won't be environments to read from team-provider-info.json, it won't prompt for using an existing environment. Follow the interactive prompts for your configuration needs.

Verify the new environment and push

To verify that everything went well, look again AmplifyAppId in team-provider-info.json under the new environment. This should match with the Amplify Console.

Now we push:

$ amplify push

Verify Successful Deployment

All's that's left now is to wait while Amplify recreates the policies for all your back-end parts. If it all went well, you should have no failures in the terminal, and see the deployment success in Amplify Console with references to your API, functions, etc. like:

Amplify Console Environment Deploy Success

If you have a front-end, re-attach the source control of choice.


The final step after everything is working is to remove references to the old application. We did this partially by deleting old environments in team-provider-info.json. Now we have to delete the old app from the old account, and we're done!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.