{"id":16727,"library":"firebase-auth-lite","title":"Firebase Auth Lite","description":"Firebase Auth Lite (Beta) is a lightweight, performance-focused alternative to the official Firebase Auth SDK, designed specifically for modern browser environments. Currently at version 0.8.9, it aims to deliver significantly smaller bundle sizes and faster authentication performance, claiming to be up to 27 times smaller and 13 times faster than the official SDK. The library is under active development, with its API explicitly stated as subject to change without warning until it reaches a stable 1.0 release. Key differentiators include a simplified API, enhanced client-side security through direct OAuth redirect handling, and limitations such as localStorage-only session persistence. It relies on modern browser features like the Fetch API and localStorage, requiring users to handle transpilation for broader browser compatibility. Its release cadence is ad-hoc, driven by development progress toward v1.0.","status":"active","version":"0.8.9","language":"javascript","source_language":"en","source_url":"https://github.com/samuelgozi/firebase-auth-lite","tags":["javascript"],"install":[{"cmd":"npm install firebase-auth-lite","lang":"bash","label":"npm"},{"cmd":"yarn add firebase-auth-lite","lang":"bash","label":"yarn"},{"cmd":"pnpm add firebase-auth-lite","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Auth is the default export of the library. It is designed for ESM environments, typically used in modern browsers or via bundlers. Avoid named imports or CommonJS `require`.","wrong":"import { Auth } from 'firebase-auth-lite';\nconst Auth = require('firebase-auth-lite');","symbol":"Auth","correct":"import Auth from 'firebase-auth-lite';"},{"note":"Auth is a class and must be instantiated with the `new` keyword. The `apiKey` option is required for most authentication flows.","wrong":"const auth = Auth({ apiKey: 'YOUR_API_KEY' });","symbol":"Auth instance","correct":"const auth = new Auth({ apiKey: 'YOUR_API_KEY' });"}],"quickstart":{"code":"import Auth from 'firebase-auth-lite';\n\n// Ensure you set your Firebase API Key, e.g., via environment variable\nconst API_KEY = process.env.FIREBASE_API_KEY ?? 'YOUR_FIREBASE_API_KEY_HERE';\n\n// Instantiate the Auth client\nconst auth = new Auth({\n  apiKey: API_KEY,\n  // Optional: Add a custom app name if needed\n  // appName: 'my-web-app'\n});\n\nasync function runAuthDemo() {\n  try {\n    console.log('Attempting to sign up a new user...');\n    // Example: Sign up with email and password\n    const newUser = await auth.signUpWithEmailAndPassword('test@example.com', 'password123');\n    console.log('New user signed up:', newUser.uid, newUser.email);\n\n    console.log('\\nAttempting to sign in existing user...');\n    // Example: Sign in with email and password\n    const user = await auth.signInWithEmailAndPassword('test@example.com', 'password123');\n    console.log('User signed in:', user.uid, user.email);\n\n    console.log('\\nGetting current user session...');\n    // Example: Get the currently signed-in user\n    const currentUser = await auth.getCurrentUser();\n    if (currentUser) {\n      console.log('Current active user:', currentUser.uid);\n    } else {\n      console.log('No user currently signed in.');\n    }\n\n    console.log('\\nAttempting to sign out user...');\n    // Example: Sign out\n    await auth.signOut();\n    console.log('User successfully signed out.');\n\n  } catch (error) {\n    console.error('Authentication failed:', error.code || error.message);\n    // As of v0.8.1, error messages are Firebase error codes.\n    // Map these codes to user-friendly messages using the official Firebase docs or the library's wiki.\n  }\n}\n\nrunAuthDemo();","lang":"javascript","description":"Demonstrates core authentication flows including user registration (sign-up), logging in (sign-in), retrieving the current user's session, and logging out (sign-out), showcasing typical API usage."},"warnings":[{"fix":"Refer to the Firebase Auth error code documentation or the `firebase-auth-lite` wiki (github.com/samuelgozi/firebase-auth-lite/wiki/Error-codes-map) to map error codes to displayable messages for your users.","message":"Error messages are no longer 'human friendly' English strings; instead, they are Firebase error code strings (e.g., 'auth/invalid-email'). You must implement your own mapping to user-friendly messages.","severity":"breaking","affected_versions":">=0.8.1"},{"fix":"Remove any `supportedProviders` options from your `Auth` instantiation. The library will now automatically handle provider support via server responses.","message":"The `signInWithProvider` function no longer requires you to provide a list of supported providers during `Auth` instantiation. The function will now throw a server-returned error if a provider is unsupported.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Be prepared for frequent API changes and review release notes for each update. Pinning to a specific patch version is recommended in production environments.","message":"This library is in 'Beta' and 'work in progress'. The API is explicitly stated to change without warning until version 1.0 is released.","severity":"gotcha","affected_versions":">=0.1"},{"fix":"Integrate Babel or another transpiler into your build process to target older browsers or environments that do not fully support modern JS features used by this library.","message":"The library only supports modern browsers and is written with modern JavaScript (Fetch API, localStorage). You are responsible for transpiling the code for wider browser compatibility (e.g., via Babel).","severity":"gotcha","affected_versions":">=0.1"},{"fix":"Be aware of this limitation if your application requires alternative session persistence mechanisms (e.g., cookies, sessionStorage). Plan accordingly for your security and UX requirements.","message":"Sessions can currently only be persisted in `localStorage`. More options may be added in future versions.","severity":"gotcha","affected_versions":">=0.1"},{"fix":"In your OAuth provider's console (e.g., Google Cloud Console), configure the redirect URI to point to the specific page in your application that will handle the login redirect.","message":"When setting up Federated Identity Providers (e.g., Google, Facebook OAuth), you must whitelist *your application's own URL* as the redirect URI, not the Firebase-provided `firebaseapp.com` endpoint.","severity":"gotcha","affected_versions":">=0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Implement a mapping logic in your application to translate Firebase error codes (e.g., 'auth/invalid-email') into user-friendly messages. Refer to the Firebase Auth error code documentation or the library's wiki for a comprehensive list.","cause":"The library now returns raw Firebase error codes instead of human-readable messages after v0.8.1.","error":"Authentication error: auth/invalid-email"},{"fix":"Ensure you are importing `Auth` as the default export using `import Auth from 'firebase-auth-lite';` and instantiating it with `new Auth(...)`.","cause":"Attempting to use `Auth` as a function or incorrectly importing it as a named export.","error":"TypeError: Auth is not a constructor"},{"fix":"This library is browser-focused. Ensure it runs in a modern browser environment or use appropriate polyfills for `fetch` and `localStorage` if targeting older environments.","cause":"Running the library in an environment (e.g., older Node.js versions, certain test environments) that does not provide the Fetch API or localStorage.","error":"ReferenceError: fetch is not defined"},{"fix":"In the respective OAuth provider's developer console, update the Authorized Redirect URIs to specify the exact URL of the page within *your application* that handles the sign-in redirect, not the `https://[app-id].firebaseapp.com/__/auth/handler` URL.","cause":"Incorrectly configured redirect URL for Federated Identity Providers (e.g., Google, Facebook OAuth), using the default Firebase handler URL instead of your application's URL.","error":"Federated sign-in redirect loops or 'auth/redirect-url-mismatch'"}],"ecosystem":"npm"}