Migrate from Amplify JavaScript v5 to v6

This migration guide will help you upgrade your Amplify JavaScript project from v5 to v6. In order to provide you with a cleaner experience, better typings, improved support for NextJS, and improved tree-shaking leading to a much smaller bundle-size, we made the following changes for v6:

1. We have transitioned to an approach where you only import the features you need from each of our categories.
2. Most API’s now use named params instead of positional params, allowing for cleaner and more consistent typing.
3. We have enabled typescript strict mode on all categories and have added typing to help make it easier to connect your backend resources if you have chosen not to use the Amplify CLI.

Below is an example of how you would have previously interacted with the Amplify JavaScript library in v5.

1import { CognitoUser } from '@aws-amplify/auth';
2import { Auth } from 'aws-amplify';
3
4const handleSignIn = async ({
5  username,
6  password
7}: {
8  username: string;
9  password: string;
10}) => {
11  const user: CognitoUser = Auth.signIn(username, password);
12};

The following is an example of how you would accomplish the same functionality with v6, using our new imports and API surface.

1import { signIn } from 'aws-amplify/auth';
2
3const handleSignIn = async ({
4  username,
5  password
6}: {
7  username: string;
8  password: string;
9}) => {
10  const { isSignUpComplete, userId, nextStep } = signIn({ username, password });
11};

Step 1: Upgrade your dev environment

In order to use Amplify JavaScript v6, you will need to make sure you are using the following versions in your development environment:

• Node.js v16.x or later
• npm v9.7.1 or later

Step 2: Upgrade your Amplify project dependencies

Upgrade to the latest Amplify library using the following command:

1npm install aws-amplify@6

The aws-amplify package in v6 includes the categories below:

• Auth
• API
• Storage
• Analytics
• DataStore
• In-App Messaging

If you previously listed @aws-amplify namespaced packages for the above categories as dependencies in your package.json, you will need to remove them to avoid dependency duplication.

If you would like to use Geo, Predictions, PubSub, or Interactions you will need to install those packages separately. (see category-specific migration instructions)

Step 3: Upgrade Amplify CLI version and configuration file

If you created your project with Amplify CLI version < 12.5.1, upgrade your CLI version and regenerate your configuration file using the scripts below.

1amplify upgrade
2amplify push

This will generate a new configuration file called amplifyconfiguration.json

Wherever you called Amplify.configure({ aws-exports }); previously (usually in the root of your project) update your code as shown below

1import awsconfig from './aws-exports';
2
3Amplify.configure(awsconfig);

1import amplifyconfig from './amplifyconfiguration.json';
2
3Amplify.configure(amplifyconfig);

If you have previously configured Amplify by passing the configuration object literal when calling the Amplify.configure() function, you can now configure Amplify manually with type safety. Please refer to the documentation of each category that you are using for migration.

• Authentication - Set up and configure Amplify Auth - see Existing Resources tab
• API (GraphQL) - Configure the Amplify Library - see Existing AppSync GraphQL API tab
• API (REST) - Use existing AWS resources
• API (REST) - Define authorization rules
• Storage - Use existing AWS resources
• Analytics - Use existing AWS resources
• Analytics - Streaming analytics data (Kinesis)
• Analytics - Storing analytics data (Kinesis Firehose)
• Analytics - Personalized recommendations
• Interactions - Set up Amplify Interactions

Step 4: Update category usage

Auth

As of v6 of Amplify, you will now import the functional API’s directly from the aws-amplify/auth path as shown below. Use the switcher below to see the differences between v5 and v6:

1import { Auth } from 'aws-amplify';
2
3async function signIn() {
4  try {
5    const user = await Auth.signIn(username, password);
6  } catch (error) {
7    console.log('error signing in', error);
8  }
9}
10
11async function signOut() {
12  try {
13    await Auth.signOut();
14  } catch (error) {
15    console.log('error signing out: ', error);
16  }
17}

1import { signIn, signOut } from 'aws-amplify/auth';
2
3async function signIn({ username, password }) {
4  try {
5    const { isSignedIn, nextStep } = await signIn({ username, password });
6  } catch (error) {
7    console.log('error signing in', error);
8  }
9}
10
11async function handleSignOut() {
12  try {
13    await signOut();
14  } catch (error) {
15    console.log('error signing out: ', error);
16  }
17}

For a deeper look at v6 Auth functionality, check out our Authentication category documentation.

Analytics

As of v6 of Amplify, you will now import the functional API’s directly from the aws-amplify/analytics path as shown below. Note that in v6, the provider is determined by import path. The functions exported from aws-amplify/analytics use AWS Pinpoint. Use the switcher below to see the differences between v5 and v6:

1import { Analytics } from 'aws-amplify';
2
3Analytics.record({
4  name: 'albumVisit',
5  attributes: { genre: '', artist: '' },
6  metrics: { minutesListened: 30 }
7});
8
9Analytics.autoTrack('session', {
10  enable: true,
11  attributes: {
12    customizableField: 'attr'
13  },
14  provider: 'AWSPinpoint'
15});

1import { record, configureAutoTrack } from 'aws-amplify/analytics';
2
3record({
4  name: 'albumVisit',
5  attributes: { genre: '', artist: '' },
6  metrics: { minutesListened: 30 }
7});
8
9configureAutoTrack({
10  enable: true,
11  type: 'session',
12  options: {
13    attributes: {
14      customizableField: 'attr'
15    }
16  }
17});

For a deeper look at V6 Analytics functionality, check out our Analytics category documentation.

API (GraphQL)

As of v6 of Amplify, you will now import a function called generateClient from the aws-amplify/api path and use the client returned from that method to perform graphql operations as shown below. Use the switcher below to see the differences between v5 and v6:

1import { API, graphqlOperation } from 'aws-amplify';
2import { createTodo, updateTodo, deleteTodo } from './graphql/mutations';
3
4const todo = { 
5  name: 'My first todo', 
6  description: 'Hello world!'
7};
8
9/* create a todo */
10const newTodo = await API.graphql(
11  graphqlOperation(createTodo, {
12    input: todo
13  })
14);
15
16/* update a todo */
17const updatedTodo = await API.graphql(
18  graphqlOperation(updateTodo, {
19    input: {
20      id: newTodo.id,
21      name: 'Updated todo info'
22    }
23  })
24);
25
26/* delete a todo */
27await API.graphql(
28  graphqlOperation(deleteTodo, { 
29    input: { id: newTodo.id }
30  })
31);

1import { generateClient } from 'aws-amplify/api';
2import { createTodo, updateTodo, deleteTodo } from './graphql/mutations';
3
4const client = generateClient();
5
6const todo = {
7  name: 'My first todo',
8  description: 'Hello world!'
9};
10
11/* create a todo */
12const newTodo = await client.graphql({
13  query: createTodo,
14  variables: { input: todo }
15});
16
17/* update a todo */
18const updatedTodo = await client.graphql({
19  query: updateTodo,
20  variables: { input: {
21    id: newTodo.id,
22    name: 'Updated todo info'
23  }}
24});
25
26/* delete a todo */
27const deletedTodo = await client.graphql({
28  query: deleteTodo,
29  variables: { 
30    input: { id: newTodo.id }
31  }
32});

For a deeper look at how the GraphQL API functionality in V6, check out our API (GraphQL) category documentation.

API (Rest)

As of v6 of Amplify, you will now import the functional API’s directly from the aws-amplify/api path as shown below. Use the switcher below to see the differences between v5 and v6:

1import { Amplify, API } from 'aws-amplify';
2
3/* fetch data */
4async function getData() {
5  const apiName = 'MyApiName';
6  const path = '/path';
7  const options = {
8    headers: {} // OPTIONAL
9  };
10
11  return await API.get(apiName, path, options);
12}
13
14/* update data */
15async function postData() {
16  const apiName = 'MyApiName';
17  const path = '/path';
18  const options = {
19    body: { 
20      name: 'My first todo',
21      message: 'Hello world!'
22    },
23    headers: {} // OPTIONAL
24  };
25
26  return await API.post(apiName, path, options);
27}
28
29postData();
30
31/* delete data */
32async function deleteData() {
33  const apiName = 'MyApiName';
34  const path = '/path';
35  const options = {
36    headers: {} // OPTIONAL
37  };
38  return await API.del(apiName, path, options);
39}
40
41deleteData();

1import { get, put, del } from 'aws-amplify/api';
2
3/* fetch data */
4async function getTodo() {
5  const apiName = 'MyApiName';
6  const path = '/path';
7  const options = {
8    body: { 
9      name: 'My first todo',
10      message: 'Hello world!'
11    },
12    headers: {} // OPTIONAL
13  };
14
15  const restOperation = get({
16    apiName,
17    path,
18    options
19  });
20  return await restOperation.response;
21}
22
23/* update data */
24async function updateTodo() {
25  const apiName = 'MyApiName';
26  const path = '/path';
27  const options = {
28    body: { 
29      name: 'My first todo',
30      message: 'Hello world!'
31    },
32    headers: {} // OPTIONAL
33  };
34
35  const restOperation = put({
36    apiName,
37    path,
38    options
39  });
40  return await restOperation.response;
41}
42
43/* delete data */
44async function deleteTodo() {
45  const apiName = 'MyApiName';
46  const path = '/path';
47  const options = {
48    headers: {} // OPTIONAL
49  };
50
51  const restOperation = del({
52    apiName,
53    path,
54    options
55  });
56  return await restOperation.response;
57}

For a deeper look at how the REST API functionality in V6, check out our API (REST) category documentation.

In-App Messaging

As of v6 of Amplify, you will now import the functional API’s directly from the aws-amplify/in-app-messaging path as shown below. Use the switcher below to see the differences between v5 and v6:

1import { Notifications } from 'aws-amplify';
2
3const { InAppMessaging } = Notifications;
4InAppMessaging.syncMessages();
5
6const sendEvent = (eventName: string) => {
7  InAppMessaging.dispatchEvent({ name: eventName });
8}

1import {
2  dispatchEvent,
3  initializeInAppMessaging,
4  syncMessages
5} from 'aws-amplify/in-app-messaging';
6
7initializeInAppMessaging();
8syncMessages();
9
10const sendEvent = (eventName: string) => {
11  dispatchEvent({ name: eventName });
12}

For a deeper look at In App Messaging functionality in v6, check out our In App Messaging category documentation.

Interactions

To use Interactions in v6, you will first need to install the category as a separate dependency using the below command:

1npm install @aws-amplify/interactions

In v6, the AWSLexV2Provider provider will be included by default and you are no longer required to call Amplify.addPluggable. It is also recommended to integrate your App with AWS LexV2, as the default module exports are associated with AWS LexV2 APIs. Interactions operates in the same way as before, however, the configuration structure has changed somewhat. Use the switcher below to see the differences between v5 and v6:

1import { Amplify } from 'aws-amplify';
2import { AWSLexV2Provider } from '@aws-amplify/interactions';
3import awsconfig from './aws-exports';
4
5Amplify.configure(awsconfig);
6
7Amplify.addPluggable(new AWSLexV2Provider());
8const interactionsConfig = {
9  Interactions: {
10    bots: {
11      my_v2_bot: {
12        name: '<V2BotName>',
13        aliasId: '<V2BotAliasId>',
14        botId: '<V2BotBotId>',
15        localeId: '<V2BotLocaleId>',
16        region: '<V2BotRegion>',
17        providerName: 'AWSLexV2Provider',
18      },
19    }
20  }
21}
22
23Amplify.configure(interactionsConfig);

1import { Amplify } from 'aws-amplify';
2import amplifyconfig from './amplifyconfiguration.json';
3
4Amplify.configure(amplifyconfig);
5
6const interactionsConfig = {
7  LexV2: {
8    '<V2BotName>': {
9      aliasId: '<V2BotAliasId>',
10      botId: '<V2BotBotId>',
11      localeId: '<V2BotLocaleId>',
12      region: '<V2BotRegion>'
13    }
14  }
15}
16
17Amplify.configure({
18  ...Amplify.getConfig(),
19  Interactions: interactionsConfig
20});

For a deeper look at Interactions functionality in v6, check out our Interactions category documentation.

Predictions

To use Predictions in v6, you will first need to install the category as a separate dependency using the below command:

1npm install @aws-amplify/predictions

In v6, the provider will be included by default and you are no longer required to call Predictions.addPluggable to use this category. Otherwise, Predictions operates in the same way as before. Use the switcher below to see the differences between v5 and v6:

1import { Amplify } from 'aws-amplify';
2import {
3  Predictions,
4  AmazonAIPredictionsProvider
5} from '@aws-amplify/predictions';
6import awsconfig from './aws-exports';
7
8Amplify.configure(awsconfig);
9Predictions.addPluggable(new AmazonAIPredictionsProvider());
10
11const translateText = async ({ textToTranslate }) => {
12    const result = await Predictions.convert({
13      translateText: {
14        source: {
15          text: textToTranslate
16        }
17      }
18    });
19}

1import { Predictions } from '@aws-amplify/predictions';
2import { Amplify } from 'aws-amplify';
3import amplifyconfig from './amplifyconfiguration.json';
4
5Amplify.configure(amplifyConfig);
6
7const translateText = async ({ textToTranslate }) => {
8    const result = await Predictions.convert({
9      translateText: {
10        source: {
11          text: textToTranslate
12        }
13      }
14    });
15}

For a deeper look at Predictions functionality in v6, check out our Predictions category documentation.

PubSub

As of v6 of Amplify, you will now import the functional API’s directly from the aws-amplify/pubsub path as shown below. Use the switcher below to see the differences between v5 and v6:

1import { Amplify, PubSub } from 'aws-amplify';
2import { AWSIoTProvider } from '@aws-amplify/pubsub';
3
4// Apply plugin with configuration
5Amplify.addPluggable(
6  new AWSIoTProvider({
7    aws_pubsub_region: '<YOUR-IOT-REGION>',
8    aws_pubsub_endpoint:
9      'wss://xxxxxxxxxxxxx.iot.<YOUR-IOT-REGION>.amazonaws.com/mqtt'
10  })
11);
12
13// Step 1 - Create IAM policies for AWS IoT (see v5 docs)
14
15// Step 2 - Attach your policy to your Amazon Cognito Identity ID
16
17Auth.currentCredentials().then((info) => {
18  const cognitoIdentityId = info.identityId;
19});
20
21aws iot attach-policy --policy-name 'myIoTPolicy' --target '<YOUR_COGNITO_IDENTITY_ID>'
22
23// Step 3 - Allow Amazon Cognito Authenticated Role to access IoT Services

1import { Amplify } from 'aws-amplify';
2import { PubSub } from '@aws-amplify/pubsub';
3
4// Apply plugin with configuration
5const pubsub = new PubSub({
6  region: '<YOUR-IOT-REGION>',
7  endpoint:
8    'wss://xxxxxxxxxxxxx.iot.<YOUR-IOT-REGION>.amazonaws.com/mqtt'
9});
10
11// Step 1 - Create IAM policies for AWS IoT (see v5 docs)
12
13// Step 2 - Attach your policy to your Amazon Cognito Identity ID
14
15import { fetchAuthSession } from 'aws-amplify/auth';
16fetchAuthSession().then((info) => {
17  const cognitoIdentityId = info.identityId;
18});
19
20aws iot attach-policy --policy-name 'myIoTPolicy' --target '<YOUR_COGNITO_IDENTITY_ID>'
21
22// Step 3 - Allow Amazon Cognito Authenticated Role to access IoT Services

For a deeper look at PubSub functionality in V6, check out our PubSub category documentation.

Storage

As of v6 of Amplify, you will now import the functional API’s directly from the aws-amplify/storage path as shown below. Use the switcher below to see the differences between v5 and v6:

1import { Storage } from 'aws-amplify';
2
3// Upload a file with access level `public`
4const result = await Storage.put('test.txt', 'Hello', {
5  level: 'public',
6});
7
8// Generate a file download url with check if the file exists in the S3 bucket
9const url = await Storage.get('filename.txt', {
10  validateObjectExistence: true
11});

1import { getUrl, uploadData } from 'aws-amplify/storage';
2
3// Upload a file with access level `guest` as  the equivalent of `public` in v5
4const result = await uploadData({
5  key: 'test.txt',
6  data: 'Hello',
7  options: {
8    accessLevel: 'guest'
9  }
10}).result;
11
12// Generate a file download url with check if the file exists in the S3 bucket
13const url = await getUrl({
14  key: 'filename.txt',
15  options: {
16    validateObjectExistence: true
17  },
18});

For a deeper look at how the Storage functionality in V6, check out our Storage category documentation.

Utilities

As of v6 of Amplify, you will now import utility classes and instances from the aws-amplify/utils path as shown below. Use the switcher below to see the differences between v5 and v6:

1import {
2  ServiceWorker,
3  Cache,
4  Hub,
5  I18n,
6  Logger
7} from 'aws-amplify';
8
9// Service Worker 
10const serviceWorker = new ServiceWorker();
11
12// Cache 
13Cache.setItem(key, value, [options]);
14
15// Hub (Listening for messages) 
16class MyClass { 
17  constructor() { 
18    Hub.listen('auth', (data) => { 
19      const { payload } = data; 
20      this.onAuthEvent(payload);  
21      console.log('A new auth event has happened: ', data.payload.data.username + ' has ' + data.payload.event); 
22    }) 
23  }
24
25  onAuthEvent(payload) {
26    // ... your implementation
27  }
28}
29
30// Internationalization 
31I18n.setLanguage('fr');
32
33// Logger 
34const logger = new Logger('foo');
35
36logger.info('info bar'); 
37logger.debug('debug bar'); 
38logger.warn('warn bar'); 
39logger.error('error bar');

1import {
2  ServiceWorker,
3  Cache,
4  Hub,
5  I18n,
6  ConsoleLogger
7} from 'aws-amplify/utils';
8
9// Service Worker 
10const serviceWorker = new ServiceWorker();
11
12// Cache 
13Cache.setItem(key, value, [options]);
14
15// Hub (Listening for messages) 
16class MyClass { 
17  constructor() { 
18    Hub.listen('auth', (data) => { 
19      const { payload } = data; 
20      this.onAuthEvent(payload);  
21      console.log('A new auth event has happened: ', data.payload.data.username + ' has ' + data.payload.event); 
22    }) 
23  }
24
25  onAuthEvent(payload) { 
26    // ... your implementation 
27  } 
28}
29
30// Internationalization 
31I18n.setLanguage('fr');
32
33// Console Logger 
34const logger = new ConsoleLogger('foo');
35
36logger.info('info bar'); 
37logger.debug('debug bar'); 
38logger.warn('warn bar'); 
39logger.error('error bar');

For a deeper look at v6 Utilities, check out our Utilities documentation.