There has always been a bit of a problem between deploying your backend and then integrating that same backend with your front end code. The front end needs to know where the back end is located. The traditional approach is to create a configuration file for the purpose. But how?
The AWS Mobile team created the awsmobile CLI and followed that with the AWS Amplify CLI. These tools are great for new projects. They provide for best practices deployment capabilities on the backend — and automatic maintenance of the required configuration file on the front end.
What about existing projects?
Let’s say you have a nice deployment of a backend on AWS with the Serverless Framework. You’ve may have configured Amazon Cognito, plus an Amazon DynamoDB table connected together with some AWS Lambda functions and an AWS AppSync API layer. Things are good. Now you want to create some mobile apps to leverage this infrastructure.
In the old world, you would create an
aws-exports.js file for your web and React Native projects, or an
awsconfiguration.json file for your Android and iOS native projects — probably by hand. The alternative would be to create a constants file with the appropriate values for initializing connectivity to your backend. Either way, it’s a laborious process.
That is why I created the aws-amplify-serverless-plugin. This is a plugin for the Serverless Framework that takes the resources that you have deployed and creates the appropriate configuration file(s) for you.
Let’s look at an example
To get started with a simple example, let’s say we have a GitHub repository with four directories at the top level:
backendcontains my Serverless Framework files, including the
serverless.ymlfile, GraphQL schema and mapping templates.
androidcontains my typical Android project.
ioscontains my typical iOS project.
webcontains my web project that I will deploy to an S3 bucket that is specified in the
To deploy, we just type:
(cd backend && sls deploy -v)
Then we’ll build each of the clients, maybe deploying the web like this:
(cd android && ./gradlew build) (cd ios && ./build.sh) (cd backend && sls clinet deploy -v)
It’s a fairly normal build cycle. Now, let’s update the project to include the
aws-amplify-serverless-plugin. First, we’ll need to install the plugin:
Then, add a custom section to configure the plugin:
Each appClient entry is an
AWS::Cognito::UserPoolAppClient resource listed in the
resources section of your
Now, run the deployment using
sls deploy -v.
At the end of the deployment, you should see the three files written out. Android, React Native, and web clients can use the files directly. For iOS, you will have to add the
awsconfiguration.json file to your project. Ensure you do not check the “Copy files” box when adding the file to your project. You want any updates to be automatically included in your project.
How does it work?
The Serverless Framework turns your configuration into a CloudFormation template. The plugin cycles through all the resources that are a part of the CloudFormation stack that has been deployed, and queries those resources for settings that are relevant to a mobile or web client. Once it has all the settings, it then turns the resulting configuration into the appropriate file format.
aws-amplify-serverless-plugin supports the following features
- AWS AppSync (including generation via the excellent
serverless-appsync-pluginas well as through the Resources section)
- Amazon Cognito Federated Identities
- Amazon Cognito User Pools — you can specify a different user pool app client for each client.
- Amazon S3 buckets — the first listed S3 bucket (aside from the deployment bucket) is registered as the transfer bucket.
In addition, it supports two different file formats:
awsconfiguration.jsonis the native format for the AWS Mobile SDK for Android and iOS
I hope this plug-in helps developers who have a significant investment in Serverless Framework to continue to use that investment — yet still get the benefits of the AWS Mobile SDK and AWS Amplify libraries. The plugin is far from perfect, but feel free to leave questions, bugs, and feature requests on the GitHub repository.