DEV Community: gerard-sans

Offline-first made easy with GraphQL, Amplify DataStore and Vue

gerard-sans — Thu, 01 Oct 2020 11:10:08 +0000

Create a PWA cloud-enabled offline-first chatroom using Vue

In this article, you will create Chatty, a chatroom Progressive Web App (PWA) that stores data on the device while offline, and synchronises in real-time with other devices when online using Amplify DataStore, GraphQL and Amazon DynamoDB. We will cover:

Introduction to Offline-first, PWAs and Amplify DataStore
Setting up a new project with the Vue CLI
Creating a new GraphQL API
Amplify DataStore: setup, data models and usage
Creating the UI with Vue: the chatroom, sending and deleting messages; and doing real-time with subscriptions
Making Chatty a PWA
Adding a PWA custom configuration
Improving UX while offline
Publishing your app via the AWS Amplify Console
Installing Chatty in the Desktop and Mobile
Cleaning up cloud services

In order to follow this post you will need a basic knowledge of GraphQL. You can learn the basics following this tutorial at graphql.org. We will be referring to GraphQL schema, directives, types, queries, mutations, subscriptions and resolvers.

Please let me know if you have any questions or want to learn more at @gerardsans.

> Final solution and step by step tutorial in GitHub.

Introduction to Offline-first, PWAs and Amplify DataStore

Offline-first is an approach to software development, where an application is built to function, with or without an internet connection. Using this approach, data is stored locally on the user’s device and periodically uploaded and replicated into the cloud. Features include:

Offline ready: application works offline. This usually comes with some limitations regarding feature set and device capabilities. Eg: PWAs require an install step where the user needs to be online to download all the necessary application assets.
Great user experience: application loads fast and transitions seamlessly from online to offline improving user retention. The user is in control regarding app updates, data synchronisation, data conflict resolution and connectivity. Eg: App shell; user is informed about connectivity changes.
Native-like features: application behaves similar to a native app. Eg: PWAs are able to run on multiple operating systems as standalone applications and don’t require the user to interact with the browser.
Reliable storage: user can exit the application at any moment without losing data. Application stores user data securely on-device and synchronises with the cloud transparently when possible.

Progressive Web Apps

Progressive Web Apps combine the benefits from native apps, while being able to run on more platforms, leveraging browser technologies. PWA features allow Web apps to close the gap with native applications while creating similar user experiences. PWA features:

Works offline via service worker.
Great performance via app shell and pre-cached assets.
Access to device APIs via Web APIs.
Supports push notifications via service worker.
Works in Web, Mobile and Desktop via Web app manifest.

The most important requirements for PWA are: security, must be served via HTTPS, the service worker and the Web app manifest. We will incorporate all of these to Chatty.

Amplify DataStore

Amplify DataStore, is an on device persistent repository for interacting with local data, and able to automatically synchronise via GraphQL. Using Amplify DataStore, you can provide a great offline-first experience for your users, while using a simple programming model.

GraphQL knowledge is beneficial when using Amplify DataStore to understand its inner workings but not necessary to use DataStore APIs.

Amplify takes care of all the heavy lifting regarding hosting your data source in the cloud using Amazon DynamoDB; and scaling real-time messaging, synchronising data and running conflict resolution with AWS AppSync and GraphQL.

Amplify DataStore uses your GraphQL schema to generate data models. These will help keep your client code consistent with the type and fields defined in your GraphQL schema; and reduce type checks and data related run-time errors while enforcing GraphQL type safety.

Amplify DataStore behaves differently when in offline or online modes:

In offline mode, we use the DataStore API to manage the data on the device via the Storage Engine using GraphQL. The local Data Store being used will vary depending on the user device. This can either be IndexedDB in the browser or SQL Lite in Android and iOS.

Amplify DataStore data flow in offline mode

In online mode, Amplify DataStore, will synchronise with the cloud using the Sync Engine via GraphQL to automatically synchronise with your GraphQL API. At the query level, this is implemented as an AWS AppSync resolver accessing Amazon DynamoDB, AWS Lambda or Amazon ElasticSearch.

Amplify DataStore data flow in online mode

Amplify DataStore supports the following conflict resolution modes during synchronisation:

Optimistic concurrency, this mode rejects any incoming changes if there’s a mismatch in the tracking version between the incoming change and the item being changed. A further step on the client is required to resolve the conflict.
Auto merge (default), this mode doesn’t require further steps to resolve conflicts. It accommodates mutations on a field-by-field basis as long as scalar types don’t clash. If they do, they are ignored but all other fields are merged, if possible.
Custom, this mode uses AWS Lambda to allow more control and complex use cases.

For more details read conflict detection and sync.

Setting up a new project with the Vue CLI

Before moving to the next section, please complete the steps described in “Build your first full-stack serverless app with Vue”. Here you will set up the initial project, familiarise with Amplify CLI and add an authorisation flow so users can register themselves via an automated verification code sent to their email and login.

Creating a new GraphQL API

First, we are going to create the GraphQL API to service Chatty chatroom. To create it, we will use the following command:

amplify add api

Answer the following questions

Please select from one of the below mentioned services GraphQL
Provide API name: ChattyAPI
Choose the default authorization type for the API API key
Enter a description for the API key: (empty)
After how many days from now the API key should expire (1–365): 7

It’s important that you don’t miss the following steps to set up conflict detection. If you missed it, you can recover with amplify api update

Do you want to configure advanced settings for the GraphQL API Yes, I want to make some additional changes.
Configure additional auth types? No
Configure conflict detection? Yes
Select the default resolution strategy Auto Merge
Do you want to override default per model settings? No
Do you have an annotated GraphQL schema? No
Choose a schema template: Single object with fields (e.g., “Todo” with ID, name, description)
Do you want to edit the schema now? Yes

When prompted, replace the default schema with the following:

type Chatty @model {  
  id: ID!  
  user: String!  
  message: String!  
  createdAt: AWSDateTime  
}

By adding @model to the Chatty type we are telling the Amplify CLI to create the resolvers to support queries, mutations and subscriptions in Amazon DynamoDB. Besides the regular CRUD operations, we are also getting some more advanced features like pagination, filtering and real-time synchronisation that we are going to use later.

Pushing your GraphQL API to the cloud

Let’s run the push command to create the GraphQL API:

amplify push

Are you sure you want to continue? Yes
Do you want to generate code for your newly created GraphQL API Yes
Choose the code generation language target javascript
Enter the file name pattern of graphql queries, mutations and subscriptions src/graphql/**/*.js
Do you want to generate/update all possible GraphQL operations — queries, mutations and subscriptions Yes
Enter maximum statement depth [increase from default if your schema is deeply nested] 2

Write down your GraphQL endpoint and API KEY.

This is the resulting architecture with our new GraphQL API managed by AWS AppSync and Amazon DynamoDB:

Run the command below to access the AWS AppSync console.

amplify console api

Please select from one of the below mentioned services GraphQL

Amplify DataStore setup

Run the command below to install the necessary dependencies:

npm install --save @aws-amplify/core @aws-amplify/datastore

Data model generation

Generate the data models to manage our messages for our ChattyAPI.

amplify codegen models

Important: DO NOT forget to regenerate your models every time you introduce a change in your schema.

After running this command, AWS Amplify CLI has generated the necessary data models in a new folder. The files in this folder hold your data model classes and schema.

<amplify-app>  
    |\_ src  
      |\_ models

Creating a message

Now that the GraphQL API and data models are created, we can begin using the DataStore API. The first thing we’ll do is create a new message passing the generated data model to save.

Using data models allow us to be always compliant with the GraphQL schema and prevent errors right in the client.

import { DataStore } from "@aws-amplify/datastore";  
import { Chatty } from "./models";

await DataStore.save(new Chatty({  
  user: "amplify-user",  
  message: "Hi everyone!",  
  createdAt: new Date().toISOString()  
}))

This will create a record locally in your device and synchronise it in the background using the underlying GraphQL API when in online mode.

Querying data

Let’s see how we can query the data using Amplify DataStore. In order to query our data model we will use a query and a predicate to indicate that we want all records.

import { DataStore, Predicates } from "@aws-amplify/datastore";  
import { Chatty } from "./models";

const messages = await DataStore.query(Chatty, Predicates.ALL);

This will return an array of messages that we can display in our UI. Predicates also support filters for common types like Strings, Numbers and Lists.

Find all supported filters at query with Predicates.

Creating the UI with Vue

Now, let’s look at how we can create the UI to create and display messages for Chatty chatroom.

<template>  
  <div v-for="message of sorted" :key="message.id">  
    <div>{{ message.user }} - {{ moment(message.createdAt).format('YYYY-MM-DD HH:mm:ss')}})</div>  
    <div>{{ message.message }}</div>  
  </div>  
</template>  
<script>  
import { DataStore, Predicates } from "@aws-amplify/datastore";  
import { Chatty } from "./models";  
import moment from "moment";

export default {  
  name: 'app',  
  data() {  
    return {  
      user: {},  
      messages: [],  
    }  
  },  
  computed: {  
    sorted() {  
      return [...this.messages].sort((a, b) => -a.createdAt.localeCompare(b.createdAt));  
    }  
  },  
  created() {  
    // authentication state managament  
    onAuthUIStateChange((state, user) => {  
      // set current user and load data after login  
      switch (state) {  
        case AuthState.SignedIn: {  
          this.user = user;  
          this.loadMessages();  
          break;  
        }  
      }  
    });  
  },  
  methods: {  
    moment: () => moment(),  
    loadMessages() {  
      DataStore.query(Chatty, Predicates.ALL).then(messages => {  
        this.messages = messages;  
      });  
    },  
  }  
}  
</script>

After the user signs in, we call loadMessages. This fetches all the messages in our local store. We are sorting the list with a computed method sorted as we want our messages to show the most recent at the top. We are also using moment to format our time variables.

Creating a message

Now, let’s look at how we create new messages.

<template>  
  <form v-on:submit.prevent>  
    <input v-model="form.message" placeholder="Enter your message..." />  
    <button @click="sendMessage">Send</button>  
  </form>  
</template>  
<script>  
export default {  
  data() {  
    return {  
      form: {},  
    };  
  },   
  methods: {  
    sendMessage() {  
      const { message } = this.form  
      if (!message) return;  
      DataStore.save(new Chatty({  
        user: this.user.username,  
        message: message,  
        createdAt: new Date().toISOString()  
      })).then(() => {  
        this.form = { message: '' };  
        this.loadMessages();  
      }).catch(e => {  
        console.log('error creating message...', e);  
      });  
    },  
  }  
}  
</script>

We use a form to read the message from the user and call sendMessage with save passing the user and current date along with the message. Once the message has been created we reset the input field and reload all messages. Note how we use Amplify DataStore as our source of truth in this implementation.

Deleting all messages

One of the main advantages of working using Amplify DataStore is being able to run a series of GraphQL mutations without having to use a series of individual operations. See below how we can use delete together with a predicate to remove all messages.

DataStore.delete(Chatty, Predicates.ALL).then(() => {  
  console.log('messages deleted!');  
});

When using Amplify DataStore records are never removed, but marked for removal. Records will then be automatically removed as defined in their TTL attribute. At the time of writing, this is set to 30 days.

Real-time with GraphQL subscriptions

Next, let’s see how we can create a GraphQL subscription. To do so, we will listen for changes of data in our API, and update the state whenever a new piece of data comes through. When the component is destroyed, we will unsubscribe to avoid memory leaks.

As we are using Amplify DataStore, as our source of truth, we don’t need another copy of it at the app level so we just need to load the latest state with loadMessages.

<script>  
export default {  
  data() {  
    return {  
      subscription: undefined;  
    };  
  },  
  created() {  
    //Subscribe to changes  
    this.subscription = DataStore.observe(Chatty).subscribe(msg => {  
      console.log(msg.model, msg.opType, msg.element);  
      this.loadMessages();  
    });  
  },   
  destroyed() {  
    if (!this.subscription) return;  
    this.subscription.unsubscribe();  
  },  
}  
</script>

At this point, the chatroom is fully working including authentication flow and data synchronisation in real-time.

Real-time synchronisation using Chrome and Firefox clients side-by-side.

On the other hand, we haven’t made much progress in making it work offline or having native-like features. In order to tick these boxes, we are going to make our app a PWA.

Making Chatty a PWA

The PWA CLI plugin can help us making Chatty a PWA by running a single command:

vue add @vue/pwa

This will make few changes to the project and add a few new assets necessary to run the app as a PWA. The most important change happens in src/main.js where we are now registering a service worker that will allow Chatty to work offline.

Using the default settings, the service worker is configured to pre-cache all the assets resulting from the build (js, css and public folder). Using this setup, the browser can access the cache to load the app while offline. See the diagram below:

Service worker serving assets from the cache while offline

Learn more about service workers at using service workers.

Run the build command to see changes:

yarn build

In your dist folder you should find the following:

└── dist  
  ├── css  
  │   └── app.<version>.css  
  ├── img/icons  
  │   ├── android-chrome-<size>.png  
  │   └── ...  
  ├── js  
  │   ├── app.<version>.png  
  │   └── ...  
  ├── favicon.ico  
  ├── index.html  
  ├── manifest.json  
  ├── precache-manifest.<version>.json  
  ├── robots.txt  
  └── service-worker.js

The index.html has been modified to include the Web app manifest manifest.json along with some meta tags and entries to support different devices and platforms. You can further customise these settings. The most important ismanifest.json/display set to standalone. This setting will give the app a look and feel like a native application for Desktop and Mobile. Learn about all the options available in Web app manifest.

Another important file is service-worker.js. This contains the implementation for the service worker which determines the behaviour of the app while offline. As part of it, precache-manifest.<version>.json includes all files to be installed and pre-cached as part of the app. This will make the app load almost instantly as it won’t use the network. These files were created by the PWA CLI plugin and include all the assets from your build.

Test the app running the following commands on a new terminal window:

cd dist  
python -m SimpleHTTPServer 8887  // open localhost:8887

Remember that in order to test the app you need to install the service worker first. This requires at least loading the app once.

To test the app while offline you can use the Developer Tools or switch off your internet connection. See below a screen capture after refreshing the page while offline:

Chatty app while offline.

As you can see in the screenshot above using Chrome, in the Network tab, the files are served by the service worker while offline (in green). Unfortunately the default setup won’t include any custom assets like our SVG logo in the header (in red) or external fonts.

Adding a PWA custom configuration

Let’s fix the issue with our logo by using a custom configuration. Create vue.config.js with the following content at the root of your project:

// vue.config.js  
const manifest = require('./public/manifest.json')module.exports = {  
  pwa: {  
    name: manifest.short_name,  
    themeColor: manifest.theme_color,  
    msTileColor: manifest.background_color,  
    appleMobileWebAppCapable: 'yes',  
    appleMobileWebAppStatusBarStyle: 'black',  
    workboxPluginMode: 'InjectManifest',  
    workboxOptions: {  
      swSrc: 'src/service-worker.js',  
    }  
  }  
}

This file controls the PWA CLI plugin and deal with settings in the Web app manifest and UX for different devices.

The custom configuration uses workbox in injectManifest mode and points to the service worker implementation we want to use. Find all configuration options at the official website. Now create src/service-worker.js with the following code

// src/service-worker.js  
workbox.core.setCacheNameDetails({ prefix: 'amplify-datastore' })

workbox.core.skipWaiting()  
workbox.core.clientsClaim()

const cacheFiles = [{  
 "revision": "e653ab4d124bf16b5232",  
 "url": "[https://aws-amplify.github.io/img/amplify.svg](https://aws-amplify.github.io/img/amplify.svg)"  
}]

self.__precacheManifest = cacheFiles.concat(self.__precacheManifest || [])  
workbox.precaching.precacheAndRoute(self.__precacheManifest, {})

For our service worker, we are setting a prefix for our cache to easily find our files while using the Developer Tools. We are also setting the behaviour for new service worker versions. These will be applied immediately replacing any existing ones with skipWaiting and clientsClaim as explained here. To fix our SVG issue, we are adding the url to the SVG file, to the pre-cached files defined in the Web app manifest.

Improving UX while offline

We are almost done. Our app can survive offline reloads, can store messages while offline and can synchronise when back online thanks to Amplify DataStore.

The only remaining issue now is improving the user experience as the user doesn’t know when the app is operating online or offline. This is not a great UX, as sometimes the user might inadvertently go offline and be confused as for not receiving any feedback or explanation from the app. We can fix this by using the code below:

// <div v-if="offline">You are offline.</div>  
// <div v-bind:class="{ offline: offline }">

// App.vue  
import { Hub } from 'aws-amplify';

export default {  
  data() {  
    return { offline: undefined };  
  },  
  created() {  
    this.listener = Hub.listen('datastore', {payload:{event}} => {  
      if (event === 'networkStatus') {  
        this.offline = !data.active;  
      }  
    })  
  }  
}

We are using the Amplify Hub to detect network changes and use it to set the offline flag. Once in place, we can use it to display messages or style the UI accordingly as shown at the beginning of the code above. We are now ready to publish Chatty to the cloud and test it using different devices.

Chatty PWA informing the user of changes in the network status.

Publishing your app via the AWS Amplify Console

The first thing you need to do is create a new repo for this project. Once you’ve created the repo, copy the URL for the project to the clipboard and initialise git in your local project:

git init  
git remote add origin [repo@repoofyourchoice.com](mailto:repo@repoofyourchoice.com):username/project-name.git  
git add .git commit -m 'initial commit'git push origin master

Next visit the AWS Amplify Console in your AWS account. Click Get Started to create a new deployment. Next, authorise your repository provider as the repository service. Next, choose the new repository and branch for the project you just created and click Next. In the next screen, create a new role and use this role to allow the AWS Amplify Console to deploy these resources and click Next. Finally, click Save and Deploy to deploy your application!

AWS Amplify Console deployment steps.

This will generate a public url that uses HTTPS, which is a requirement for PWAs. Congratulations! You can now test it in your browser, Desktop and Mobile.

Installing the Chatty app in the Desktop and Mobile

Due to the inclusion of the Web app manifest in our index.html page, you can now install the Chatty app in the Desktop and Mobile devices in Windows, Mac and Linux. The way it works, changes slightly depending the device and operating system you are using. Try it out following the steps in Add to Home screen.

Use add to Home screen to install in Desktop and Mobile.

Cleaning up cloud services

If at any time, you would like to delete a service from your project and your AWS Account, you can do this by running:

amplify delete

Conclusion

Congratulations! You successfully built your first offline-first app using Vue and Amplify. You created a chatroom PWA that stores data on the device while offline and when online synchronises in real-time with other devices using Amplify DataStore, AWS AppSync, GraphQL and Amazon DynamoDB. Thanks for following this tutorial.

If you prefer, you can follow the instructions in this video to build the chatroom app.

Thanks for reading!

Have you got any questions regarding this tutorial or AWS Amplify? Feel free to reach out to me anytime at @gerardsans.

My Name is Gerard Sans. I am a Developer Advocate at AWS Mobile working with AWS Amplify and AWS AppSync teams.
GraphQL is an open source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data.

Build your first full-stack serverless app with Vue and AWS Amplify

gerard-sans — Tue, 29 Sep 2020 19:21:00 +0000

Build flexible, scalable, and reliable apps with AWS Amplify

In this tutorial, you will learn how to build a full-stack serverless app using Vue and AWS Amplify. You will create a new project and add a full authorisation flow using the authenticator component. This includes:

Introduction to AWS Amplify
Setting up a new project with the Vue CLI
Installing Amplify CLI
Adding authentication
Publishing your app
Cleaning up cloud services

Please let me know if you have any questions or want to learn more on the above at @gerardsans.

Introduction to AWS Amplify

Amplify makes developing, releasing and operating modern full-stack serverless apps easy and delightful. Mobile and frontend web developers are being supported throughout the app life cycle via an open source Amplify Framework (consisting of the Amplify libraries and Amplify CLI) and seamless integrations with AWS cloud services, and the AWS Amplify Console.

Amplify libraries: in this article we will be using aws-amplify and @aws-amplify/ui-vue.
Amplify CLI: command line tool for configuring and integrating cloud services.
UI components: authenticator, photo picker, photo album and chat bot.
Cloud services: authentication, storage, analytics, notifications, AWS Lambda functions, REST and GraphQL APIs, predictions, chat bots and extended reality (AR/VR).
Offline-first support: Amplify DataStore provides a programming model for leveraging shared and distributed data without writing additional code for data reconciliation between offline and online scenarios.

By using AWS Amplify, teams can focus on development while the Amplify team enforces best patterns and practices throughout the AWS Amplify stack.

Amplify CLI

The Amplify CLI provides a set of commands to help with repetitive tasks and automating cloud service setup and provision.

Some commands will prompt questions and provide sensible defaults to assist you during its execution. These are some common tasks. Run:

amplify init, to setup a new environment. Eg: dev, test, dist.
amplify push, to provision local resources to the cloud.
amplify status, to list local resources and their current status.

The Amplify CLI uses AWS CloudFormation to manage service configuration and resource provisioning via templates. This a declarative and atomic approach to configuration. Once a template is executed, it will either fail or succeed.

Setting up a new project with the Vue CLI

To get started, create a new project using the Vue CLI. If you already have it, skip to the next step. If not, install it and create the app using:

yarn global add @vue/cli  
vue create amplify-app

Navigate to the new directory and check everything checks out before continuing

cd amplify-app  
yarn serve

Prerequisites

Before going forward make sure you have gone through the instructions in our docs to sign up to your AWS Account and install and configure the Amplify CLI.

Setting up your Amplify project

AWS Amplify allows you to create different environments to define your preferences and settings. For any new project you need to run the command below and answer as follows:

amplify init

Enter a name for the project: amplify-app
Enter a name for the environment: dev
Choose your default editor: Visual Studio Code
Please choose the type of app that you’re building javascript
What javascript framework are you using vue
Source Directory Path: src
Distribution Directory Path: dist
Build Command: npm run-script build
Start Command: npm run-script serve
Do you want to use an AWS profile? Yes
Please choose the profile you want to use default

At this point, the Amplify CLI has initialised a new project and a new folder: amplify. The files in this folder hold your project configuration.

<amplify-app>  
    |\_ amplify  
      |\_ .config  
      |\_ #current-cloud-backend  
      |\_ backend  
      team-provider-info.json

Installing the AWS Amplify dependencies

Install the required dependencies for AWS Amplify and Vue using:

yarn add aws-amplify @aws-amplify/ui-vue

Adding authentication

AWS Amplify provides authentication via the auth category which gives us access to AWS Cognito. To add authentication use the following command:

amplify add auth

When prompted choose:

Do you want to use default authentication and security configuration?: Default configuration
How do you want users to be able to sign in when using your Cognito User Pool?: Username
Do you want to configure advanced settings? No

Pushing changes to the cloud

By running the push command, the cloud resources will be provisioned and created in your AWS account.

amplify push

To quickly check your newly created Cognito User Pool you can run

amplify status

To access the AWS Cognito Console at any time, go to the dashboard at https://console.aws.amazon.com/cognito. Also be sure that your region is set correctly.

Your resources have been created and you can start using them!

Configuring the Vue application

Reference the auto-generated aws-exports.js file that is now in your src folder. To configure the app, open main.ts and add the following code below the last import:

import Vue from 'vue'  
import App from './App.vue'  

+ import Amplify from 'aws-amplify';  
+ import '@aws-amplify/ui-vue';  
+ import aws\_exports from './aws-exports';  

+ Amplify.configure(aws\_exports);  

Vue.config.productionTip = false  

new Vue({  
  render: h => h(App),  
}).$mount('#app')

Using the Authenticator Component

AWS Amplify provides UI components that you can use in your app. Let’s add these components to the project

In order to use the authenticator component add it to src/App.vue:

<template>  
  <div id="app">  
+    <amplify-authenticator> 
+      <div>  
+        <h1>Hey, {{user.username}}!</h1>  
+        <amplify-sign-out></amplify-sign-out>  
+      </div> 
+    </amplify-authenticator>
  </div>  
</template>
<script>  
+ import { AuthState, onAuthUIStateChange } from '@aws-amplify/ui-components'

export default {  
  name: 'app',  
  data() {  
    return {  
+      user: { },
    }  
  },  
  created() {  
+    // authentication state managament  
+    onAuthUIStateChange((state, user) => {  
+      // set current user and load data after login  
+      if (state === AuthState.SignedIn) {  
+        this.user = user;  
+      }  
+    }) 
  }  
}  
</script>

You can run the app and see that an authentication flow has been added in front of your app component. This flow gives users the ability to sign up and sign in.

To view any users that were created, go back to the Cognito Dashboard at https://console.aws.amazon.com/cognito. Also be sure that your region is set correctly.

Alternatively you can also use:

amplify console auth

Accessing User Data

To access the user’s info using the Auth API. This will return a promise.

import { Auth } from 'aws-amplify';
Auth.currentAuthenticatedUser().then(console.log)

Publishing your app

To deploy and host your app on AWS, we can use the hosting category.

amplify add hosting

Select the plugin module to execute: Amazon CloudFront and S3
Select the environment setup: DEV
hosting bucket name YOURBUCKETNAME
index doc for the website index.html
error doc for the website index.html

Now, everything is set up & we can publish it:

amplify publish

Cleaning up Services

To wipe out all resources from your project and your AWS Account, you can do this by running:

amplify delete

Conclusion

Congratulations! You successfully built your first full-stack serverless app using Vue and AWS Amplify. Thanks for following this tutorial.

You have learnt how to provide an authentication flow using the authenticator component or via the service API and how to use Amplify CLI to execute common tasks including adding and removing services.

Thanks for reading!

Have you got any questions regarding this tutorial or AWS Amplify? Feel free to reach out to me anytime at @gerardsans.

My Name is Gerard Sans. I am a Developer Advocate at AWS Mobile working with AWS Amplify and AWS AppSync teams.

Create a REST API integrated with Amazon DynamoDB using AWS Amplify and Vue

gerard-sans — Mon, 28 Sep 2020 21:38:56 +0000

In this article you will create a REST API integrated with Amazon DynamoDB using AWS Amplify including CRUD operations and publication. Access to the REST API will allow both registered users and guests. In order to test it you will create a client including an authentication flow using Vue.

Setting up a new project with the Vue CLI
Creating a REST API with Amplify CLI
Creating a new REST API
Implementing CRUD operations using Amazon DynamoDB
Pushing your REST API to the cloud
Publishing your app via the AWS Amplify Console
Cleaning up cloud services

Please let me know if you have any questions or want to learn more at @gerardsans.

> Final solution in GitHub.

Setting up a new project with the Vue CLI

Creating a REST API with Amplify CLI

The Amplify CLI provides a guided workflow to easily add, develop, test and manage REST APIs to access your AWS resources from your web and mobile applications.

A REST API or HTTP endpoint will be composed by one or more paths. Eg: /todos. Each path will use a Lambda function to handle HTTP requests and responses. Amplify CLI creates a single resource in Amazon API Gateway so you can handle all routes, HTTP Methods and paths, with a single Lambda function via a Lambda Proxy integration. HTTP proxy integrations forward all requests and responses directly through to your HTTP endpoint. Eg: /todos.

Architecture diagram for the Todo App

Creating a new REST API

In this post, you are going to create a REST API to service a todo app with a single endpoint /todos using Amazon DynamoDB as a data source. To create it, use the following command:

amplify add api

Answer the following questions

Please select from one of the below mentioned services: REST
Provide a friendly name for your resource to be used as a label for this category in the project: todosApi
Provide a path (e.g., /book/{isbn}): /todos

This will be the configuration for /todos path in Amazon API Gateway:

/                          
|\_ /todos        Main resource. Eg: /todos  
   ANY           Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT  
   OPTIONS       Allow pre-flight requests in CORS by browser  
   |\_ /{proxy+}  Eg: /todos/, /todos/id  
      ANY        Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT  
      OPTIONS    Allow pre-flight requests in CORS by browser

By default, Amplify CLI creates a greedy path variable /todos/{proxy+} that catches all child resources for a path and forwards them to your Lambda. This will match all child routes including /todos/id.

Choose a Lambda source Create a new Lambda function
Provide a friendly name for your resource to be used as a label for this category in the project: todosLambda
Provide the AWS Lambda function name: todosLambda
Choose the runtime that you want to use: NodeJS
Choose the function template that you want to use: CRUD function for Amazon DynamoDB

The Lambda function template, CRUD function for Amazon DynamoDB implements route handlers for GET, POST, PUT and DELETE Http Methods and paths for /todos and /todos/*. Some possible routes examples include:

GET /todos         List all todos  
GET /todos/1       Load a todo by id  
POST /todos        Create a todo  
PUT /todos         Update a todo  
DELETE /todos/1    Delete a todo by id

Do you want to access other resources in this project from your Lambda function? No
Do you want to invoke this function on a recurring schedule? No
Do you want to configure Lambda layers for this function? No
Do you want to edit the local lambda function now? Yes

We are going to change this template later but it’s good that you have it open as you follow the next steps.

Press enter to continue
Restrict API access Yes
Who should have access? Authenticated and Guest users
What kind of access do you want for Authenticated users? create, read, update, delete
What kind of access do you want for Guest users? read

Amplify CLI restricts API access combining Amazon Cognito for authentication and AWS IAM (Identity and Access Management) for granting execution permissions on routes.

Do you want to add another path? No

That’s all! Before we publish to the cloud though, let’s see how to change the default template to implement create, read, update and delete operations for your todo app.

Implementing CRUD operations with Amazon DynamoDB

In order to manage your todo app you want to implement all CRUD operations, these are: create, read, update and delete. The template we picked in the last section uses AWS Serverless Express. Amazon API Gateway will proxy incoming requests to your todosLambda.

For the implementation, you need to add route handlers to match all HTTP methods and paths you want to support. The first to match with an incoming request will be then executed. This will be in the same order as you have define them. If there’s no match an error will be returned.

See below, how different HTTP methods and operations match route definitions in AWS Serverless Express and DynamoDB Document Client.

REST API mapping between HTTP requests, AWS Serverless Express and Document Client calls.

Before we start, you need to install a library to generate the ids for new todos. To install this dependency run the following commands from the root of your project:

cd /amplify/backend/function/todosLambda/src  
npm i --save uuid

Open /amplify/backend/function/todosLambda/src/app.js and replace its content for:

const AWS = require('aws-sdk')
var awsServerlessExpressMiddleware = require('aws-serverless-express/middleware')  
var bodyParser = require('body-parser')  
var express = require('express')  
const { v4: uuidv4 } = require('uuid')

AWS.config.update({ region: process.env.TABLE_REGION });  
const dynamodb = new AWS.DynamoDB.DocumentClient();
let tableName = "todosTable";  
if (process.env.ENV && process.env.ENV !== "NONE") {  
  tableName = tableName + '-' + process.env.ENV;  
}

var app = express()  
app.use(bodyParser.json())  
app.use(awsServerlessExpressMiddleware.eventContext())app.use(function (request, response, next) {  
  response.header("Access-Control-Allow-Origin", "\*")  
  response.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept")  
  next()  
});

This is the same code from the default template adding the uuid library. This takes care of initialising DynamoDB Document Client API to interact with DynamoDB, the DynamoDB table name taking into account the current environment and enabling CORS headers.

Let’s handle the first route, we will use the HTTP Method and path by the title for reference as in the next section. For each operation, first we will include the code from the client; and then, followed by the code serving it in the todosLambda.

Fetching todos (GET, /todos)

In the client, we use the Amplify JavaScript library aws-amplify to consume the REST API. In order to fetch the todos useAPI.get with the todosApi followed by the path /todos and an empty payload. The result is an array with the todos as part of the body. Remember to use JSON.parse as the result.body needs to be in plain text due to HTTP transport. The result object also contains the statusCode and path as url.

// client request: fetching todos  
import { API } from 'aws-amplify';

API.get('todosApi', '/todos', {}).then(result => {  
 this.todos = JSON.parse(result.body);  
}).catch(err => {  
 console.log(err);  
})

Let’s look at the code in todosLambda. To fetch todos, map a handler function to the GET Method and the /todos path. Then run a dynamodb.scan operation. This fetches all records in the table specified. Limit the results to 100 items. Find more details in the Developer Guide from Amazon DynamoDB.

Scan returns all the data in a table so you may consider to change it for a query if you expect more than just few records.

// todosLambda route handler: fetching todos
app.get("/todos", function (request, response) {  
  let params = {  
    TableName: tableName,  
    limit: 100  
  }  
  dynamodb.scan(params, (error, result) => {  
    if (error) {  
      response.json({ statusCode: 500, error: error.message });  
    } else {  
      response.json({ statusCode: 200, url: request.url, body: JSON.stringify(result.Items) })  
    }  
  });  
});

This returns the todos array as part of the body. Don’t forget to use JSON.stringifyas it needs to be in plain text due to HTTP transport.

Once the operation finishes, check for errors and create a JSON response accordingly. You will use the same approach in the rest of operations.

Fetching a todo by id (GET, /todos/:id)

Let’s quickly see the code necessary on the client below.

// client request: fetching a todo by id
import { API } from 'aws-amplify';

API.get('todosApi', `/todos/${id}`, {}).then((result) => {  
  this.todo = JSON.parse(result.body);  
}).catch(err => {  
  console.log(err);  
})

Notice how to use API.get with a path using a template string generating the path. Eg: /todos/${id} becomes "/todos/c71f0be2–607d-48bc-b721–4cb77c90a58f". The result receives the todo details.

Let’s see how to get the details from a single todo in todosLambda. In order to capture the todo id use route parameters, a feature from AWS Serverless Express. Route parameters use a semicolon to capture values at specific position in the URL like in /users/**:userId**/books/**:bookId**. Values are then available in the request object as request.params.userId and request.params.bookId.

// todosLambda route handler: fetching a todo by id
app.get("/todos/:id", function (request, response) {  
  let params = {  
    TableName: tableName,  
    Key: {  
      id: request.params.id  
    }  
  }  
  dynamodb.get(params, (error, result) => {  
    if (error) {  
      response.json({ statusCode: 500, error: error.message });  
    } else {  
      response.json({ statusCode: 200, url: request.url, body: JSON.stringify(result.Item) })  
    }  
  });  
});

As in the code above, use dynamodb.get to set your table and partition key Key.id from the request parameters.

For todosApi we only have a partition key, if you have a composed key (partition key + sort key) include the sort key too as part of the Key.sk.

Creating a new todo (POST, /todos)

In order to create a new todo, use API.post and set the payload to include the new todo description text within the request body.

// client request: creating a new todo
import { API } from 'aws-amplify';

API.post('todosApi', '/todos', {  
 body: {  
    text: "todo-1"  
  } 
}).then(result => {  
  this.todo = JSON.parse(result.body);  
}).catch(err => {  
  console.log(err);  
})

In todosLambda, creating a new todo is a bit more elaborated as we need to provide some new attributes and values. As we saw in the code above, the request.bodycontains the description for the new todo: text. Generate a new id, set complete to false, addcreatedAtand updatedAt timestamps and include the userId. To create the todo use dynamodb.put.

// todosLambda route handler: creating a new todoapp.post("/todos", function (request, response) {  
  const timestamp = new Date().toISOString(); 
  let params = {  
    TableName: tableName,  
    Item: {  
      ...request.body,  
      id: uuidv4(),               // auto-generate id  
      complete: false,            // default for new todos  
      createdAt: timestamp,  
      updatedAt: timestamp,  
      userId: getUserId(request)  // userId from request  
    }  
  } 
  dynamodb.put(params, (error, result) => {  
    if (error) {  
      response.json({ statusCode: 500, error: error.message, url: request.url });  
    } else {  
      response.json({ statusCode: 200, url: request.url, body: JSON.stringify(params.Item) })  
    }  
  });  
});

The helper function getUserId below extracts the user id from Amazon Cognito.

// todosLambda route handler: helper function
const getUserId = (request) => {  
  try {  
    const reqContext = request.apiGateway.event.requestContext;  
    const authProvider = reqContext.identity.cognitoAuthenticationProvider;  
    return authProvider ? authProvider.split(":CognitoSignIn:").pop() : "UNAUTH";  
  } catch (error) {  
    return "UNAUTH"; 
  }  
}

This code tries to capture the user id from the request identity context and if unsuccessful, returns an unauthorised token with UNAUTH as the value.

Updating a todo (PUT, /todos)

At this point you should know how to use the Amplify API. In order to update a todo use API.put and the /todos path. As you did creating a new todo provide the todo changes including its id as part of the body. As in the code below, change both the description and the complete values. The result contains any fields that were changed and their new values.

// client request: updating a todo
import { API } from 'aws-amplify';

API.put('todosApi', `/todos`, {   
 body: {  
    id: id,  
    text: "todo-2",  
    complete: true  
  }  
}).then(result => {  
  this.todo = JSON.parse(result.body);  
}).catch(err => {  
  console.log(err);  
})

The update in todosLambda uses most of the code you are already familiar but including a new update expression. This expression includes optional attributes so we need to create it dynamically. Eg: to service a request changing only the description text but not the other attributes. We used UPDATED_NEW to return only the updated attributes in DynamoDB but if you need all attributes use ALL_NEW.

// todosLambda route handler: updating a todo
app.put("/todos", function (request, response) {  
  const timestamp = new Date().toISOString(); 
  const params = {  
    TableName: tableName,  
    Key: {  
      id: request.body.id,
    },  
    ExpressionAttributeNames: { '#text': 'text' },  
    ExpressionAttributeValues: {},  
    ReturnValues: 'UPDATED_NEW',
  };  
  params.UpdateExpression = 'SET ';  
  if (request.body.text) {  
    params.ExpressionAttributeValues[':text'] = request.body.text;  
    params.UpdateExpression += '#text = :text, ';  
  }  
  if (request.body.complete) {  
    params.ExpressionAttributeValues[':complete'] = request.body.complete;  
    params.UpdateExpression += 'complete = :complete, ';  
  }  
  if (request.body.text || request.body.complete) {  
    params.ExpressionAttributeValues[':updatedAt'] = timestamp;  
    params.UpdateExpression += 'updatedAt = :updatedAt';  
  }  
  dynamodb.update(params, (error, result) => {  
    if (error) {  
      response.json({ statusCode: 500, error: error.message, url: request.url });  
    } else {  
      response.json({ statusCode: 200, url: request.url, body: JSON.stringify(result.Attributes) })  
    }  
  });  
});

To keep the semantics of HTTP PUT use the todo id from request.body.id instead of the request.params.id.

Deleting a todo by id (DELETE, /todos/:id)

Let’s implement the request to delete a todo. On the client, use API.del with a path including the id as a route parameter. If successful, the result body will be {} with statusCode:200.

// client request: deleting a todo by id
import { API } from 'aws-amplify';

API.del('todosApi', `/todos/${id}`, {}).then(result => {  
  console.log(result);  
}).catch(err => {  
  console.log(err);  
})

In todosLambda, use the same techniques from the previous route handlers now using dynamodb.delete operation.

// todosLambda route handler: deleting a todo by id
app.delete("/todos/:id", function (request, response) {  
  let params = {  
    TableName: tableName,  
    Key: {  
      id: request.params.id 
    }  
  }  
  dynamodb.delete(params, (error, result) => {  
    if (error) {  
      response.json({ statusCode: 500, error: error.message, url: request.url });  
    } else {  
      response.json({ statusCode: 200, url: request.url, body: JSON.stringify(result) })  
    }  
  });  
});

This completes all the CRUD operations. Before we can test it we need to publish it.

Pushing your new REST API to the cloud

Let’s deploy the new REST API in the cloud by running this command in the root of your project:

amplify push

At the end of this command you can take note of your new REST API url.

REST APIs follow this pattern https://{restapi-id}.execute-api.{region}.amazonaws.com/{environment}/{path}

Let’s see an overview of all the resources created by Amplify CLI.

REST  
 |\_ /todos (path)  
    |\_ todosApi (Amazon API Gateway)   
       |\_ todosLambda (AWS Lambda)  
          |\_ Logs (Amazon CloudWatch)

We have covered all AWS Services but Amazon CloudWatch. This service will allow you to monitor usage and access to logs during development and testing.

Publishing your app via the AWS Amplify Console

The first thing you need to do is create a new repo for this project. Once you’ve created the repo, copy the URL for the project to the clipboard and initialise git in your local project:

git init  
git remote add origin [repo@repoofyourchoice.com](mailto:repo@repoofyourchoice.com):username/project-name.git  
git add .git commit -m 'initial commit'git push origin master

AWS Amplify Console deployment steps.

Cleaning up cloud services

If at any time, you would like to delete the services from your project and your AWS Account, you can do this by running:

amplify delete

Conclusion

Congratulations! You successfully created a REST API using AWS Amplify, implemented all CRUD operations using Amazon DynamoDB and created a client to consume it restricting access to both registered users and guests using Vue. Thanks for following this tutorial.

If you prefer, you can also follow this video to achieve the same result.

Thanks for reading!

Have you got any questions about this tutorial or AWS Amplify? Feel free to reach me anytime at @gerardsans.

My Name is Gerard Sans. I am a Developer Advocate at AWS Mobile working with AWS Amplify and AWS AppSync teams.

Create a cloud-enabled GraphQL API with AWS Amplify and Vue

gerard-sans — Mon, 28 Sep 2020 20:49:56 +0000

In this tutorial, we will learn how to build a GraphQL data-driven serverless app using Vue, AWS Amplify and AWS AppSync. We will create a new project with Vue, generate a serverless GraphQL API using AWS AppSync and build a client to consume it including real-time. We will cover:

Introduction to AWS AppSync
Setting up a new project with the Vue CLI
Creating a new GraphQL API and using your first GraphQL transform
Pushing your GraphQL API to the cloud
Building the client: adding queries, mutations and real-time
Publishing your app via the AWS Amplify Console
Cleaning up cloud services

In order to follow this post you will need a basic knowledge of GraphQL. You can learn the basics following this tutorial at graphql.org.

> Final solution and step by step tutorial in GitHub.

Please let me know if you have any questions or want to learn more at @gerardsans.

Introduction to AWS AppSync

AWS AppSync allows you to create highly scalable serverless GraphQL data-driven mobile and web apps by providing an open source Amplify Framework (consisting of AWS AppSync Clients, GraphQL transforms and the CLI), integrations with multiple data sources, and the AWS AppSync console.

GraphQL client: client-side library to securely access data from your GraphQL API. Built-in support for real-time and offline/delta client synchronisation.
Amplify CLI: set of commands, via theapi category, to automate the setup and provision of resources for AWS AppSync and Amazon API Gateway cloud services. Support for REST and GraphQL APIs.
GraphQL Transforms: custom GraphQL schema directives that can be used in your GraphQL schema to enable custom workflows.
Data sources: databases (Amazon DynamoDB for NoSQL, Amazon Aurora for RDBMS), searches (Amazon Elasticsearch Service), and AWS Lambda functions.

By using AWS AppSync, teams can quickly create highly scalable serverless GraphQL data-driven apps for mobile and web while leaving the heavy lifting to the Amplify CLI.

AWS AppSync data-driven apps architecture overview

Setting up a new project with the Vue CLI

Before moving to the next section, please complete the steps described in “Build your first full-stack serverless app with Vue”.

Creating a new GraphQL API

For this post we are going to create a GraphQL API to list our favourite restaurants. To create it, we will use the following command:

amplify add api

Answer the following questions

Please select from one of the below mentioned services GraphQL
Provide API name: RestaurantAPI
Choose the default authorization type for the API API key
Enter a description for the API key: (empty)
After how many days from now the API key should expire (1–365): 7
Do you want to configure advanced settings for the GraphQL API No, I am done.
Do you have an annotated GraphQL schema? No
Choose a schema template: Single object with fields (e.g., “Todo” with ID, name, description)
Do you want to edit the schema now? Yes

When prompted, replace the default schema with the following:

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

You should be familiar with everything in the GraphQL schema above but for the @model directive. This is a GraphQL transform provided by AppSync.

Using your first GraphQL transform

GraphQL transforms allow AppSync to provide further customisation and support for common scenarios, so you don’t have to.

By adding@model to theRestauranttype we are telling the Amplify CLI runtime to create the resolvers to support queries, mutations and subscriptions in DynamoDB. Besides the regular CRUD operations, we are also getting some more advanced features like pagination and filtering that we are going to cover later.

Once we apply@model to a type we get access to these other transforms:

@key to configure custom index structures in DynamoDB
@searchable to enable searches using Amazon Elasticsearch Service
@connection to add relationships between types
@lambda to generate AWS Lambda resolvers
@auth to add fine grained multi-authorisation support
@versioned to add conflict resolution for offline scenarios

Learn how to use each transform in detail from the official docs.

GraphQL Transforms are implemented using custom GraphQL schema directives as defined in the GraphQL specification.

Pushing your GraphQL API to the cloud

Let’s run the push command to create the GraphQL API and see the results of using the @model transform:

amplify push

Are you sure you want to continue? Yes
Do you want to generate code for your newly created GraphQL API Yes
Choose the code generation language target javascript
Enter the file name pattern of graphql queries, mutations and subscriptions src/graphql/**/*.js
Do you want to generate/update all possible GraphQL operations — queries, mutations and subscriptions Yes
Enter maximum statement depth [increase from default if your schema is deeply nested] 2

Write down your GraphQL endpoint and API KEY.

Run the command below to access the AWS AppSync console.

amplify console api

Please select from one of the below mentioned services GraphQL

Testing your new GraphQL API

Once in the AWS AppSync console, click on Queries on the left side. This will open an editor that we can use to edit and test GraphQL queries.

Execute the following mutation to create a new restaurant:

mutation createRestaurant {  
  createRestaurant(input: {  
    name: "Nobu"  
    description: "Great Sushi"  
    city: "New York"  
  }) {  
    id name description city  
  }  
}

Now, run this query to list the restaurant we just added:

query listRestaurants {  
  listRestaurants {  
    items {  
      id  
      name  
      description  
      city  
    }  
  }  
}

Besides creating all common CRUD operations for your types, AWS AppSync also creates extra utility features like filters. Run this query to try using filters:

query searchRestaurants {  
  listRestaurants(filter: {  
    city: {  
      contains: "New York"  
    }  
  }) {  
    items {  
      id  
      name  
      description  
      city  
    }  
  }  
}

AWS AppSync creates filters on GraphQL scalar types (ID, String, Int, Float, Boolean) for list operations like listRestaurants.

Querying data with queries

In the earlier sections, we made sure we had a working GraphQL API. On the client, we will start by displaying a list.

<template>  
  <div v-for="restaurant of restaurants" :key="restaurant.id">  
    {{restaurant.name}}  
  </div>  
</template>  
<script>  
import { API, graphqlOperation } from 'aws-amplify';  
import { listRestaurants } from './graphql/queries';  

export default {  
  name: 'app',  
  data() {  
    return {  
      restaurants: [],  
    }  
  },  
  created() {  
    this.getData();  
  },  
  methods: {  
    async getData() {  
      try {  
        const response = await API.graphql(graphqlOperation(listRestaurants));  
        this.restaurants = response.data.listRestaurants.items;  
      }  
      catch (error) {  
        console.log('Error loading restaurants...', error);  
      }  
    },  
  }  
}  
</script>

From the code above, we are using API.graphqlto run the listRestaurantsquery within getData. Queries were created by the Amplify CLI during the push command. This call returns a promise that we handle by using async/await and render the result using v-for.

You might be wondering why we used listRestaurants.items. This is because AWS AppSync created an intermediate type ModelRestaurantConnection. This is so we can handle pagination scenarios together withlimit and nextTokenparameters.

listRestaurants(filter: ModelRestaurantFilterInput, limit: Int, nextToken: String): ModelRestaurantConnection 
type ModelRestaurantConnection {  
 items: [Restaurant]  
 nextToken: String  
}

Creating data with mutations

In order to add new restaurants, we are going to create a data entry using form to take the required user input and pass it forward to the createRestaurant mutation.

<template>  
  <div>  
    <form v-on:submit.prevent>  
      <div>  
        <label>Name: </label>  
        <input v-model='form.name' class='input' />  
      </div>  
      ...  
      <button @click='createRestaurant' class='button'>Create</button>  
    </form>  
  </div>  
</template>  
<script>  
import { createRestaurant } from './graphql/mutations';  

export default {  
  name: 'app',  
  data() {  
    return {  
      form: { },  
    }  
  },  
  methods: {  
    async createRestaurant() {  
      const { name, description, city } = this.form  
      if (!name || !description || !city) return;  

      const restaurant = { name, description, city };  
      try {  
        const response = await API.graphql(graphqlOperation(createRestaurant, { input: restaurant }))  
        console.log('Item created!')  
        this.restaurants = [...this.restaurants, response.data.createRestaurant];  
        this.form = { name: '', description: '', city: '' };  
      } catch (error) {  
        console.log('Error creating restaurant...', error)  
      }  
    },  
  }  
}  
</script>

Note how AWS AppSync instead of passing each field as an argument created an input type CreateRestaurantInput which makes our client code simpler and convenient.

type Mutation {  
 createRestaurant(input: CreateRestaurantInput!): Restaurant  
}input CreateRestaurantInput {  
 id: ID  
 name: String!  
 description: String!  
 city: String!  
}

As we did before with queries, we are using async/await to run our mutation as we submit the form via onCreate. Once we get the result, we use the form data to update the list and clear the form inputs.

Adding real-time with subscriptions

To demonstrate real-time, we are going to use a subscription to update AppSync clients when new restaurants are added. AppSync clients will subscribe to listen for changes going through our GraphQL API. More specifically, restaurant creation mutations.

import { onCreateRestaurant } from './graphql/subscriptions';  

export default {  
  name: 'app',  
  created() {  
    //Subscribe to changes  
    API.graphql(graphqlOperation(onCreateRestaurant))  
    .subscribe((sourceData) => {  
      const newRestaurant = sourceData.value.data.onCreateRestaurant  
      if (newRestaurant) {  
        // skip our own mutations and duplicates  
        if (this.restaurants.some(r => r.id == newRestaurant.id)) return;  
        this.restaurants = [newRestaurant, ...this.restaurants];  
      }   
    });  
  },  
}

We use createdto setup the subscription and immediately subscribe to start listening for notifications. Then for each notification, we will update our list of restaurants with changes.

Publishing your app via the AWS Amplify Console

The first thing you need to do is create a new repo for this project. Once you’ve created the repo, copy the URL for the project to the clipboard and initialise git in your local project:

git init  
git remote add origin [repo@repoofyourchoice.com](mailto:repo@repoofyourchoice.com):username/project-name.git  
git add .git commit -m 'initial commit'git push origin master

AWS Amplify Console deployment steps.

Cleaning up cloud services

If at any time, you would like to delete a service from your project and your AWS Account, you can do this by running:

amplify delete

Conclusion

Congratulations! You successfully built your first GraphQL API using Vue and AWS AppSync. Thanks for following this tutorial.

If you prefer, you can follow the instructions in this video to build the same app but deploying to Amazon Cloudfront and Amazon S3.

Thanks for reading!

Have you got any questions regarding this tutorial or AWS Amplify? Feel free to reach out to me anytime at @gerardsans.

My Name is Gerard Sans. I am a Developer Advocate at AWS Mobile working with AWS Amplify and AWS AppSync teams.
GraphQL is an open source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data.

Build your first full-stack serverless app with Vue and AWS Amplify

gerard-sans — Tue, 22 Sep 2020 12:57:56 +0000

Build flexible, scalable, and reliable apps with AWS Amplify

Introduction to AWS Amplify
Setting up a new project with the Vue CLI
Installing Amplify CLI
Adding authentication
Publishing your app
Cleaning up cloud services

Please let me know if you have any questions or want to learn more on the above at @gerardsans.

Introduction to AWS Amplify

Amplify libraries: in this article we will be using aws-amplify and @aws-amplify/ui-vue.
Amplify CLI: command line tool for configuring and integrating cloud services.
UI components: authenticator, photo picker, photo album and chat bot.
Cloud services: authentication, storage, analytics, notifications, AWS Lambda functions, REST and GraphQL APIs, predictions, chat bots and extended reality (AR/VR).
Offline-first support: Amplify DataStore provides a programming model for leveraging shared and distributed data without writing additional code for data reconciliation between offline and online scenarios.

By using AWS Amplify, teams can focus on development while the Amplify team enforces best patterns and practices throughout the AWS Amplify stack.

Amplify CLI

The Amplify CLI provides a set of commands to help with repetitive tasks and automating cloud service setup and provision.

Some commands will prompt questions and provide sensible defaults to assist you during its execution. These are some common tasks. Run:

amplify init, to setup a new environment. Eg: dev, test, dist.
amplify push, to provision local resources to the cloud.
amplify status, to list local resources and their current status.

The Amplify CLI uses AWS CloudFormation to manage service configuration and resource provisioning via templates. This a declarative and atomic approach to configuration. Once a template is executed, it will either fail or succeed.

Setting up a new project with the Vue CLI

To get started, create a new project using the Vue CLI. If you already have it, skip to the next step. If not, install it and create the app using:

yarn global add @vue/cli  
vue create amplify-app

Navigate to the new directory and check everything checks out before continuing

cd amplify-app  
yarn serve

Prerequisites

Before going forward make sure you have gone through the instructions in our docs to sign up to your AWS Account and install and configure the Amplify CLI.

Setting up your Amplify project

AWS Amplify allows you to create different environments to define your preferences and settings. For any new project you need to run the command below and answer as follows:

amplify init

Enter a name for the project: amplify-app
Enter a name for the environment: dev
Choose your default editor: Visual Studio Code
Please choose the type of app that you’re building javascript
What javascript framework are you using vue
Source Directory Path: src
Distribution Directory Path: dist
Build Command: npm run-script build
Start Command: npm run-script serve
Do you want to use an AWS profile? Yes
Please choose the profile you want to use default

At this point, the Amplify CLI has initialised a new project and a new folder: amplify. The files in this folder hold your project configuration.

<amplify-app>  
    |\_ amplify  
      |\_ .config  
      |\_ #current-cloud-backend  
      |\_ backend  
      team-provider-info.json

Installing the AWS Amplify dependencies

Install the required dependencies for AWS Amplify and Vue using:

yarn add aws-amplify @aws-amplify/ui-vue

Adding authentication

AWS Amplify provides authentication via the auth category which gives us access to AWS Cognito. To add authentication use the following command:

amplify add auth

When prompted choose:

Do you want to use default authentication and security configuration?: Default configuration
How do you want users to be able to sign in when using your Cognito User Pool?: Username
Do you want to configure advanced settings? No

Pushing changes to the cloud

By running the push command, the cloud resources will be provisioned and created in your AWS account.

amplify push

To quickly check your newly created Cognito User Pool you can run

amplify status

To access the AWS Cognito Console at any time, go to the dashboard at https://console.aws.amazon.com/cognito. Also be sure that your region is set correctly.

Your resources have been created and you can start using them!

Configuring the Vue application

Reference the auto-generated aws-exports.js file that is now in your src folder. To configure the app, open main.ts and add the following code below the last import:

import Vue from 'vue'  
import App from './App.vue'  

+ import Amplify from 'aws-amplify';  
+ import '@aws-amplify/ui-vue';  
+ import aws\_exports from './aws-exports';  

+ Amplify.configure(aws\_exports);  

Vue.config.productionTip = false  

new Vue({  
  render: h => h(App),  
}).$mount('#app')

Using the Authenticator Component

AWS Amplify provides UI components that you can use in your app. Let’s add these components to the project

In order to use the authenticator component add it to src/App.vue:

<template>  
  <div id="app">  
+    <amplify-authenticator> 
+      <div>  
+        <h1>Hey, {{user.username}}!</h1>  
+        <amplify-sign-out></amplify-sign-out>  
+      </div> 
+    </amplify-authenticator>
  </div>  
</template>
<script>  
+ import { AuthState, onAuthUIStateChange } from '@aws-amplify/ui-components'

export default {  
  name: 'app',  
  data() {  
    return {  
+      user: { },
    }  
  },  
  created() {  
+    // authentication state managament  
+    onAuthUIStateChange((state, user) => {  
+      // set current user and load data after login  
+      if (state === AuthState.SignedIn) {  
+        this.user = user;  
+      }  
+    }) 
  }  
}  
</script>

You can run the app and see that an authentication flow has been added in front of your app component. This flow gives users the ability to sign up and sign in.

To view any users that were created, go back to the Cognito Dashboard at https://console.aws.amazon.com/cognito. Also be sure that your region is set correctly.

Alternatively you can also use:

amplify console auth

Accessing User Data

To access the user’s info using the Auth API. This will return a promise.

import { Auth } from 'aws-amplify';
Auth.currentAuthenticatedUser().then(console.log)

Publishing your app

To deploy and host your app on AWS, we can use the hosting category.

amplify add hosting

Select the plugin module to execute: Amazon CloudFront and S3
Select the environment setup: DEV
hosting bucket name YOURBUCKETNAME
index doc for the website index.html
error doc for the website index.html

Now, everything is set up & we can publish it:

amplify publish

Cleaning up Services

To wipe out all resources from your project and your AWS Account, you can do this by running:

amplify delete

Conclusion

Congratulations! You successfully built your first full-stack serverless app using Vue and AWS Amplify. Thanks for following this tutorial.

Thanks for reading!

Have you got any questions regarding this tutorial or AWS Amplify? Feel free to reach out to me anytime at @gerardsans.

My Name is Gerard Sans. I am a Developer Advocate at AWS Mobile working with AWS Amplify and AWS AppSync teams.