In this workshop we'll learn how to build cloud-enabled web applications with Vue & AWS Amplify.
- Authentication
- GraphQL API with AWS AppSync
- Hosting
- Multiple Environments
- Deploying via the Amplify Console
- Removing / Deleting Services
- Node:
12.9.0
. Visit Node - npm:
6.10.3
. Packaged with Node otherwise run upgrade
npm install -g npm
To get started, we first need to create a new Vue project & change into the new directory using the Vue CLI.
If you already have it installed, skip to the next step. If not, either install the CLI & create the app or create a new app using:
npm install -g @vue/cli
vue create amplify-app
Vue CLI
- ? Please pick a preset: default (babel, eslint)
- ? Pick the package manager to use when installing dependencies: NPM
Now change into the new app directory and make sure it runs
cd amplify-app
npm run serve
Let's now install the AWS Amplify API & AWS Amplify Vue library:
npm install --save aws-amplify aws-amplify-vue
If you have issues related to EACCESS try using sudo:
sudo npm <command>
.
Next, we'll install the AWS Amplify CLI:
npm install -g @aws-amplify/cli
If you have issues related to fsevents with npm install. Try:
npm audit fix --force
.
Now we need to configure the CLI with our credentials:
amplify configure
If you'd like to see a video walkthrough of this configuration process, click here.
Here we'll walk through the amplify configure
setup. Once you've signed in to the AWS console, continue:
- Specify the AWS Region: eu-central-1 (Frankfurt)
- Specify the username of the new IAM user: amplify-app
In the AWS Console, click Next: Permissions, Next: Tags, Next: Review, & Create User to create the new IAM user. Then, return to the command line & press Enter.
- Enter the access key of the newly created user:
accessKeyId: (<YOUR_ACCESS_KEY_ID>)
secretAccessKey: (<YOUR_SECRET_ACCESS_KEY>) - Profile Name: default
To view the new created IAM User go to the dashboard at https://console.aws.amazon.com/iam/home#/users/. Also be sure that your region matches your selection.
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
Now, the AWS Amplify CLI has iniatilized a new project & you will see 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
To add authentication to our Amplify project, we can 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? Yes, I want to make some additional changes.
- What attributes are required for signing up? (Press <space> to select, <a> to toggle all, <i> to invert selection): Email
- Do you want to enable any of the following capabilities? (Press <space> to select, <a> to toggle all, <i> to invert selection): None
To select none just press
Enter
in the last option.
Now, we'll run the push command and the cloud resources will be created in our 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.
Now, our resources are created & we can start using them!
The first thing we need to do is to configure our Vue application to be aware of our new AWS Amplify project. We can do this by referencing the auto-generated aws-exports.js
file that is now in our src
folder.
To configure the app, open main.js and add the following code below the last import:
import Amplify, * as AmplifyModules from 'aws-amplify'
import { AmplifyPlugin } from 'aws-amplify-vue'
import awsconfig from './aws-exports'
Amplify.configure(awsconfig)
Vue.use(AmplifyPlugin, AmplifyModules)
Now, our app is ready to start using our AWS services.
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></amplify-authenticator>
</div>
</template>
Now, we can run the app and see that an Authentication flow has been added in front of our App component. This flow gives users the ability to sign up & 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 we can also use
amplify console auth
We can access the user's info now that they are signed in by calling currentAuthenticatedUser()
which returns a Promise.
<script>
import { Auth } from 'aws-amplify';
export default {
name: 'app',
data() {
return {
user: { },
}
},
methods: {
currentUser() {
Auth.currentAuthenticatedUser().then(user => {
this.user = user;
console.log(user);
})
}
}
}
</script>
The Authenticator
Component is a really easy way to get up and running with authentication, but in a real-world application we probably want more control over how our form looks & functions.
Let's look at how we might create our own authentication flow.
To get started, we would probably want to create input fields that would hold user input data in the state. For instance when signing up a new user, we would probably need 2 inputs to capture the user's email & password.
To do this, we could create a form like:
<form v-on:submit.prevent>
<div>
<label>Username: </label>
<input v-model='form.username' class='input' />
</div>
<div>
<label>Password: </label>
<input v-model='form.password' type="password" />
</div>
<button @click='signIn' class='button'>Sign In</button>
</form>
We'd also need to have a method that signed up & signed in users. We can us the Auth class to do this. The Auth class has over 30 methods including things like signUp
, signIn
, confirmSignUp
, confirmSignIn
, & forgotPassword
. These functions return a promise so they need to be handled asynchronously.
<script>
import { Auth } from 'aws-amplify';
export default {
name: 'login',
data() {
return {
form: {
username: '',
password: ''
}
}
},
methods: {
signIn() {
const { username, password } = this.form;
Auth.signIn(username, password).then(user => {
console.log('User signed in');
})
.catch((error) => console.log(`Error: ${error}`))
}
}
}
</script>
To add a GraphQL API, we can 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 an authorization type for the API API key
- 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? Yes
When prompted, update the schema to the following:
type Restaurant @model {
id: ID!
clientId: String
name: String!
description: String!
city: String!
}
Note: Don't forget to save the changes to the schema file!
Next, let's push the configuration to our account:
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
Notice your GraphQL endpoint and API KEY.
This step created a new AWS AppSync API. Use the command below to access the AWS AppSync dashboard. Make sure that your region is correct.
amplify console api
- Please select from one of the below mentioned services GraphQL
In the AWS AppSync console, on the left side click on Queries.
Execute the following mutation to create a new restaurant in the API:
mutation createRestaurant {
createRestaurant(input: {
name: "Nobu"
description: "Great Sushi"
city: "New York"
}) {
id name description city
}
}
Now, let's query for the restaurant:
query listRestaurants {
listRestaurants {
items {
id
name
description
city
}
}
}
We can even add search / filter capabilities when querying:
query searchRestaurants {
listRestaurants(filter: {
city: {
contains: "New York"
}
}) {
items {
id
name
description
city
}
}
}
Now that the GraphQL API is created we can begin interacting with it!
The first thing we'll do is perform a query to fetch data from our API.
To do so, we need to define the query, execute the query, store the data in our state, then list the items in our UI.
Read more about the Amplify GraphQL Client here.
<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() {
const response = await API.graphql(graphqlOperation(listRestaurants));
this.restaurants = response.data.listRestaurants.items;
},
}
</script>
Now, let's look at how we can create mutations.
<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: { },
clientId: null
}
},
created() {
this.clientId = uuid();
},
methods: {
async createRestaurant() {
try {
const { name, description, city } = this.form;
const restaurant = { name, description, city, clientId: this.clientId };
const response = await API.graphql(
graphqlOperation(createRestaurant, { input: restaurant })
);
this.restaurants = [...this.restaurants, response.data.createRestaurant];
this.form = { name: '', description: '', city: '' };
console.log('item created!')
} catch (err) {
console.log(err)
}
}
}
}
</script>
Next, let's see how we can create a subscription to subscribe to changes of data in our API.
To do so, we need to listen to the subscription, & update the state whenever a new piece of data comes in through the subscription.
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 (newRestaurant.clientId == this.clientId) return;
if (this.restaurants.some(r => r.id == newRestaurant.id)) return;
this.restaurants = [newRestaurant, ...this.restaurants];
}
});
},
}
To deploy & host your app on AWS, we can use the hosting
category.
amplify add hosting
- Select the environment setup: DEV (S3 only with HTTP)
- 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
You can create multiple environments for your application in which to create & test out new features without affecting the main environment which you are working on.
When you create a new environment from an existing environment, you are given a copy of the entire backend application stack from the original project. When you make changes in the new environment, you are then able to test these new changes in the new environment & merge only the changes that have been made since the new environment was created back into the original environment.
Let's take a look at how to create a new environment. In this new environment, we'll re-configure the GraphQL Schema to have another field for the pet owner.
First, we'll initialize a new environment using amplify init
:
amplify init
- Do you want to use an existing environment? N
- Enter a name for the environment: apiupdate
- Do you want to use an AWS profile? Y
- amplify-workshop-user
Once the new environment is initialized, we should be able to see some information about our environment setup by running:
amplify env list
| Environments |
| ------------ |
| dev |
| *apiupdate |
Now we can update the GraphQL Schema in amplify/backend/api/RestaurantAPI/schema.graphql
to the following (adding the owner field):
type Restaurant @model {
...
owner: String
}
Now, we can create this new stack by running amplify push
:
amplify push
After we test it out, we can now merge it into our original dev environment:
amplify env checkout dev
amplify status
amplify push
- Do you want to update code for your updated GraphQL API? Y
- Do you want to generate GraphQL statements? Y
We have looked at deploying via the Amplify CLI hosting category, but what about if we wanted continous deployment? For this, we can use the Amplify Console to deploy the application.
The first thing we need to do is create a new GitHub repo for this project. Once we've created the repo, we'll copy the URL for the project to the clipboard & initialize git in our local project:
git init
git remote add origin git@github.com:username/project-name.git
git add .
git commit -m 'initial commit'
git push origin master
Next we'll visit the Amplify Console in our AWS account at https://eu-central-1.console.aws.amazon.com/amplify/home.
Here, we'll click Get Started to create a new deployment. Next, authorize Github as the repository service.
Next, we'll choose the new repository & branch for the project we just created & click Next.
In the next screen, we'll create a new role & use this role to allow the Amplify Console to deploy these resources & click Next.
Finally, we can click Save and Deploy to deploy our application!
Now, we can push updates to Master to update our application.
If at any time, or at the end of this workshop, you would like to delete a service from your project & your account, you can do this by running the amplify remove
command:
amplify remove auth
amplify push
If you are unsure of what services you have enabled at any time, you can run the amplify status
command:
amplify status
amplify status
will give you the list of resources that are currently enabled in your app.
In order to follow this workshop you need to create and activate an Amazon Web Services account.
Follow the steps here
Message: The AWS Access Key Id needs a subscription for the service
Solution: Make sure you are subscribed to the free plan. Subscribe
Message: TypeError: fsevents is not a constructor
Solution: npm audit fix --force