How to Integrate Lovable with Google Cloud Firestore

In the Google Cloud Console at console.cloud.google.com, select your project from the top dropdown and navigate to IAM & Admin → Service Accounts. Click 'Create Service Account'. Give it a meaningful name like 'lovable-firestore-access' and a description like 'Service account for Lovable Edge Function Firestore access'. Click 'Create and continue'. On the 'Grant this service account access to the project' step, add a role. For read-write access to Firestore, use 'Cloud Datastore User'. For read-only, use 'Cloud Datastore Viewer'. For full admin access (including schema changes), use 'Cloud Datastore Owner' — but this is overly broad for most Lovable apps. Click 'Continue' and then 'Done'. After creation, click on the service account in the list and navigate to the 'Keys' tab. Click 'Add key' → 'Create new key' → select 'JSON' → 'Create'. Google downloads a JSON file containing: type, project_id, private_key_id, private_key (RSA private key), client_email, client_id, and several auth URIs. This file is your service account credential — protect it like a password. You will paste its contents into Lovable Cloud Secrets in the next step.

In Lovable, click the '+' button next to the Preview panel to open the Cloud tab, then navigate to Secrets. Add these secrets: - GCP_SERVICE_ACCOUNT_JSON: paste the entire contents of the JSON key file as a single value - GCP_PROJECT_ID: your Google Cloud project ID (e.g., my-project-12345) The service account JSON is a multi-line string that may cause issues when pasted into some secret managers. If the Lovable Secrets panel truncates or mangles the value, minify the JSON first by removing all whitespace (use an online JSON minifier or paste into the browser console and run JSON.stringify(JSON.parse(yourJson))). The Edge Function will parse this JSON to extract the client_email and private_key fields needed for JWT signing. The private key contains literal newline characters — when stored in an environment variable, these are often encoded as the two-character sequence backslash-n rather than actual newlines. The Edge Function must handle this encoding by replacing \\n with actual newline characters before using the key for JWT signing.

The core challenge of the standalone Firestore integration is authentication. Firestore's REST API requires a Google OAuth2 access token, obtained by signing a JWT with the service account private key and exchanging it at Google's token endpoint. The JWT for Google's service accounts has specific required claims: iss (the service account client_email), scope (space-separated Google API scopes — for Firestore use 'https://www.googleapis.com/auth/datastore'), aud (always 'https://oauth2.googleapis.com/token'), iat (current timestamp), and exp (expiry, maximum 1 hour from iat). Deno's built-in Web Crypto API can sign this JWT using the RS256 algorithm and the service account's RSA private key. After signing, the JWT is exchanged at the Google token endpoint for a short-lived access token. This access token is then used as a Bearer token in all Firestore REST API calls. The Firestore REST API URL structure is: https://firestore.googleapis.com/v1/projects/{projectId}/databases/(default)/documents/{collection}/{documentId}. For listing a collection, omit the document ID. For structured queries (Firestore's equivalent of SQL WHERE), use the :runQuery endpoint with a StructuredQuery payload.

1// Key portion of the Google OAuth2 JWT flow for Deno:
2// supabase/functions/firestore-proxy/index.ts (auth section)
3
4const serviceAccount = JSON.parse(Deno.env.get("GCP_SERVICE_ACCOUNT_JSON") || "{}");
5const privateKeyPem = serviceAccount.private_key.replace(/\\n/g, "\n");
6
7// Import RSA private key for signing
8const keyData = privateKeyPem
9  .replace(/-----BEGIN PRIVATE KEY-----/, "")
10  .replace(/-----END PRIVATE KEY-----/, "")
11  .replace(/\n/g, "");
12const binaryKey = Uint8Array.from(atob(keyData), c => c.charCodeAt(0));
13const cryptoKey = await crypto.subtle.importKey(
14  "pkcs8",
15  binaryKey,
16  { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
17  false,
18  ["sign"]
19);
20
21// Build JWT claims
22const now = Math.floor(Date.now() / 1000);
23const claims = {
24  iss: serviceAccount.client_email,
25  scope: "https://www.googleapis.com/auth/datastore",
26  aud: "https://oauth2.googleapis.com/token",
27  iat: now,
28  exp: now + 3600,
29};
30
31// Sign JWT (header.payload.signature)
32const header = btoa(JSON.stringify({ alg: "RS256", typ: "JWT" })).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
33const payload = btoa(JSON.stringify(claims)).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
34const signingInput = `${header}.${payload}`;
35const signatureBytes = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", cryptoKey, new TextEncoder().encode(signingInput));
36const signature = btoa(String.fromCharCode(...new Uint8Array(signatureBytes))).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
37const jwt = `${signingInput}.${signature}`;
38
39// Exchange JWT for access token
40const tokenResponse = await fetch("https://oauth2.googleapis.com/token", {
41  method: "POST",
42  headers: { "Content-Type": "application/x-www-form-urlencoded" },
43  body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: jwt }),
44});
45const { access_token } = await tokenResponse.json();

With the Edge Function deployed and authentication working, open the Lovable chat and describe the frontend components you want. Provide your Firestore collection names and document field names — Lovable generates React components that call the firestore-proxy Edge Function. Firestore REST API responses have a specific structure that differs from a flat JSON object. A document response looks like: { name: 'projects/my-project/databases/(default)/documents/articles/docId', fields: { title: { stringValue: 'Hello' }, count: { integerValue: '42' }, active: { booleanValue: true } }, createTime: '...', updateTime: '...' }. The field values are wrapped in type-specific objects. When prompting Lovable, describe your Firestore fields and their types so Lovable can generate code that unwraps these type-value objects. Lovable can create a utility function that converts Firestore's field format ({ stringValue: 'text' }, { integerValue: '42' }) into plain JavaScript values ('text', 42) before rendering. For listing collections, the REST API returns a documents array with the same per-field type-value structure. Pagination uses a pageToken from the previous response as a parameter for the next request.

The Firestore REST API supports structured queries through its :runQuery endpoint — the equivalent of Firestore's JavaScript SDK query() method. Structured queries let you filter documents by field value, order results, and limit the response count, all server-side without fetching an entire collection. The structured query format is different from a simple URL parameter — it's a JSON POST body sent to: POST https://firestore.googleapis.com/v1/projects/{projectId}/databases/(default)/documents:runQuery. The body describes the collection, filter conditions, ordering, and limits using Firestore's StructuredQuery schema. Ask Lovable to extend the firestore-proxy Edge Function with a 'query' operation that accepts filter parameters and constructs the StructuredQuery payload. Common filter operators include EQUAL, GREATER_THAN, LESS_THAN, ARRAY_CONTAINS, and IN. Compound filters use composite filters with AND or OR operators. For complex query requirements, RapidDev's team can help design Firestore indexes and structured query patterns for your specific collection structure.