Migration

Migrate from 3.x to 4.x

Installation

Install the 4.x version of @aws-amplify/ui-vue and 6.x version of aws-amplify.

1. Updates to the Authenticator

The Authenticator has the following breaking changes:

The initialState property now accepts forgotPassword in place of resetPassword:

- <authenticator initial-state="resetPassword">
- </authenticator>
+ <authenticator initial-state="forgotPassword">
+ </authenticator>

The corresponding component slot has been updated to reflect the change as well:

-    <template v-slot:reset-password-header>
-      <h3
-        class="amplify-heading"
-        style="padding: var(--amplify-space-xl) 0 0 var(--amplify-space-xl)"
-      >
-        Did you forgot something?
-      </h3>
-    </template>
+    <template v-slot:forgot-password-header>
+      <h3
+        class="amplify-heading"
+        style="padding: var(--amplify-space-xl) 0 0 var(--amplify-space-xl)"
+      >
+        Did you forgot something?
+      </h3>
+    </template>

The user object provided after an end user has been authenticated has been updated to reflect the AuthUser interface available from aws-amplify/auth:

- interface AmplifyUser {
-   challengeName?: ChallengeName;
-   attributes?: CognitoAttributes;
-   username: string;  
- }
+ interface AuthUser  {
+   username: string;
+   userId: string;
+   signInDetails?: CognitoAuthSignInDetails;
+ }

AuthUser can be imported from aws-amplify/auth:

import { AuthUser } from 'aws-amplify/auth';

User attributes are now available by directly calling fetchUserAttribues:

import { fetchUserAttributes } from 'aws-amplify/auth';

const userAttributes = await fetchUserAttributes();

2.x to 3.x

Installation

Install the 3.x version of the @aws-amplify/ui-vue library and the 5.x version of the aws-amplify library.

Update and usage

@aws-amplify/ui-vue@3.x introduces the following breaking changes:

1. @aws-amplify/ui-vue@3.x moves automatic signin on signup logic to aws-amplify.

If you are overriding Auth.signUp, update the override function call to include the autoSignIn option set to enabled. If this change is not made, users will not be automatically signed in on signup.

 async handleSignUp(formData) {
  let { username, password, attributes } = formData;
  // custom username
  username = username.toLowerCase();
  attributes.email = attributes.email.toLowerCase();
  return Auth.signUp({
    username,
    password,
    attributes,
+   autoSignIn: {
+     enabled: true
+   }
  });
}

2. @aws-amplify/ui-vue@3.x removes legacy i18n translation keys

@aws-amplify/ui-vue@3.x replaces following legacy Authenticator texts:

• Send Code in reset password screen is replaced by Send code.
• Forgot your password? with the trailing space is replaced by Forgot your password.

If you were using I18n to translate those keys, please update your translations accordingly to match the new strings.

1.x to 2.x

Installation

Install the 2.x version of the @aws-amplify/ui-vue library.

Update Main

Update the main.js file and remove the references to the older ui-components library as see below:

main.js

- import {
-   applyPolyfills,
-   defineCustomElements,
- } from '@aws-amplify/ui-components/loader';

- applyPolyfills().then(() => {
-   defineCustomElements(window);
- });
- const app = createApp(App);
- app.config.isCustomElement = tag => tag.startsWith('amplify-');
- app.mount('#app');

import App from "./App.vue";
import { Amplify } from 'aws-amplify';
import awsconfig from './aws-exports';
import { createApp } from 'vue';
+ import '@aws-amplify/ui-vue/styles.css';

Amplify.configure(awsconfig);

createApp(App).mount('#app');

Usage

Using the Authenticator component is similar to the 1.x usage.

Below is an example of how to create an Authenticator.

App.vue

<script setup>
+ import { Authenticator } from '@aws-amplify/ui-vue';

</script>

<template>
-  <amplify-authenticator>
-    <div>
-      My App
-      <amplify-sign-out></amplify-sign-out>
-    </div>
-  </amplify-authenticator>
+  <authenticator>
+     <template v-slot="{ user, signOut }">
+      <h1>Hello {{ user.username }}!</h1>
+      <button @click="signOut">Sign Out</button>
+    </template>
+  </authenticator>
</template>

Breaking changes

The 2.x version of the Authenticator component has several differences from earlier versions. Here are a few of the major changes that you'll need to look out for.

Slots

All the slot locations have changed with the 2.x version of the Authenticator. To get a sense of the changes please check out the Headers and Footers section.

Form Fields

The 2.x version of the Authenticator has a different format for the formFields prop. It also no longer accepts inputProps nor hint. Instead, it's recommended that you use the Headers and Footers Slots or use the Sign Up Fields custimization. For more information on form field customizations please see the Form Field Customization section.

CSS Styling

The 2.x version of the Authenticator has a completely different set of CSS variables. Please look over the Amplify CSS Variables section for more information.

onAuthUIStateChange

Previous versions of Authenticator exposed a onAuthUIStateChange handler to detect Auth state changes. For similar functionality see useAuthenticator.