firebase-auth-for-chrome-extensions
v1.0.0
Published
Seamlessly implement Firebase Auth inside Manifest V3 Chrome Extensions using Offscreen Documents.
Downloads
11
Readme
firebase-auth-for-chrome-extensions
The ultimate solution for Firebase Authentication in Manifest V3 Chrome Extensions.
Manifest V3 removed Background Pages (which had access to the DOM) and replaced them with Service Workers. Because the Firebase Web SDK relies on the DOM to execute Google Sign-In and handle OAuth redirects, standard signInWithPopup methods will instantly crash in modern Chrome Extensions.
This package provides a plug-and-play architectural bridge. It uses Chrome's native chrome.identity API to handle the popup UI, and seamlessly proxies the credential to a hidden MV3 Offscreen Document so Firebase can securely authenticate the session without ever needing a visible DOM.
🚀 Installation
npm install firebase-auth-for-chrome-extensions(Requires firebase as a peer dependency)
🛠️ Usage
This package provides three distinct entry points for the three environments of your extension.
1. The Background Script (Service Worker)
In your background.js (or background.ts), initialize the auth proxy. This script will listen for login requests from your popup and spawn the Offscreen Document to process them.
import { setupAuthListener } from "firebase-auth-for-chrome-extensions/background";
// Provide the path to the offscreen HTML file you will create in Step 2.
// This path is relative to the root of your compiled extension (dist/build folder)
setupAuthListener({
offscreenPath: "offscreen.html",
});2. The Offscreen Document
You must create a minimal HTML file (e.g., offscreen.html) in your public/static folder, and a corresponding script (e.g., offscreen.js).
offscreen.html (Must be declared in your manifest.json)
<!DOCTYPE html>
<html>
<body>
<!-- Must be a module to support Firebase imports -->
<script type="module" src="offscreen.js"></script>
</body>
</html>offscreen.js
Initialize your Firebase App securely here, where a DOM exists!
import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";
import { initializeOffscreenAuth } from "firebase-auth-for-chrome-extensions/offscreen";
const app = initializeApp({
apiKey: "YOUR_API_KEY",
authDomain: "YOUR_PROJECT.firebaseapp.com",
// ... rest of config
});
const auth = getAuth(app);
// This function catches the token from the background script and logs the user in
initializeOffscreenAuth(auth);3. The React Popup / Frontend
Wrap your extension's React application in the provided AuthProvider.
App.jsx
import React from "react";
import {
AuthProvider,
useExtensionAuth,
} from "firebase-auth-for-chrome-extensions/react";
import { auth } from "./lib/firebase"; // Your standard Firebase init file
export default function App() {
return (
<AuthProvider auth={auth}>
<Main />
</AuthProvider>
);
}
function Main() {
const { user, loading, loginWithGoogle, logout } = useExtensionAuth();
if (loading) return <div>Loading session...</div>;
if (!user) {
return (
<button onClick={() => loginWithGoogle().catch(console.error)}>
Log in with Google
</button>
);
}
return (
<div>
<h1>Welcome, {user.email}</h1>
<button onClick={logout}>Sign Out</button>
</div>
);
}⚙️ Manifest V3 Requirements
For this to work natively, your manifest.json must include the following permissions and an OAuth2 Client ID generated from the Google Cloud Console (Chrome Application type).
{
"manifest_version": 3,
"name": "My Firebase Extension",
"version": "1.0.0",
"permissions": ["identity", "offscreen", "storage"],
"oauth2": {
"client_id": "YOUR_CHROME_APP_OAUTH_CLIENT_ID.apps.googleusercontent.com",
"scopes": ["email", "profile"]
},
"background": {
"service_worker": "background.js",
"type": "module"
}
}🔥 Important Firebase Step:
You must take the exact client_id string from your manifest.json and paste it into the "Whitelist client IDs from external projects" section of your Firebase Console under Authentication -> Sign-In Method -> Google. If you skip this, Firebase will throw an auth/invalid-credential error.