This article aims to provide the most recent step by step guide on how to scaffold a base project using Vue 3, Vuetify and Amplify components. Using amplify's Vue 3 getting started tutorial was a bit challenging in my opinion as certain steps (Injection of window.global
script in index.html was confusing, vite.config.js
setup was lacking import alias support, directory where amplify init
should be triggered isn't clearly stated) on the guide were not detailed enough to be followed by somebody completely new with using Amplify.
After reading through this article, you'd be able to:
- Run
npm run dev
successfully without facing import issues. - Get an amplify app in your AWS account.
- Have a base scaffold that could easily be extended with other core amplify components (GraphQL API, Hosting, Cognito-based Auth)
Pre-requisites
In order to follow this guide and the same exact scaffold, you will need to have the following CLIs installed on your machines.
-
Node 18
- I'm using the most latest version of NodeJS 18. I've installed mine usingnvm
(Node version manager). -
amplify
cli - You'll need the amplify cli to initialize the amplify app and provision backend resources later on. -
aws
cli - You'll need an AWS cli to configure pre-built AWS profiles that allows your machine to make changes on your AWS accounts.
Initialise the Vue 3 projects
As with any Vue 3 + Vite project, we have to scaffold the base project by using the pre-built tools provided by the Vue JS.
npm init vue@3
Install Dependencies
After the scaffolding of base components gets completed, navigate into the project's directory and install the dependencies required by the base application to run.
# Substitute this with your project name
cd ./aws-exam-trainer
npm install
Add Dependencies
We also need to install the following dependencies:
-
vuetify
- is the most popular UI library for VueJS projects. It requires literally no design skills to get you started in crafting visually decent frontend applications. -
aws-amplify
- is the base library used for accessing common integrations in Amplify such as API, Auth, Analytics, etc. This library is not coupled with UI-specific frameworks such as Vue and React JS. -
@aws-amplify/ui-vue
- is a VueJS-specific set of cloud connected components that makes trivial tasks (Upload to S3, Cognito-backed Integration, etc) easy and fast to implement.
npm install vuetify aws-amplify @aws-amplify/ui-vue
Initialising Amplify App
The next step is to initialise the Amplify app. This is done by running the amplify init
command inside the directory generated by the npm init vue@3
command from the first step.
amplify init
Running the command will present you with the following prompt and most of the configurations for vue 3 projects will be pre-filled for us. Just agree with the default configurations for now.
Note: It is recommended to run this command from the root of your app directory
? Enter a name for the project awsexamtrainer
The following configuration will be applied:
Project information
| Name: awsexamtrainer
| Environment: dev
| Default editor: Visual Studio Code
| App type: javascript
| Javascript framework: vue
| Source Directory Path: src
| Distribution Directory Path: dist
| Build Command: npm run-script build
| Start Command: npm run-script serve
? Initialize the project with the above configuration? Yes
Using default provider awscloudformation
The next important step is to configure the AWS named profile that will be used for provisioning the Amplify app. This profile will also be used for other operations that require changes to our AWS account, such as provisioning AppSync APIs and Cognito User Pools.
In my machine, I've configured a profile called my-poc-profile
and just selected this on the guided CLI provided by AWS amplify
? Select the authentication method you want to use: AWS profile
For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html
? Please choose the profile you want to use my-poc-profile
Adding backend environment dev to AWS Amplify app: dvmifg83sjtwe
Deployment completed.
Deploying root stack awsexamtrainer [ ---------------------------------------- ] 0/4
amplify-awsexamtrainer-dev-10… AWS::CloudFormation::Stack CREATE_IN_PROGRESS Sun Apr 09 2023 10:08:18…
DeploymentBucket AWS::S3::Bucket CREATE_IN_PROGRESS Sun Apr 09 2023 10:08:21…
AuthRole AWS::IAM::Role CREATE_IN_PROGRESS Sun Apr 09 2023 10:08:21…
UnauthRole AWS::IAM::Role CREATE_IN_PROGRESS Sun Apr 09 2023 10:08:21…
✔ Help improve Amplify CLI by sharing non sensitive configurations on failures (y/N) · no
Deployment state saved successfully.
✔ Initialized provider successfully.
✅ Initialized your environment successfully.
Your project has been successfully initialized and connected to the cloud!
Some next steps:
"amplify status" will show you what you've added already and if it's locally configured or deployed
"amplify add <category>" will allow you to add features like user login or a backend API
"amplify push" will build all your local backend resources and provision it in the cloud
"amplify console" to open the Amplify Console and view your project status
"amplify publish" will build all your local backend and frontend resources (if you have hosting category added) and provision it in the cloud
Pro tip:
Try "amplify add api" to create a backend API and then "amplify push" to deploy everything
At this point, you should now have an amplify app configured on your AWS account.
Plug Vuetify and Amplify to main.js file
In order to access Vuetify UI components and Amplify base libraries, we'll have to configure the default main.js
file generated by the vue init process with the following code.
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import './assets/main.css'
// Vuetify
import 'vuetify/styles'
import { createVuetify } from 'vuetify'
import * as components from 'vuetify/components'
import * as directives from 'vuetify/directives'
// Amplify
import { Amplify } from 'aws-amplify'
import awsExports from './aws-exports'
import AmplifyVue from '@aws-amplify/ui-vue'
Amplify.configure(awsExports)
const vuetify = createVuetify({
components,
directives
})
const app = createApp(App)
app.use(vuetify)
app.use(AmplifyVue)
app.use(router)
app.mount('#app')
Add window.global and global exports handle (Vite Users only) to index.html
In order to make use of the UI components provided by @aws-amplify/ui-vue
library to our vite-based project, we'll have to inject the snippet below that adds global
property to window and a global exports object required by Amplify components.
Please inject it on the same position to avoid getting unwanted behaviours and errors later on the development. (This is one nasty mistake I've made on my initial attempts on using Amplify + VueJS projects).
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" href="/favicon.ico" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Vite App</title>
</head>
<body>
<div id="app"></div>
<!--Add this snippet-->
<script>
window.global = window
var exports = {}
</script>
<!--End of snippet to inject-->
<script type="module" src="/src/main.js"></script>
</body>
</html>
Setup vite.config.js
We'll also have to configure the vite.config.js
file so it would end up like this instead of the one provided by the amplify getting started docs for Vue JS.
What makes this configuration better than the one provided by the amplify team is that it allows us to import vue components from src
folder without having to use relative paths.
Tip of the day
Importing components using static path syntax makes VueJS projects easier to maintain by:
- Making refactoring of dependent components paths in large projects more resilient to bugs caused by relative imports failures.
- Regardless of the depth of the dependent component, static path imports make it easy reference shared components by having a standard import location.
- Removes the cognitive effort required from developers in mentally resolving the relative paths of components they like to import.
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'url'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [vue()],
resolve: {
alias: [
{
find: './runtimeConfig',
replacement: './runtimeConfig.browser'
},
// This bit here is not mentioned in Amplify Docs
{ find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) }
]
}
})
For TypeScript users
For typescript users, you will have to configure the compilerOptions.skipLibCheck
option to your tsconfig.json
files to skip type checking of declaration files.
This can save time during compilation at the expense of type-system accuracy. For example, two libraries could define two copies of the same type in an inconsistent way. Rather than doing a full check of all d.ts
files, TypeScript will type check the code you specifically refer to in your app’s source code.
...
"compilerOptions": {
"skipLibCheck": true,
...
Testing the Base Scaffold
At this point, you should have a basic Vue 3 project that can access both Vuetify and Amplify components without facing compile issues.
npm run dev
You should be able to see the following web page on the port allocated to vite without errors.
What's Next?
On the next articles, I'll be showcasing how to:
- Install and customize a Cognito-backed login interface.
- Add an AppSync API that uses at least two types of resolvers (Lambda and DynamoDB)
- Automate the deployment of changes from github repos to S3+CloudFront web hosting setup.
The final project aims to generate AWS exam reviewer questions using OpenAI prompts based from a user provided link (Ideally an AWS Documentation web page).
What makes this project interesting is that AWS professionals can now generate reviewer questions in a matter of seconds, track their scores and generate reviewer content that changes over time.
Till then, see you soon.
Top comments (4)
Hey there! Great post. There's very little on the web at the moment that isn't dated and difficult to refactor to the latest changes to Amplify (especially the authenticator) and Vue 3. Thank you! It looks like you'll be covering Authentication next, which is awesome. If you can help folks understand how to best have a user's authentication persist across a full blown app (with views, composables, etc) then that would be great: ui.docs.amplify.aws/react/connecte.... No pressure, just wondering if you have had the same challenges I have with this.
Great post
Thanks Hector!
Great article, however I also had to change the default App.vue to use
<v-app>
and<v-main>
instead of<header>
and<main>
. Also, the vuetify styles are missing. I'm getting default styles, but hopefully I'll resolve soon.