# react-apple-signin-auth

 Apple signin for React using the official Apple JS SDK

<a href="https://npmjs.com/package/react-apple-signin-auth">
  <img src="https://img.shields.io/npm/v/react-apple-signin-auth.svg"></img>
  <img src="https://img.shields.io/npm/dt/react-apple-signin-auth.svg"></img>
</a>
<a href="https://codecov.io/gh/A-Tokyo/react-apple-signin-auth">
  <img src="https://img.shields.io/codecov/c/github/a-tokyo/react-apple-signin-auth.svg"></img>
</a>
<a href="https://twitter.com/intent/follow?screen_name=ahmad_tokyo"><img src="https://img.shields.io/twitter/follow/ahmad_tokyo.svg?label=Follow%20@ahmad_tokyo" alt="Follow @ahmad_tokyo"></img></a>

[Checkout the demo for a quick start!](https://react-apple-signin-auth.ahmedtokyo.com)
<!-- [Checkout the demo for a quick start!](https://react-apple-signin-auth.ahmedtokyo.com) -->

<a href="https://react-apple-signin-auth.ahmedtokyo.com">
<img src="https://i.imgur.com/Z8avh0K.png"></img>
</a>

## Prerequisites
1. You should be enrolled in [Apple Developer Program](https://developer.apple.com/programs/).
2. Please have a look at [Apple documentation](
https://developer.apple.com/sign-in-with-apple/get-started/) related to "Sign in with Apple" feature.
3. You should create App ID and Service ID in your Apple Developer Account.
4. You should generate private key for your Service ID in your Apple Developer Account.

## Apple Signin Setup
Detailed configuration instructions can be found at [blog post](https://medium.com/@artyomefremov/add-sign-in-with-apple-button-to-your-website-today-part-1-12ed1444623a?postPublishedType=initial) and [Apple docs](https://help.apple.com/developer-account/#/dev1c0e25352) and [official apple docs for webpage signin](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/configuring_your_webpage_for_sign_in_with_apple).

## Installation

```bash
npm i react-apple-signin-auth
```
OR
```bash
yarn add react-apple-signin-auth
```

> Ships dual CJS + ESM builds with proper `exports`, so `import AppleSignin from 'react-apple-signin-auth'` works out-of-the-box in Vite, Next.js, webpack, Rollup, and native Node ESM. TypeScript types are bundled.

## Usage
[Checkout the demo for a quick start!](https://react-apple-signin-auth.ahmedtokyo.com)
```js
import AppleSignin from 'react-apple-signin-auth';

/** Apple Signin button */
const MyAppleSigninButton = () => (
  <AppleSignin
    /** Auth options passed to AppleID.auth.init() */
    authOptions={{
      /** Client ID - eg: 'com.example.com' */
      clientId: 'com.example.web',
      /** Requested scopes, seperated by spaces - eg: 'email name' */
      scope: 'email name',
      /** Apple's redirectURI - must be one of the URIs you added to the serviceID - the undocumented trick in apple docs is that you should call auth from a page that is listed as a redirectURI, localhost fails */
      redirectURI: 'https://example.com',
      /** State string that is returned with the apple response */
      state: 'state',
      /** Nonce */
      nonce: 'nonce',
      /** Uses popup auth instead of redirection */
      usePopup: ${authOptions.usePopup},
    }} // REQUIRED
    /** General props */
    uiType="dark"
    /** className */
    className="apple-auth-btn"
    /** Removes default style tag */
    noDefaultStyle={false}
    /** Allows to change the button's children, eg: for changing the button text */
    buttonExtraChildren="Continue with Apple"
    /** Extra controlling props */
    /** Called upon signin success in case authOptions.usePopup = true -- which means auth is handled client side */
    onSuccess={(response) => console.log(response)} // default = undefined
    /** Called upon signin error */
    onError={(error) => console.error(error)} // default = undefined
    /** Skips loading the apple script if true */
    skipScript={false} // default = undefined
    /** Apple image props */
    iconProp={{ style: { marginTop: '10px' } }} // default = undefined
    /** render function - called with all props - can be used to fully customize the UI by rendering your own component  */
    render={(props) => <button {...props}>My Custom Button</button>}
  />
);

export default MyAppleSigninButton;
```

##### Note about the response's `user` object
`onSuccess` response object will contain the user object on the first time attempt only. Meaning if you make another signIn attempt for the same account you will not get the user object.
### Raw JS functionality
a module called `appleAuthHelpers` is also exported to allow you to use the functionality without using the UI or relying on React. This works with any kind of frontend JS, eg: react, vue, etc... Note that you need to load the apple script yourself.
- Importing the apple script:
  ```js
  // using raw html:
  <script src="https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js" defer></script>

  // OR using react hooks:
  import { useScript, appleAuthHelpers } from 'react-apple-signin-auth';

  const myComponent = () => {
    useScript(appleAuthHelpers.APPLE_SCRIPT_SRC);
    // ...
  };

  export default myComponent;

  ```
- Using appleAuthHelpers:
  ```js
  import { appleAuthHelpers } from 'react-apple-signin-auth';
  // OR
  // import appleAuthHelpers from 'react-apple-signin-auth/dist/appleAuthHelpers'; // @unstable - might change with upgrades

  /**
   * perform apple signIn operation
   */
  appleAuthHelpers.signIn({
    authOptions: {
      // same as above
    },
    onSuccess: (response) => console.log(response),
    onError: (error) => console.error(error),
  });

  // OR

  /** promisified version - promise resolves with response on success or undefined on error -- note that this only work with usePopup: true */
  const response = await appleAuthHelpers.signIn({
    authOptions: {
      // same as above
    },
    onError: (error) => console.error(error),
  });

  if (response) {
    console.log(response);
  } else {
    console.error('Error performing apple signin.');
  }

  ```

## Server-side authentication (nodeJS backend)
Another library exists for server/backend support for Apple signin [apple-signin-auth](https://github.com/A-Tokyo/apple-signin-auth)

### Usage
- Install the library `yarn add apple-signin-auth` OR `npm i apple-signin-auth`
- Implement JWT verification logic
  ```js
  const appleSignin = require("apple-signin-auth");


  const { authorization, user } = req.body;

  try {
    const { sub: userAppleId } = await appleSignin.verifyIdToken(
      authorization.id_token, // We need to pass the token that we wish to decode.
      {
        audience: "com.example.web", // client id - The same one we used on the frontend, this is the secret key used for encoding and decoding the token.
        nonce: 'nonce' // nonce - The same one we used on the frontend - OPTIONAL
      }
    );
  } catch (err) {
    // Token is not verified
    console.error(err);
  }
  ```
#### Further resources:
- https://dev.to/onygami/how-to-add-signin-with-apple-on-your-website-43m9

### Related Projects
- [Apple Signin for Node JS](https://github.com/A-Tokyo/apple-signin-auth)
- [Apple Signin for React Native](https://github.com/invertase/react-native-apple-authentication)
- [Supabase Docs: Build a Social Auth App with Expo React Native](https://supabase.com/docs/guides/auth/quickstarts/with-expo-react-native-social-auth)

## Troubleshooting

### Vite 8 "Element type is invalid... but got: object"
Vite 8 tightened its CJS interop and no longer auto-unwraps `module.exports.default` when you `import` a CJS package. Resolved in **v1.2.0+** by shipping a native ESM build advertised through the `exports` field. Upgrade to 1.2.0 or newer; the workaround `legacy.inconsistentCjsInterop: true` in `vite.config.ts` is no longer needed.

### Popup doesn't close / `onSuccess` never fires (`usePopup: true`)
When `usePopup: true`, Apple's JS SDK only resolves the signin promise if `authOptions.redirectURI`'s origin exactly matches `window.location.origin`. If they differ, the popup completes the auth flow but the parent window never receives the `web_message` response, so the popup stays open and neither `onSuccess` nor `onError` fires.

- Make sure the page that calls `signIn` is served from the same origin as `redirectURI` (scheme + host + port).
- If you need a backend to receive the response (`form_post` flow), use `usePopup: false` the popup mode posts back to the opener window, not to your server.

Reference: [Apple Developer Forums thread 130666](https://developer.apple.com/forums/thread/130666).

### Blank page after redirect / `appleauth/jslog` errors
A blank page after the Apple redirect (often with a failed `appleauth/jslog` network request) means Apple's servers rejected the request because the page calling `signIn` isn't whitelisted on your Apple Service ID.

- In the Apple Developer Console, open your Service ID and make sure the page's origin is listed under **Return URLs**.
- `localhost` is rejected by Apple. For local development use a deployed staging URL or a hostname that resolves to your machine (eg: `127.0.0.1.nip.io`).
- The Service ID's `clientId`, `redirectURI`, and the origin serving the signin button must all be configured consistently.

## Contributing
Pull requests are highly appreciated! For major changes, please open an issue first to discuss what you would like to change.

### Getting Started
- Clone the repo: `git clone https://github.com/a-tokyo/react-apple-signin-auth`
- Install deps: `yarn`
- Start webpack development server on [localhost:3001](http://localhost:3001): `yarn start`
- To run/update the tests locally, run: `yarn test -u`