Split the React and React Native documentation. Usage and Setup are really confusing.

[angineering]

Is your feature request related to a problem? Please describe.
It is very frustrating and confusing to try to get started with AWS amplify when building for react native, as the documentation does not make it clear on many accounts what work for react and what works for React Native. A lot of the examples error when trying them in React Native. I have so far spent several days making very little progress.

Describe the solution you'd like
Separate documentation for React and React Native. Even though they are similar languages they are very much not the same.

Describe alternatives you've considered
Scrapping AWS Amplify and using Firebase instead.

Additional context
Particularly full, working examples of custom UI and Authenticators you can try out. https://aws-amplify.github.io/amplify-js/media/authentication_guide.html#create-your-own-ui is not a working example. It should be changed to something you can just copy paste to try out.

[mlabieniec]

Thanks for the feedback, and apologies for your frustration. Our aws-amplify-react-native package actually utilizes the @aws-amplify/core and @aws-amplify/auth, storage etc. core modules (and coincidentally the core library API), so the API is actually the same code as the JS side. The only difference is the actual UI components, however, the API remains exactly the same as web.

We purposefully try to keep the API the same across platforms. This is the reason we combined the Framework support guides for react/react native, and similarly angular and ionic. The only key difference with RN is the react-native link for the amazon-cognito-identity-js library if you are not using Expo.

We also had migrated the majority of the specifics into new Getting Started guides, specific to framework:
https://aws-amplify.github.io/amplify-js/media/quick_start?platform=react-native
https://aws-amplify.github.io/amplify-js/media/quick_start?platform=react

For deeper guide for both React and React Native:
https://amplify.github.io/amplify-js/media/react_guide

And specifically each category outlines it's UI components and usage:
https://aws-amplify.github.io/amplify-js/media/authentication_guide#using-components-in-react

There is also a starter with a completely custom UI utilizing the base API here:
https://github.com/aws-samples/aws-mobile-react-native-starter

There is also a list maintained by one of our developer advocates with some specific React Native examples here:
https://github.com/dabit3/awesome-aws-amplify#react-native

Specifically around Auth a great custom UI here:
https://github.com/react-native-training/react-native-auth-starter

Can you let me know which part you are having a hard time with specifically? We are working on a large update to our docs that will move these over to a new repo as well so that we can iterate on them faster without requiring library build/test steps.

[angineering]

Thank you for the feedback. Very happy to hear the docs are being worked on.

In brief this is my status for react native.

The good :

• the Auth component from aws-amplify is working fine. I can use it directly. Really wish the api clearly specified the structure of the returned objects.
• I ended up combining Auth with react-native- navigation rather than using the Authenticator component. This worked.

The bad :

• spent 3 days trying to make the Authenticator component work. withAuthenticator and just wrapping my App component in it worked, but I couldn't get any customisation to work at all. Not even if I just copy pasted from github.
• a link in the documentation to a working custom Authenticator example would be amazing
• documentation should specify that sign up does not sign in
• it is not possible to configure my cognito user pool to use email to sign in rather than username. Have gone through the manual setup and tried changing a bunch of values. Frustrating.
• it's not possible to pull in changes created / modified in the cloud. I created a new cognito pool to use email and tried changing the json parameters to use this. It just ended up creating a new cognito pool with that name and details instead.
• the example saying how you need to change your use pool to use email with a screenshot should show how to get that setting to work. I couldn't find any way of changing to email after manual setup creates a username pool.
• it's not possible to remove the email verification parameter in the parameters.json. Setup claims it's required when trying to push the changes. Googling it says it's not a required parameter.

[mlabieniec]

Thanks @angineering this is really good information and I appreciate you taking the time to put it together. I think most of this is pretty clear and straight forward to address. I will try and get some of this addressed in the next major update which is (i'm hoping) to be this week. I'll update this issue with it for review if you are up for taking a look and letting me know if it covers these adequately i'd greatly appreciate it.

[angineering]

Thank you, I would be happy to have a look.

It's really great to hear it's already being addressed!

[karlmosenbacher]

I can agree that the documentation of how to implement a custom UI with authenticator needs improvement. As @angineering have I spent multiple days trying to implement a custom signup screen without success.

[mlabieniec]

@karlmosenbacher @angineering can you take a look at the following update to the authentication guide and let me know if this helps:

https://github.com/mlabieniec/docs/blob/master/js/authentication.md#using-components-in-react--react-native

I haven't exactly split these up completely yet, but provided a high-level overview of all the options available on the Authenticator and withAuthenticator in the top section, then deep-dive's following.

[angineering]

Thank you for the quick update @mlabieniec .

The new definitions of props are super helpful. Great addition!

Would you be able to add a note on how to:

• Configure auth setup to use email instead of username? I haven't been able to do this, and would love to.

• How to use email link verification instead of code?

• How to turn off email verification

Other comments:

I thought the federated prop only worked in React and not React Native? Has this changed?
export default withAuthenticator(App, // display federation/social provider buttons federated = {myFederatedConfig},

• Does "federated" prop work in react native? Clarify.

In the section "Using the Authenticator Component Directly":

• it is not entirely clear if the authenticator you define is then used later to wrap app (example 2), or if the <App /> should be next to all the custom sign-in components in example 1. Could you clarify?
• If you replace the default one with yours from example 1, will example 2 still work?
• If copy-pasted, do these examples work in React Native? (I would check, but sadly don't have time this week). When used it previously with custom components I would usually get errors about super being undefined etc.

on this line: "authData - additional data within authState; when the state is signedIn, it will return a user object." could you link to the definition of what a user object is?

• Link to user object definition

In Enabling Federated Identities:

• Does this now work with React Native? If not, please clarify at the top. Other documentation says it doesn't.

In the Federated Identities section it's in an easy-to-miss line specified that with React Native you have to do federation manually.

• Could this be in a bold note at the top of this section + with a small note every time there is a federation example? (One of many reasons I want the documentation for React and React Native to be separate)

• The link with jekyll in it doesn't resolve correctly

• Does WithFederated work in both react native and react, or only react?

• Is the hosted UI meant to be used for react / web applications only, or is it also meant for mobile? If used on mobile, how does it work? Does it open a web browser screen for auth? A screenshot and a clarification either way would be amazing. I've been assuming it's not meant to be used in apps, but was never entirely sure.

• just a heads up, {: .callout .callout--info} doesn't seem to be resolving where you've used it

Any chance we could have some screenshots of what e.g. the signup screen by default looks like on web and mobile if you use withAuthenticator(app) so people know what to expect?

Thank you so much for fixing the documentation!!

[mlabieniec]

@angineering thank you for the thorough feedback this is very helpful and I think it’s all pretty clear. I am going to review these with the team today and try to incorporate this all into my next push this afternoon. Thanks for taking the time to list all this out much appreciated.

[karlmosenbacher]

@mlabieniec thanks for the updated docs! Really appreciated.

I have one thought tho regarding the authenticator docs.
https://github.com/mlabieniec/docs/blob/master/js/authentication.md#using-the-authenticator-component-directly

It says in the docs that when using the authenticator it will give you more customization options for your UI. Does this mean that I can create my own SignUp screen or can I only customize the default SignUp screen? And how can I create my own SignUp screen? Will my customized screen work with the other screens? These are some question that would all be answered if you could give us a complete example in how to implement a custom screen with the authenticator. I know there is one for the withAuthenticator.

Before when adding the SignUp screen in the hide property of the Authenticator, the create account text disappeared in the SignIn screen, is it still like that?

BR

[mlabieniec]

@karlmosenbacher thanks for the input. Recently the withAuthenticator has been updated to also provide more customization, so it's not as locked down as before. However, you can't obviously place it where you'd like in your app or position it anywhere in particular is the caveat where you would probably use the Authenticator at this point. Does that make sense?

For the using particular parts of the Authenticator, you can customize it to only show particular parts i.e.

<Authenticator hideDefault={true}>
          <SignIn/>
 </Authenticator> 

Or use the hide prop to hide specific components, its up to you how you do it. And of course, you can go the route of tooling up your own and just use the API would be the final option for customization. A good example of that on react native here: https://github.com/react-native-training/react-native-auth-starter. Let me know if that clarifies, i'll keep this in mind with doing my next pass at the authentication guide this afternoon. Thanks again for taking the time to provide the feedback.

[karlmosenbacher]

@mlabieniec that makes absolutely sense, but Im afraid thats not the issue I am having, and I am trying to go away from using the API and take advantage of Authenticator (or withAuthenticator) as mush as possible.

Please correct me if Im wrong now, but I try to use the Authenticator in this way:

This would be in the App.js file (not index.js).

<Authenticator>
  <SignIn />
  <MyCustomSignUp />
</Authenticator>

and then in my MyCustomSignUp-component

 export class MyCustomSignUp extends React.Component {
  render () {
    const { authState } = this.props;
  
   if (authState === 'signUp') {
     return (
        My sign up screen content
       (use onStateChange to change from signUp state to signIn state
        when signUp is finished. Sign up using the API )
     );
    } else {
     return null;
    }
  }
}

I think I have seen a guide with this implementation but I dont know if its correct or not?

[powerful23]

@karlmosenbacher it should be like:

<Authenticator hideDefault={true}>
  <SignIn />
  <MyCustomSignUp />
</Authenticator>

And yes in your signUp component, you should render it or not based on the authState, and you can jump to other state by:

if (props.onStateChange) props.onStateChange(state, data);

[karlmosenbacher]

@powerful23 thanks for clarifying it!

[angineering]

hi @mlabieniec thank you again for working on this.

I was wondering if you would be able to quickly explain how to set up aws amplify to use email instead of username? as in the photo https://aws-amplify.github.io/docs/js/authentication#sign-up . It always sets up with username and makes it unchangeable whenever I do it. Can't wait for the new documentation :)