Multiple Environments with AWS Amplify

In this tutorial, you are going to learn how to use Amplify's env command. We will walk through an example where two people collaborate on an Amplify project.

Note: This article is a tutorial for intermediate developers who are familiar with the basics of Amplify. Do you want to learn how to accelerate the creation of your projects using Amplify 🚀? I recommend beginners to check out Nader Dabit's free course on egghead, or Amplify's 'Getting Started'.

If you use Amplify in your team, you will have to know how to use the env command properly. Otherwise, your collaboration will be a mess. Done right, Amplify allows easy and effective collaboration on projects.

There are two ways you can share an Amplify project.

Each team member works in their own "sandbox" aka. their local version of the environment.
The team shares the same development environment.

The first approach is recommended. Let's walk through each procedure, so you understand both and can decide which you prefer. You need to be familiar with Git to follow this tutorial.

1. Sandboxes

We start with the sandbox approach. Create a folder for this tutorial called multiple-env/.

mkdir multiple-env && cd multiple-env

Initialize the React project.

npx create-react-app env-one && cd env-one

Create React App automatically initializes a Git repository for us. The folder layout should later look like this.

└──multiple-env/
   ├── env-one/
   └── env-two/

Imagine env-two/ being on your co-worker's computer. Here we'll use the two apps on your computer to simulate multiple environments.

1. a) You

Initialize Amplify in your first environment and add authentication. Note: In some of these code examples, there will be several CLI commands that you have to run. Remember to double-check that you catch all and don't miss any.

# highlight-start
amplify init
# highlight-end
Note: It is recommended to run this command from the root of your app directory
? Enter a name for the project
env-one
# highlight-start
? Enter a name for the environment
prod
# highlight-end
? Choose your default editor:
Visual Studio Code
? Choose the type of app that you\'re building
javascript
Please tell us about your project
? What javascript framework are you using
react
? Source Directory Path:
src
? Distribution Directory Path:
build
? Build Command:
npm run-script build
? Start Command:
npm run-script start
Using default provider  awscloudformation
 
For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html
 
? Do you want to use an AWS profile?
Yes
? Please choose the profile you want to use
your-amplify-cli-user
 
✔ Successfully created initial AWS cloud resources for deployments.
✔ Initialized provider successfully.
Initialized your environment successfully.
 
Your project has been successfully initialized and connected to the cloud!
 
# highlight-start
amplify add auth
# highlight-end
Do you want to use the default authentication and security configuration?
Default configuration
Warning: you will not be able to edit these selections.
How do you want users to be able to sign in?
Email
Do you want to configure advanced settings?
No, I am done.

Nothing fancy going on here. Just make sure to name the first environment prod, master or something along those lines.

Push your changes to the cloud.

amplify push

If you run amplify status, you will see that your changes have been deployed.

amplify status
 
Current Environment: prod
 
| Category | Resource name  | Operation | Provider plugin   |
| -------- | -------------- | --------- | ----------------- |
| Auth     | envoneauth | No Change | awscloudformation |

Add the changes to git.

git add --all && git commit -m "Initialize Amplify and add authentication."

Set up a remote repository on GitHub or your version control provider of choice and upload your files.

git remote add origin https://github.com/janhesters/envtutorial.git
git push -u origin master

1. b) Your Co-Worker

You might want to use a second editor and terminal window to simulate the collaboration.

Clone the remote repository.

git clone https://github.com/janhesters/envtutorial.git env-two && cd env-two && yarn

If you run amplify status now, it will throw an error.

amplify status
 
Current Environment: undefined

Initialize the master branch using the prod environment.

amplify init
Note: It is recommended to run this command from the root of your app directory
? Do you want to use an existing environment?
Yes
? Choose the environment you would like to use:
prod
? Choose your default editor:
Visual Studio Code
Using default provider  awscloudformation
 
For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html
 
? Do you want to use an AWS profile?
Yes
? Please choose the profile you want to use
your-amplify-cli-user
 
✔ Initialized provider successfully.
Initialized your environment successfully.
 
Your project has been successfully initialized and connected to the cloud!

In a real-world scenario, your collaborators might have different CLI profiles. Make sure everyone has the permissions to access the relevant resources.

Now, your co-worker has the environment, too.

amplify status
 
Current Environment: prod
 
| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Auth     | envoneauth    | No Change | awscloudformation |

1. c) You

Change back to env-one/. We want to add another feature.

Amplify environments work hand in hand with Git. We can create our sandbox by creating a new git branch, and running amplify init within it.

git checkout -b sandbox && amplify init
Switched to a new branch 'sandbox'
Note: It is recommended to run this command from the root of your app directory
? Do you want to use an existing environment?
No
? Enter a name for the environment
sandbox
Using default provider awscloudformation
 
For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html
 
? Do you want to use an AWS profile?
Yes
? Please choose the profile you want to use
your-amplify-cli-user

Typically, you would give the branch a more meaningful name than "sandbox". Alternatively to amplify init we could've also used amplify env add.

The changes for this environment aren't deployed yet.

amplify status
 
Current Environment: sandboxone
 
| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Auth     | envonesandbox | Create    | awscloudformation

Note how it says our current environment is sandboxone. To list all environments run amplify env list.

amplify env list
 
| Environments |
| ------------ |
| prod         |
| *sandboxone  |

In this list, our current environment is marked with a star (*).

Let's also add an API to the sandbox and deploy it.

# highlight-start
amplify add api
# highlight-end
? Please select from one of the below mentioned services
GraphQL
? Provide API name:
AppSyncEnvOneSandbox
? Choose an authorization type for the API
Amazon Cognito User Pool
Use a Cognito user pool configured as a part of this project
? Do you have an annotated GraphQL schema?
No
? Do you want a guided schema creation?
Yes
? What best describes your project:
Single object with fields (e.g., “Todo” with ID, name, description)
? Do you want to edit the schema now?
No
 
# highlight-start
amplify push
git add --all && git commit -m "Add API."
# highlight-end

The sandbox now has an API as well as authentication. If we made our changes and want to merge them into the production environment, we can do that by using Git.

git checkout master
amplify env checkout prod
git merge sandbox
amplify push
git add --all && git commit -m "Merge API into production."

If you are done using your sandbox environment, you can delete it by running amplify env remove.

amplify env remove sandbox
? Do you also want to remove all the resources of the environment from the cloud?
Yes

1. d) Your Co-Worker

Your co-worker can get the changes by running amplify env pull. cd into env-two/ and do that.

git pull && amplify env pull

When those commands are done your co-worker is synced up with the master branch.

amplify status
 
Current Environment: prod
 
| Category | Resource name        | Operation | Provider plugin   |
| -------- | -------------------- | --------- | ----------------- |
| Auth     | envoneauth           | No Change | awscloudformation |
| Api      | AppSyncEnvOneSandbox | No Change | awscloudformation |

Good job! 👏🏻 Now you know how to collaborate using sandboxes. Next, we'll explore collaboration with ...

Sharing backends is as easy as using the sandbox. I like to mix both approaches. Meaning each team member develops using their custom sandbox, but before changes get merged into production, they get merged into the development environment.

2. a) You

Similar to the sandbox approach, create a dev branch with Git and an environment with Amplify in env-one/.

git checkout -b dev && amplify init
Switched to a new branch 'dev'
Note: It is recommended to run this command from the root of your app directory
? Do you want to use an existing environment?
No
? Enter a name for the environment
dev
Using default provider  awscloudformation
 
For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html
 
? Do you want to use an AWS profile?
Yes
? Please choose the profile you want to use
your-amplify-cli-user

We might want to track our users using Amplify's analytics, so let's add that to our dev branch.

amplify add analytics
Using service: Pinpoint, provided by: awscloudformation
? Provide your pinpoint resource name:
AnaliticsDev
Adding analytics would add the Auth category to the project if not already added.
? Apps need authorization to send analytics events. Do you want to allow guests and unauthenticated users to send analytics events? (we recommend you allow this when getting started)
No
Authorize only authenticated users to send analytics events. Use "amplify update auth" to modify this behavior.
Successfully updated auth resource locally.
Successfully added resource AnaliticsDev locally

Push your changes to the cloud and GitHub.

amplify push
git add --all && git commit -m "Add analytics."
git push --set-upstream origin dev

2. b) You Co-Worker

Your co-worker, in env-two/, can get the remote branch by creating his local version and then fetching it.

git checkout -b dev && git fetch origin dev && git pull origin dev

Your co-worker can list all environments to see both the prod and the dev branch.

amplify env list
 
| Environments |
| ------------ |
| *prod        |
| dev          |

Moving code from dev to prod works the same way as we showed earlier when we moved from sandbox to prod.

If you liked this tutorial, you might want to read my other articles about Amplify because they cover advanced use cases and make you an Amplify expert.

Summary

Remember: Use Amplify's env command parallel to Git.

We understood the two ways - sandbox and shared environments - to use env by looking at an example for each.

To clean up run amplify delete.

Jan Hesters