react-apple-signin-auth

react-apple-signin-auth wraps Apple’s official “Sign in with Apple” JS SDK in a ready-to-use React component, so teams can add Apple authentication without hand-rolling script loading, popup/redirect handling, or promise plumbing around window.AppleID. It ships a styled AppleSigninButton with light/dark themes, a render prop for fully custom UI, and a promisified appleAuthHelpers.signIn() for using the same auth flow without React at all (documented for Vue and other frontends).

The package has zero runtime dependencies beyond React itself, ships dual CJS/ESM builds with a proper exports map (fixing Vite’s stricter CJS interop as of 1.2.0), and bundles both Flow and TypeScript type definitions. Its README doubles as a troubleshooting guide for real Apple Sign In failure modes — popup/redirect origin mismatches, unregistered Return URLs, and blank-page redirects — reflecting lessons the maintainer accumulated from production usage and GitHub issues over several years.

What You Get

• A pre-styled AppleSigninButton component with light/dark uiType themes and the official Apple glyph
• A render prop escape hatch to fully own the button’s markup while reusing the click/auth handler
• appleAuthHelpers.signIn() — a promisified, framework-agnostic function to trigger Apple auth outside React
• useScript hook that lazily injects Apple’s appleid.auth.js script exactly once per page
• Dual CJS + ESM builds with a proper exports map, plus bundled TypeScript and Flow types
• Zero runtime dependencies beyond React/React-DOM peer deps

Common Use Cases

• Adding a compliant “Sign in with Apple” option alongside Google/Email auth on a SaaS login page
• Popup-based auth flows where the response is consumed entirely client-side via onSuccess
• Redirect-based (form_post) flows where a backend needs to receive and verify the Apple JWT
• Non-React frontends (Vue, plain JS) using only appleAuthHelpers.signIn() directly
• Pairing with the companion apple-signin-auth Node package to verify the returned id_token server-side

Under The Hood

Architecture The library is a thin, clearly layered wrapper: src/index.js is the sole entry point, exporting AppleSigninButton as the default and re-exporting appleAuthHelpers and useScript as named helpers. AppleSigninButton.jsx composes exactly two lower-level pieces — useScript (injects Apple’s external SDK script via a useEffect, deduped by querying existing <script> tags) and appleAuthHelpers.signIn (a promise-wrapped call into window.AppleID.auth). The polling concern of “wait for a global variable to exist” is factored out into a standalone waitForVar utility, reused by appleAuthHelpers rather than inlined. This separation means a change to how the Apple script loads or how the global API is invoked touches appleAuthHelpers/waitForVar only, never the UI layer, and the button component has no internal state beyond what React’s own effect system provides.

Tech Stack Plain JavaScript with Flow annotations (/* @flow */) throughout src/, transpiled via Babel to both CommonJS and ESM output (dist/ and dist/esm/), with TypeScript’s tsc --emitDeclarationOnly used purely to generate dist/types/*.d.ts from a hand-maintained ambient declaration file rather than from the Flow-typed source itself. The only runtime dependency is the peer-declared react/react-dom (>=16.8, hooks-based); dev tooling includes ESLint (airbnb config) with eslint-plugin-flowtype, Prettier, Husky pre-commit hooks, and CircleCI running the Jest suite on every push. A companion demo/ app (a separate Vite-based project) exercises the library for local development and is deployed via gh-pages.

Code Quality Each module has a colocated Jest test file (AppleSigninButton.test.js with a snapshot, appleAuthHelpers.test.js, useScript.test.js, index.test.js) plus a top-level __tests__/build.test.js, run under jsdom with Enzyme for component testing. jest.config.js enforces coverage thresholds (66% branches, 71% functions, 77% lines/statements) with an explicit @TODO push up over time comment acknowledging the bar isn’t yet high — an honest rather than inflated quality signal. Error handling is deliberate rather than accidental: signIn distinguishes popup vs. redirect flows, explicitly swallowing spurious promise rejections during real page navigation (redirect mode) with an inline comment explaining why, while still surfacing errors via onError or console.error in popup mode. The one real gap is type-system duplication — Flow types live in source, but the TypeScript definitions consumers actually get are a hand-authored .d.ts file that has to be kept in sync manually rather than generated from a single source of truth.

What Makes It Unique Rather than only exposing a styled button, the package deliberately ships two API surfaces at different abstraction levels: a full pre-built component (with a render prop for total UI control) and a bare, promisified appleAuthHelpers.signIn() that works in any frontend, documented explicitly for Vue usage. Its README goes further than most auth wrappers by documenting concrete production failure modes as first-class troubleshooting entries — the Vite 8 CJS-interop break (fixed by shipping proper dual builds with an exports map), popup/redirect origin mismatches that silently strand the auth flow, and blank-page redirects caused by unregistered Apple Return URLs — turning accumulated GitHub-issue knowledge into documentation rather than leaving it undiscoverable.