Front-End Web & Mobile
Amplify CLI simplifies starting from existing Amplify projects and adds new command for extending CLI capabilities
The Amplify Framework is an open source project for building cloud-enabled mobile and web applications. Today, we are happy to announce new features in the Amplify CLI that simplify the developer experience by enabling developers to get started from an existing Amplify project hosted on a Git repo by using a single command.
The ‘amplify init’ command with a new ‘–app’ parameter clones the git repo, initializes the project, deploys the backend, and configures the frontend—whether a web, iOS, or Android application—to use the backend. For web applications, the command also launches the application in your default browser. This helps speed up the process of set up, development, and testing existing Amplify projects.
In addition, the Amplify CLI has now made it easy to add custom capabilities via plugins. A new ‘amplify plugin init’ command generates template for a plugin based on simple questions you answer. You can then extend these generated templates to add commands, events, and configuration for your plugin.
Getting started from an existing Amplify project
We will walkthrough an example of how you can use this new feature with an existing web application that was built using Amplify. We will use the Journey app hosted on a GitHub repo in our sample walkthrough.
Install and configure the Amplify CLI
The configure step will guide you through steps for creating a new IAM user. Select all default options.
If you already have the CLI configured, you do not need to run the configure command again.
Choose the Amplify app
For this blog post, we are using the Journey app which is built using React, AWS Amplify, GraphQL, AWS AppSync, and hosted on GitHub. You can use any other application that was built using Amplify. The repo for the application you use must include the following for this feature to work:
1. amplify/, .config/, and backend/ folders
2. ‘project-config.json’ in .config/ folder
3. ‘backend-config.json’ in backend/ folder
4. CloudFormation files in the backend/ folder. For e.g. ‘schema.graphql’ for API and cloudformation template for auth.
We pass the GitHub URL for the Journey app in the amplify init command as shown below:
The init command clones the GitHub repo, initializes the CLI, creates a ‘sampledev’ environment in CLI, detects and adds categories, provisions the backend, pushes the changes to the cloud, and starts the app.
If you already have an AWS profile set up on your local machine, choose “Yes” when prompted by the CLI and select the profile you would like to use.
If you do not have an AWS profile set up on your local machine, you will be prompted by the CLI to set up a new AWS profile.
Provisioning the frontend and backend
Next, the CLI will detect the ‘amplify’ folder in the source code of your app and start provisioning the backend resources for your app using your AWS account and profile selected in the previous step. It will also detect and install frontend packages dependencies that the web application needs by reading the package.json file.
Once the process is complete, the CLI will automatically open the app in your default browser.
Auth
The Journey app has auth category (sign-in) added to its backend. You can add users to log-in using amplify auth console command. This will open up the Amazon Cognito console in your browser where you can add users and groups.
To add a user, go under General Settings –> Users and groups –> Create user. In the create user dialog box, uncheck the "Send an invitation to this new user?" option as shown below:
Restart your app after you add the users in the Cognito console using:
As you can see, this simplifies the entire process of setting up an existing app built using Amplify. You no longer have to download the source code, figure out the categories, provision resources, push changes to the cloud, and then start your app. This helps speed up the development and testing process enabling you to focus more on the front end piece.
Custom capabilities in the Amplify CLI
The Amplify CLI has a pluggable architecture which allows you to write plugins that are one of the following types: category, provider, frontend, and util. To learn more about the types of plugins, refer to our documentation.
Before this release, creating a plugin for CLI was done by executing a series of manual steps which include creating directories for the plugin source code, adding code for commands and events, creating extensions as needed, testing your plugin, and publishing it to NPM. These steps can consume time overall due to more manual steps being involved compared to the new feature.
Now, the Amplify CLI plugin platform enables you to create and configure the entire skeleton of a plugin package with few commands.
In the example below, we will create a simple util plugin called my-amplify-utility and add a version command to it which outputs the version of our plugin. An util plugin typically does not manage any backend resources in the cloud but can be used by other plugins.
Add a new plugin
First, run the amplify plugin init command from an empty directory. Alternatively, you can use its alias amplify plugin new. This commands asks you a few simple questions which are used as input to create the skeleton of a new plugin package. Once created, this plugin will show up in your local installation of Amplify CLI. You can view all of the active plugins by using the amplify plugin list command.
Once the above command completes, it will create a directory called ‘my-amplify-plugin’ in the folder where you ran the command. Let’s take a look what’s inside this folder:
amplify-plugin.json is the plugin manifest file which contains the plugin name, type, commands, and event handlers.
commands/ folder contains the code for each command you add to the plugin.
event-handlers/ folder contains the event handlers you specify in the amplify-plugin.json file.
index.js is the entry point of the plugin invoked by the Amplify CLI.
package.json contains the package information about the plugin.
Update version.js
The init command automatically creates templates for few commands such as help and version. These templates can be found at: command/help.js and commands/version.js
Modify the version.js file to say “Version 1.0.0”
async function run(context) {
// print out the version of your plugin package
context.print.info('Version 1.0.0');
}
module.exports = {
run,
};
Install the plugin package
Once you have updated the version.js file, install the plugin package locally by running the following command from the root of the plugin package folder which in our case is my-amplify-plugin:
Run the plugin
To use the plugin, run the following command:
As seen above, it prints out the version of the plugin.
Publish and use the plugin
You can publish the plugin to NPM using the instructions here.
Once your plugin is published, other developers can install and use it using the following commands:
To learn more about the complete plugin platform and commands, visit our documentation.
Feedback
We hope you like these new features! Let us know how we are doing, and submit any feedback in the Amplify Framework Github Repository. You can read more about AWS Amplify on the AWS Amplify website.