Migration

@aws-amplify/ui-angular

Migrate from 4.x to 5.x

Installation

Install the 5.x version of @aws-amplify/ui-angular 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:

- <amplify-authenticator initialState="resetPassword">
- </amplify-authenticator>
+ <amplify-authenticator initialState="forgotPassword">
+ </amplify-authenticator>

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

- <ng-template amplifySlot="reset-password-header">
-   <h3
-     class="amplify-heading"
-     style="padding: var(--amplify-space-xl) 0 0 var(--amplify-space-xl)"
-   >
-     Did you forget something?
-   </h3>
- </ng-template>
+ <ng-template amplifySlot="forgot-password-header">
+   <h3
+     class="amplify-heading"
+     style="padding: var(--amplify-space-xl) 0 0 var(--amplify-space-xl)"
+   >
+     Did you forget something?
+   </h3>
+ </ng-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 fetchUserAttributes:

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

const userAttributes = await fetchUserAttributes();

The function signatures of the services interface have been updated to align with the shape of the underlying aws-amplify/auth APIs used by the Authenticator and provide improved typescript support:

interface AuthenticatorServices {
  services?: {
-    getCurrentUser?: () => Promise<any>,
+    getCurrentUser?: () => Promise<AuthUser>,

-    handleSignIn?: ({ username, password, }: { username: string;password: string; }) => Promise<any>,
+    handleSignIn?: (input: SignInInput) => Promise<SignInOutput>,

-    handleSignUp?: (formData: any) => Promise<ISignUpResult>,
+    handleSignUp?: (input: SignUpInput) => Promise<SignUpOutput>,

-    handleConfirmSignIn?: ({ user, code, mfaType, }: { user: any; code: string; mfaType: ChallengeName; }) =>Promise<any>),
+    handleConfirmSignIn?: (input: ConfirmSignInInput) => Promise<ConfirmSignInOutput>,

-    handleConfirmSignUp?: ({ username, code, }: { username: string; code: string; }) => Promise<any>,
+    handleConfirmSignUp?: (input: ConfirmSignUpInput) => Promise<ConfirmSignUpOutput>,

-    handleForgotPasswordSubmit?: ({ username, code, password, }: { username: string; code: string; password:string; }) => Promise<string>),
+    handleForgotPasswordSubmit?: (input: ConfirmResetPasswordInput) => Promise<void>,

-    handleForgotPassword?: (formData: any) => Promise<any>,
+    handleForgotPassword?: (input: ResetPasswordInput) => Promise<ResetPasswordOutput>,
  }
}

The input and return type interfaces are available as imports from aws-amplify/auth:

import { ConfirmSignInInput } from 'aws-amplify';

3.x to 4.x

Installation

Install the 4.x version of the @aws-amplify/ui-angular library.

Update and usage

@aws-amplify/ui-angular@4.x introduces the following breaking changes:

1. @aws-amplify/ui-angular@4.x bumps minimum Angular version to 14

If your application is on Angular 13 or older, please migrate to Angular 14+ as per official guide.

2. @aws-amplify/ui-angular@4.x requires @aws-amplify/ui-angular/theme.css to be imported via angular.json

Previous version of @aws-amplify/ui-angular required @aws-amplify/ui-angular/theme.css to be in your global CSS file. To migrate, you should first remove the style import from your global CSS:

- @import '~@aws-amplify/ui-angular/theme.css';

Then open your angular.json file, and add node_modules/@aws-amplify/ui-angular/theme.css to styles array. This array is located in projects.<project-name>.architect.build.options.

"styles": [
+ "node_modules/@aws-amplify/ui-angular/theme.css",
  "src/styles.css"
],

2.x to 3.x

Installation

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

Update and usage

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

1. @aws-amplify/ui-angular@3.x bumps minimum Angular version to 12

If your application is on Angular 11 or older, please migrate to Angular 12+ as per official guide.

Note: Going forward, @aws-amplify/ui-angular will have the same version support as Angular's official LTS support window.

2. @aws-amplify/ui-angular@3.x migrates Angular compiler to IVY

@aws-amplify/ui-angular@3.x drops support for legacy View engine, and migrated to the Ivy compiler. Please migrate to Angular 12+, and make sure you did not disable Ivy in your tsconfig.json. In particular, please remove "enableIvy": false in your tsconfig.json:

{
  ...,
  "angularCompilerOption": {
-    "enableIvy": false
  }
}

3. @aws-amplify/ui-angular@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
+   }
  });
}

4. @aws-amplify/ui-angular@3.x removes legacy i18n translation keys

We replaced following legacy Authenticator texts:

• Confirmation Code in confirm sign up screen is replaced by Enter your Code
• Send Code in reset password screen is replaced by Send code.
• Send Code in confirm reset password screen is replaced by Submit
• 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.

5. @aws-amplify/ui-angular@3.x removes legacy component exports

The following deprecated components imported from @aws-amplify/ui-angular/legacy are removed:

• AmplifyChatbot
• AmplifyPhotoPicker
• AmplifyPicker
• AmplifyS3Album
• AmplifyS3Image
• AmplifyS3ImagePicker
• AmplifyS3Text
• AmplifyS3TextPicker

If you wish to still use the legacy components, you can do so by installing @aws-amplify@2.x under an alias:

Then you can use the legacy components by registering LegacyAmplifyUiModule in your app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AmplifyAuthenticatorModule } from '@aws-amplify/ui-angular';
import { LegacyAmplifyUiModule } from '@aws-amplify/ui-angular-v2/legacy';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, AmplifyAuthenticatorModule, LegacyAmplifyUiModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

For more details on how to use the components, please see the v1 documentation.

1.x to 2.x

Installation

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

Update

Update the app.module.ts with the new AmplifyAuthenticatorModule and remove the old AmplifyUIAngularModule as seen below:

app.module.ts

- import { AmplifyUIAngularModule } from '@aws-amplify/ui-angular';
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';;
+ import { AmplifyAuthenticatorModule } from '@aws-amplify/ui-angular';

import { AppComponent } from './app.component';
import awsconfig from '../aws-exports';

Amplify.configure(awsconfig);

@NgModule({
  declarations: [AppComponent],
+ imports: [BrowserModule, AmplifyAuthenticatorModule],
- imports: [AmplifyUIAngularModule, BrowserModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}


);

You'll also have to import the styles in the styles.css file.

@import '~@aws-amplify/ui-angular/theme.css';

Usage

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

Below is an example of how to create an Authenticator.

app.component.html

- <amplify-authenticator usernameAlias="email">
-  <amplify-sign-up
-    slot="sign-up"
-  ></amplify-sign-up>
-  <amplify-sign-in slot="sign-in" usernameAlias="email"></amplify-sign-in>
- </amplify-authenticator>
+ <amplify-authenticator>
+  <ng-template
+    amplifySlot="authenticated"
+    let-user="user"
+    let-signOut="signOut"
+  >
+    <h1>Welcome {{ user.username }}!</h1>
+    <button (click)="signOut()">Sign Out</button>
+  </ng-template>
+</amplify-authenticator>

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 AuthenticatorService.