Skip to main content

Firebase Integration for Next.js Admin Panels

The admin panel should connect to the same Firebase project as the matching React Native app. This keeps app users, Firestore data, uploaded media, push tokens, and operational workflows in one backend.

Quick Setup​

You need two groups of Firebase configuration:

ConfigurationUsed byVisibility
Firebase web configLogin page and Firebase browser SDKPublic NEXT_PUBLIC_* values
Firebase Admin SDK credentialsNext.js API routes and server actionsServer-only environment variables

The web config identifies your Firebase project. The Admin SDK credentials authorize privileged server-side actions. Treat Admin SDK credentials as production secrets.

1. Enable Required Firebase Services​

In Firebase Console, enable the services your app uses:

  • Authentication for admin login and app user accounts;
  • Cloud Firestore for app and admin data;
  • Cloud Storage for Media Library and mobile uploads;
  • Cloud Messaging if the admin panel includes push campaigns;
  • Cloud Functions if the app uses Firebase backend functions;
  • App Check for production protection when supported by your app.

Related setup pages:

2. Add Firebase Web Config​

In Firebase Console:

  1. open your project;
  2. create or select a Web App;
  3. copy the web config;
  4. add the values to .env.local.
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=

These values must belong to the same Firebase project used by the React Native app. If the mobile app points to a different project, the admin panel will show different users and records.

3. Configure Firebase Admin SDK​

The admin panel uses Firebase Admin SDK from server routes for protected operations such as:

  • verifying admin sessions;
  • reading and writing Firestore securely;
  • uploading media through protected endpoints;
  • changing workflow status values;
  • writing Audit Log records;
  • managing admin roles when owner access is available.

For local development, use a service account path:

FIREBASE_SERVICE_ACCOUNT_PATH=/path/to/firebase-service-account.json
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com

For hosted environments, use server-side secrets:

FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-...@your-project-id.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com

Do not commit service account JSON files, .env.local, or private keys.

4. Configure Admin Access​

The admin panel checks the Firebase user after sign-in. A user can be allowed through either:

  • Firebase Auth custom claims, such as role: "owner";
  • a Firestore users/{uid} document with a supported admin role.

The first owner is usually created manually. After that, use the Admin Roles page to add operators, support agents, moderators, and content managers.

Recommended first owner flow:

  1. Create the user in Firebase Authentication.
  2. Assign role: "owner".
  3. Sign in to the admin panel.
  4. Open Admin Roles.
  5. Add other admins with the smallest role that fits their responsibilities.

5. Configure Storage Uploads​

Set the bucket in public and server-side values:

NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com
FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com
UPLOAD_MAX_FILE_SIZE_MB=10

Then open Media Library and upload a small image. A successful upload should return a Firebase Storage URL that can be used in products, listings, profiles, posts, stories, campaigns, or other app content.

6. Configure Email And Push Providers​

If your admin panel includes campaign features, configure only the providers you use.

Common email values:

SENDGRID_API_KEY=
EMAIL_FROM_ADDRESS=
EMAIL_BROADCAST_LIMIT=500

Common push values:

PUSH_BROADCAST_LIMIT=500

Push notifications also require the mobile app to have FCM and platform notification setup:

7. Confirm Firestore Data Alignment​

Use the admin panel and the mobile app together:

CheckExpected result
Sign in to the admin panelOwner can access Dashboard.
Open UsersFirebase Auth and Firestore users match the selected project.
Upload mediaFile appears in the configured Storage bucket.
Create or update a safe recordFirestore document changes and Audit Log records the action.
Open the mobile appThe app reads the same records from the same Firebase project.

Troubleshooting​

ProblemWhat to check
Login failsNEXT_PUBLIC_FIREBASE_API_KEY, Auth provider setup, email/password state.
Login succeeds but dashboard access failsCustom claims or users/{uid}.role.
API routes return Firebase Admin errorsService account, project ID, private key formatting, server-only env vars.
Upload failsStorage enabled, bucket name, Admin SDK permissions, file size limit.
Data appears emptyAdmin panel and mobile app point to different Firebase projects or collections.
Push or email failsProvider keys, sender config, broadcast limits, mobile push setup.

Production Notes​

Before deployment:

  • use a production Firebase project;
  • store Firebase Admin credentials only in the hosting provider secret manager;
  • remove development smoke-test bypass settings;
  • review Firestore and Storage rules for the mobile app;
  • keep at least two owner accounts for recovery;
  • review Audit Log after setup.

Next Steps​