Lost in documentation which libraries we should use aws-amplify vs @aws-amplify

jeroenmeulendijks commented 2 years ago

Before creating a new issue, please confirm:

[X] I have searched for duplicate or closed issues and discussions.
[X] I have tried disabling all browser extensions or using a different browser
[X] I have tried deleting the node_modules folder and reinstalling my dependencies
[X] I have read the guide for submitting bug reports.

On which framework/platform are you having an issue?

React

Which UI component?

Other

How is your app built?

CRA

What browsers are you seeing the problem on?

No response

Please describe your bug.

I'm lost in the documentation on which amplify libraries I should use. How I understand https://github.com/aws-amplify/amplify-js/wiki/Amplify-Modularization is that you have aws-amplify which contains all the packages and then @aws-amplify/ which gives you access to a part of the amplify library. So that your bundle size is reduced.

I tried reading a lot of documentation to understand what the best practices are and it seems that doing @aws-amplify/ is the way to go. BUT than if you want to use @aws-amplify/ui-react the first install statement is: yarn add @aws-amplify/ui-react aws-amplify

And the ui-react library is indeed depending on aws-amplify. So does that mean we always have to include the whole library and cannot use a smaller portion of the amplify libs.

Would be nice if someone could clarify this for me. As some people (like first comment on https://github.com/aws-amplify/amplify-js/issues/8333) say you should not mix @aws-amplify/ with aws-amplify. Or does that exclude @aws-amplify/ui-react ?

What's the expected behaviour?

Clear documentation which is understandable.

Help us reproduce the bug!

Not completely sure this is actually a bug but I also could not find a better place to raise this issue.

Code Snippet

// Put your code below this line.

Additional information and screenshots

No response

cwomack commented 2 years ago

Hello, @jeroenmeulendijks 👋 and thanks for your questions. Just for clarity, aws-amplify will include all of the scoped packages it uses under the hood... while the @aws-amplify/[package] will allow for selected packages or parts of the library (like you stated).

In general, we recommend using aws-amplify as the only dependency in your project because you’ll get access to the scoped packages (like @aws-amplify/auth) as well to ensure there aren’t dependency mismatches in your project. Ideally you’ll still have the smallest bundle size because you are guaranteed to only have one version of each scoped package. The @aws-amplify/ui-* packages are separately added as dependencies because they are separate from Amplify’s core services and allow for developer choice on which frontend framework to install without unnecessary bloat.

For example, aws-amplify and @aws-amplify/auth both have a dependency on @aws-amplify/core and would result in two instances of Amplify being initialized. This would also generate double the logs and events, but only one being configured correctly. However, having both installed won't cause problems outside of this providing all Amplify packages are kept up to date (see this doc).

I'll review this with our documentation team to see if there's specific guidance or example scenarios where we could better outline when to use each option.

jeroenmeulendijks commented 2 years ago

Hi @cwomack,

Thanks for your quick reply and basically confirming what I thought.

Than my main problem is that when I run that command to check for duplicates I get back:

@aws-amplify/ui

That package is not in our package.json because we only include:

"@aws-amplify/api-graphql": "^2.3.4",
"@aws-amplify/auth": "^4.5.2",
"@aws-amplify/core": "^4.5.2",
"@aws-amplify/storage": "^4.4.21",
"@aws-amplify/ui-react": "^3.5.1",
"aws-amplify": "^4.3.20",

For readability I only included the aws-amplify packages.

But I'm now basically lost in how I could resolve this issue as I cannot remove aws-amplify from the package.json as that's required by @aws-amplify/ui-react. When I remove it I get all kinds of errors, which basically say that aws-amplify is missing.

I would like to get a setup in which I only use the @aws-amplify/<...> libraries, but I do not think that's possible at the moment.

Thanks for any insights on this.

cwomack commented 2 years ago

@jeroenmeulendijks can you clarify the reason that you're looking to use the scoped packages vs just including the whole aws-amplify library and then allowing tree shaking to remove what's not being used?

Going forward, it would be best to use the new UI packages as seen here https://ui.docs.amplify.aws/ because we'll be deprecating the aws-amplify/ui package in the near future.

chrisbonifacio commented 2 years ago

To expand a little on what @cwomack mentioned about tree shaking, if you have the aws-amplify package installed you can still import only the scoped packages wherever you need them in your application code.

jeroenmeulendijks commented 2 years ago

@cwomack and @chrisbonifacio I thought using the @aws-amplify/<...> was the 'new' way to use amplify (in a modular way) and aws-amplify was the 'old' way that included 1 big lib.

But I now understand you recommend using it like:

Package.json "@aws-amplify/ui-react": "^3.5.1", "aws-amplify": "^4.3.20",

And than in code: import { Amplify, Auth } from 'aws-amplify';

And have the build process remove any unused dependencies.

Just to be complete, I do not know where we include aws-amplify/ui, I guess its included by one of the dependencies we include.

abdallahshaban557 commented 2 years ago

@jeroenmeulendijks - do you need any further support or can we close this issue now?

jeroenmeulendijks commented 2 years ago

@abdallahshaban557 Assuming that my understanding is correct (see my last message) than I'm fine to close this issue.

chrisbonifacio commented 2 years ago

@abdallahshaban557 Assuming that my understanding is correct (see my last message) than I'm fine to close this issue.

Your understanding is correct, but what I meant was that you can have

Package.json "@aws-amplify/ui-react": "^3.5.1", "aws-amplify": "^4.3.20"

and still import the scoped packages like so:

import { Auth } from '@aws-amplify/auth';
import { Storage } from `@aws-amplify/storage`;

if you wanted or needed to 😃

aws-amplify / amplify-js