Configure Firebase Firestore for Your Lynkz Instance

Lynkz uses Firebase Firestore — not Firebase Auth — as its sole database. Firestore stores your page data (links, themes, bio), server-side analytics, and access control records such as IP lockouts and magic tokens. You do not need to enable any other Firebase services.

Create a Firebase Project

Go to console.firebase.google.com and sign in with your Google account. Click Add project, give your project a name, and follow the prompts to finish creation. You can disable Google Analytics for the Firebase project — Lynkz tracks its own analytics independently.

Enable Firestore

Inside your new project, navigate to Build → Firestore Database in the left sidebar. Click Create database, select your preferred region (choose one close to your users), and when prompted for a security mode select Start in production mode. The default locked-down rules are fine for now — you’ll replace them in the next step.

Set Firestore Rules

In the Firestore console, open the Rules tab and replace the existing content with the rules below, then click Publish.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /pages/{username} {
      allow read: if true;
      allow write: if !('pinHash' in request.resource.data)
                   && !('email' in request.resource.data);
    }
    match /analytics/{username} {
      allow read: if false;
      allow write: if true;
    }
    match /analytics/{username}/daily/{day} {
      allow read: if false;
      allow write: if true;
    }
    match /lockouts/{id} { allow read, write: if false; }
    match /magic_tokens/{token} { allow read, write: if false; }
  }
}

These rules allow public reads of page data while blocking clients from writing sensitive fields such as pinHash and email. Analytics can be written from the browser but never read. Lockout and magic token records are fully server-side only.

You can also push your rules from the command line instead of copy-pasting in the console. Install the Firebase CLI (npm install -g firebase-tools), then run firebase deploy --only firestore:rules from your project root.

Get Your Web App Config

Navigate to Project Settings (gear icon) → Your apps. If you haven’t added a web app yet, click Add app and choose the Web platform (</>). After registering the app, Firebase displays a config object like this:

const firebaseConfig = {
  apiKey: "AIza...",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "123456789",
  appId: "1:123456789:web:abc123"
};

Copy each value into your .env.local file under the corresponding NEXT_PUBLIC_FIREBASE_* variable. See the Environment Variables reference for the full list.

Get Your Service Account Key

Still in Project Settings, open the Service accounts tab. Click Generate new private key and confirm the download. Firebase gives you a .json file containing your full service account credentials.Open the file, copy its entire contents, and set it as the value of FIREBASE_SERVICE_ACCOUNT_KEY in your Vercel environment variables. The value should be the raw JSON string — the entire object, including braces.

Your service account key grants full admin access to your Firestore database. Treat it like a password — never commit it to version control or paste it anywhere publicly visible. Store it exclusively as a Vercel environment variable (or equivalent secret store if you self-host). It should never reach the browser.

Get Started

Setup

Features

Security

Help

Configure Firebase Firestore for Your Lynkz Instance