Quasar 2, Vite and AWS Amplify

This article covers implementing the latest Vue 3 modules from AWS in the Quasar 2 framework. Quasar and Amplify are both fast moving projects in a rapidly changing industry so there are a couple of small difficulties.

A full set of instructions is available from my open source publishing project. In this article, I’ll only cover the key steps along the way, making special note of anything that doesn’t appear in the official Quasar or Amplify docs.

Ultri homepage, built with Quasar and Amplify

Prerequisites

• Install Node v14 for development
• Install the latest Quasar CLI
• Install the latest Amplify CLI

Working with Distributed Teams?

If you are working with distributed teams or in an open source project it is a good idea to keep the AWS team-provider-info.json out of the repository.

Doing this before initializing Amplify ensures it doesn’t get committed by mistake. The team-provider-info.json can be maintained in another private repository.

echo # Adding for AWS Amplify teams >> .gitignore
echo **/team-provider-info.json >> .gitignore
git commit -a -m "Add AWS Amplify team-provider-info.json to .gitignore"
git push

Why do we do this?

It is not because there is super secret in the file, it wouldn’t help an attacker do much unless you’ve been futzing with the AWS permissions.

It is kept out so that any number of team environments without conflict. It may be deployed in multiple accounts, each with a dev and prod. If anyone checked theirs in, it would overwrite the file for others.

Configure Amplify on your machine

This step creates an AWS user with permissions appropriate for Amplify apps. You will need admin permissions in the AWS account to create the more limited Amplify user. There should be one Amplify user for each human user that needs to modify or access the back end.

amplify configure

You can choose the defaults provide by AWS unless you know of a particular need. At the end of the process you will have user credentials in ~/.aws/credentials

Initialize Amplify

This will create the files in the projects /amplify directory and an aws-exports.js in the /src directory.

DO NOT ACCEPT THE DEFAULTS WHEN RUNNING INIT.

amplify init

These are the important settings, use defaults or sound judgement on the others.

? Distribution Directory Path: dist/spa
? Build Command:  quasar build -m spa
? Start Command: quasar serve dist/spa --history

Add Amplify Auth

Amplify provides a full-featured authentication option with AWS Cognito. Most of the other Amplify services require an authenticated user to be useful.

amplify add auth

Most of the options are pretty straightforward, my choices are below. I broke the prompts into sections and comment briefly on each section. It shouldn’t matter what options you choose from the perspective of getting Amplify working with Quasar, that magic comes later.

Do you want to use the default authentication and security configuration? Manual configuration
Select the authentication/authorization services that you want to use: User Sign-Up, Sign-In, connected with AWS IAM controls (Enables per-user Storage features for images or other content, Analytics, and more)
Provide a friendly name for your resource that will be used to label this category in the project: ultriauthorization
Enter a name for your identity pool. ultri_identitypool
Allow unauthenticated logins? (Provides scoped down permissions that you can control via AWS IAM) No
Do you want to enable 3rd party authentication providers in your identity pool? No
Provide a name for your user pool: ultri_userpool

You must manually configure Amplify to use the desired. You can name the various services whatever makes sense to you. We don’t allow unauthenticated user in secure services, anonymous users can still access unsecured parts of the site like the home page and signup forms. I don’t have any third party apps setup, I will add them later.

Warning: you will not be able to edit these selections.
How do you want users to be able to sign in? Username
Do you want to add User Pool Groups? Yes
? Provide a name for your user pool group: admin
? Do you want to add another User Pool Group Yes
? Provide a name for your user pool group: tech
? Do you want to add another User Pool Group No
✔ Sort the user pool groups in order of preference · admin, tech
Do you want to add an admin queries API? No

By choosing a username as the sign in identifier we avoid having it tied to an email or telephone number that may not remain in the users control.

The admin and tech groups will be used later to perform platform maintenance and administration. We don’t create an admin queries API because there are set monthly cost in maintaining the API gateway and we don’t foresee managing all that many admins or techs.

Multifactor authentication (MFA) user login options: OPTIONAL (Individual users can use MFA)
For user login, select the MFA types: SMS Text Message, Time-Based One-Time Password (TOTP)

Make MFA optional at minimum, you might consider not enabling SMS text message MFA.

Specify an SMS authentication message: Your Ultri authentication code is {####}
Email based user registration/forgot password: Enabled (Requires per-user email entry at registration)
Specify an email verification subject: Your Ultri verification code
Specify an email verification message: Your Ultri verification code is {####}

Define the messaging used in the Cognito signup process. Enabling email-based forgot password resets will enable users to help themselves when they lose their passwords.

Do you want to override the default password policy for this User Pool? Yes
Enter the minimum password length for this User Pool: 12
Select the password character requirements for your userpool:

I only force the length complexity at the Cognito level. Forcing an uppercase, number, special characters,etc. can limits the users options for a memorable password. We will check password complexity in the client software to guide the user in choosing a secure password.

Warning: you will not be able to edit these selections.
What attributes are required for signing up? Email
Specify the app's refresh token expiration period (in days): 30

Require as little data as possible at signup reduces friction. If we don’t need the information we shouldn’t even ask for it at this point in the process.

Do you want to specify the user attributes this app can read and write? Yes
Specify read attributes: Address, Birthdate, Email, Family Name, Middle Name, Gender, Locale, Given Name, Name, Nickname, Phone Number, Preferred Username, Picture, Profile, Updated At, Website, Zone Info, Email Verified?, Phone Number Verified?
Specify write attributes: Address, Birthdate, Family Name, Middle Name, Gender, Locale, Given Name, Name, Nickname, Phone Number, Picture, Profile, Updated At, Website, Zone Info

We enable read/write on all Cognito attributes. If we need to persist any of that info about a user, Cognito will be the source of truth.

Do you want to enable any of the following capabilities? No
Do you want to use an OAuth flow? No
? Do you want to configure Lambda Triggers for Cognito? No

We skip enabling any services or Lambdas that would add to our monthly costs, those will only be added if there is a proven need.

Push the Auth config to the Backend

Amplify does all the heavy lifting in defining and deploying your backend infrastructure. You simply push the changes up to the current AWS enviro.

amply push

Amplify will pull down the current config and compare to what exists locally.

✔ Successfully pulled backend environment dev from the cloud.

    Current Environment: dev

┌──────────┬────────────────────┬───────────┬───────────────────┐
│ Category │ Resource name      │ Operation │ Provider plugin   │
├──────────┼────────────────────┼───────────┼───────────────────┤
│ Auth     │ userPoolGroups     │ Create    │ awscloudformation │
├──────────┼────────────────────┼───────────┼───────────────────┤
│ Auth     │ ultriauthorization │ Create    │ awscloudformation │
└──────────┴────────────────────┴───────────┴───────────────────┘
? Are you sure you want to continue? (Y/n) Y

If you enter Y to continue Amplify will push the required changes up to AWS and create the required infrastructure.

Install the Amplify modules

Install both the base JavaScript and the Vue 3 specific modules.

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

Create a Quasar Boot File

If you are new to Quasar you may wonder where the main.js file often used in a Vue project went. That file is not exposed directly in Quasar, if you want to add something to it you need to create a boot file and register that boot file in the quasar.config.js. You can name the boot file anything, but we suggest amplify.js as a common standard.

# /src/boot/amplify.js
import { boot } from "quasar/wrappers";
import { Amplify } from "aws-amplify";
import awsExports from "../aws-exports";
import AmplifyVue from "@aws-amplify/ui-vue";
Amplify.configure(awsExports);
export default boot(({ app }) => {
   app.use(AmplifyVue);
});

Register the boot file in Quasar

You use the name without extension, in this case amplify . Find the boot section and ad amplify to the array.

# /quasar.config.js
...
boot: [
    'i18n',
    'amplify'
],
...

Implement Homepage Auth for Testing

Replace the home page with a page that implements the AWS Authenticator.

# /pages/IndexPage.vue
<script setup>
  import { Authenticator } from '@aws-amplify/ui-vue';
  import '@aws-amplify/ui-vue/styles.css';
</script>
<template>
  <authenticator>
    <template v-slot="{ user, signOut }">
      <h1>Hello {{ user.username }}!</h1>
      <button @click="signOut">Sign Out</button>
    </template>
  </authenticator>
</template>

The Magic, Account for Amplify/Vite Oddities

Up to this point things were pretty much cookie-cutter, straight from the docs and best practices.

Fix “global” missing under Vite

# In the index.html add this script to ensure global is not undefined .

# /index.html
<script>
  var global = global || window;
</script>

Fix obtuse request errors

You need to extend the Vite config for runtimeConfig.

# /quasar.config.js
extendViteConf(viteConf) {
    viteConf.resolve.alias["./runtimeConfig"] = "./runtimeConfig.browser";
},

Create a SPA Redirect in Amplify Hosting

Amplify, or any other hosting provider you use, will need a redirect record.

This is the Source address, going to a Target address of /index.html , all on one line. It gets wrapped here on Medium.

</^[^.]+$|\.(?!(css|gif|ico|jpg|js|png|txt|svg|woff|woff2|ttf|map|json|webp)$)([^.]+$)/>

SPA rewrite record for static Quasar site on Amplify

Build Away

Builds should succeed and you should be able to treat this as a normal Amplify Quasar project.