Today we’re launching the AWS Amplify Command Line Interface (CLI) toolchain for developers. AWS Amplify is an open-source library that you can use to build sophisticated cloud-powered mobile and web apps. Since the launch of the JavaScript library last year, we’ve received positive feedback, encouragement, and most importantly, contributions from the open-source and JavaScript communities. With this launch, we want to deliver on some of the biggest requests from our community.

As we continue to work with the community to improve the library, we’re taking steps to simplify the developer experience and provide tools that accelerate app development. Developers are looking to prototype and build quickly. They want to easily transition to a production rollout that includes continuous integration and continuous delivery (CI/CD) workflows across teams. Additionally, while simplicity is paramount, the ability to have “escape hatches” and customize is also a principle that most customers want in their toolchain. While many developers are excited by what new technologies like GraphQL or Progressive Web Apps (PWAs) can do, they’re looking for ways to shorten their learning curves when getting started.

With today’s announcement, we’re launching a robust feature set for simplifying mobile and web application development. We hope you see this as a great foundation as we continue to build on AWS Amplify together.

AWS Amplify CLI

The AWS Amplify CLI is easy to install via NPM:

npm install -g @aws-amplify/cli

amplify configure

Similar to the principles of the AWS Amplify library, the CLI is category based with best practices built in. The categories overlap with those in the library, but the CLI is a superset because some functionality doesn’t apply to the runtime (hosting or codegen, for example).

After you install the CLI, navigate to a JavaScript, iOS, or Android project root, initialize AWS Amplify in the new directory by running amplify init. After a few configuration questions, you can use amplify help at any time to see the overall command structure. You can use amplify help <category> to see actions for a specific category.

When you’re ready to add a feature, run amplify add <category> then answer any questions. For instance, in a React application, try running amplify add hosting to have your application built and hosted on Amazon S3 with an Amazon CloudFront distribution.

AWS CloudFormation architecture

The AWS Amplify CLI uses AWS CloudFormation and nested stacks. This allows you to add or modify configurations locally before you push them for execution in your account. It also takes any “magic” away and allows full transparency in the process of customizing your resources. To see the status of the deployment at any time, run amplify status.

Category model and built-in best practices

With this new design, there are a myriad of ways you can configure a backend for your mobile or web app on AWS. Just getting the security settings set up can be challenging, especially if you want to customize them as your business grows. We’ve built in intelligent defaults to the categories where appropriate, with opportunities to “learn more” and take control yourself. For example, running amplify add auth returns helpful messages:

$amplify add auth
The current configured provider is Amazon Cognito.
Do you want to use default authentication and security configuration? (Use arrow keys)

❯ Yes, use the default configuration.
  No, I will set up my own configuration.
  I want to learn more.

Flows like this allow you to leverage the defaults, and run amplify update auth if you ever want to change something in future, like adding multi-factor authentication (MFA) or updating password policies.

Because AWS Amplify is category based, these settings can also be “passed” to new categories when they’re added. For instance, you might run amplify add analytics either before or after you configure authentication. The CLI guides you in an excellent direction to have functional development, while incorporating appropriate best practices for security with AWS Identity and Access Management (IAM).

AWS Amplify toolchain

As we described earlier, the CLI architecture provides a solid foundation for a more robust development toolchain across your client platforms. For example, you might build a web application with some analytics and choose to hook it up to a GraphQL backend, with or without user sign-up and sign-in. Later, you might decide to also provide real-time and offline data with your iOS and Android applications. The AWS Amplify toolchain lets you do these things, and we describe a few pieces below.

GraphQL Transformer

The AWS Amplify CLI has an embedded library, the GraphQL Transformer, which simplifies developing, deploying, and maintaining GraphQL APIs. With it, you define your API using the GraphQL Schema Definition Language (SDL). The library expands and “transforms” (creates) a full AWS CloudFormation template that implements your data model.

For example, this is all that you need for a fully functional AWS AppSync backend:

type Todo @model {
  id: ID!
  name: String!
  description: String
}

The transformer converts this to AWS CloudFormation, and the CLI deploys your API. The @model syntax defines a unique type with Amazon DynamoDB. However, there are many more directives that can be used in the transformer such as:

• @connection – Creates 1:N or M:N relationships between types, such as blogs with comments.
• @versioned – Enables conflict resolution for offline or shared data operations.
• @searchable – Streams results from DynamoDB to Amazon Elasticsearch Service with automatic indexing and filters for advanced query/search functionality.
• @auth – Protects objects with fine-grained access controls, such as per-user authorization.

You can run the transform as an independent library. However it’s integrated into the AWS Amplify CLI via the API category for you to use immediately. You can also “extend” it with your own custom transforms, which you can use in CI/CD flows. For more details, see the Amplify GraphQL Transformer documentation.

GraphQL codegen

Using languages such as TypeScript, Swift, or Java with GraphQL requires a code generation step. This requires both the introspection schema, as well as GraphQL documents (queries, mutations, and subscriptions) to compile into a strongly typed class. Previously, this required you to use an external tool, but the AWS Amplify CLI has a codegen category that plugs into the deployment workflow.

The new functionality automatically downloads the GraphQL introspection schemas from your endpoint, and generates Swift or TypeScript. In the case of Android, it also downloads the schema, but the code generation happens through Gradle. The schema is placed in the appropriate directories, and you can specify where your GraphQL documents are located. Additionally, you can run the code generation commands as part of a build process if you want to automate this in Android Studio or Xcode.

Local mocking and custom plugins

Local testing and mocking is another area that many customers are trying to explore. While this is a nascent area of the industry today, the new AWS Amplify CLI architecture allows you to perform local testing of Lambda functions.

To do this, run amplify status to get the resource name of a function. Then run the following:

amplify function invoke <resourcename>

The process is invoked locally with the output from your handler. You can see your function inside the ./amplify/backend/function/resourcename structure, with an event.json file that contains the test execution data passed as context to your function.

Finally, there are always more options that you’ll want from the base AWS Amplify CLI functionality, and capabilities you might need that deviate from the best practices that are built into the CLI and toolchain. As with the AWS Amplify library escape hatches, the CLI allows you to write your own plugins for customized functionality.

Existing tooling

As we continue to improve the developer experience, we will consolidate our existing tools under the AWS Amplify toolchain. As part of this consolidation, we’ve  launched a new AWS Amplify website with centralized documentation and support for all your client development needs.

Existing Mobile Hub projects continue to work without requiring any app changes. If you’re using the AWS Mobile CLI for existing projects, you can also continue to use that older CLI. However, going forward, new features will be added to the AWS Amplify CLI toolchain which does not use Mobile Hub.

If you’re building a new mobile or web app, or adding cloud capabilities to brownfield apps, use the new AWS Amplify CLI. The new Amplify CLI will allow you to take advantage of all the new features outlined in this blog, as well as the rich CloudFormation functionality to unlock more workflows and future tooling.

Give us feedback

We’re excited to launch this new AWS Amplify CLI and toolchain—and to see what you’ll build! The flexibility, philosophy, best practices, and programming style that the AWS Amplify library has is now built into the entire toolchain. It should help accelerate your projects from inception all the way into production rollout. As always, let us know how we’re doing, and submit any requests in the AWS Amplify CLI repository.