How to Integrate Bolt.new with Google Cloud Firestore

Navigate to console.firebase.google.com and click 'Add project'. Give your project a name — this creates a Google Cloud project in the background. You can optionally enable Google Analytics; it does not affect Firestore functionality. Once the project is created, click the web icon (</>) on the Project Overview to register a web app. Give the app a nickname, skip Firebase Hosting for now, and click 'Register app'. Firebase displays your configuration object — a plain JavaScript object with six fields: apiKey, authDomain, projectId, storageBucket, messagingSenderId, and appId. Copy this entire object and keep it handy. Next, enable Firestore. In the left sidebar, click 'Firestore Database' → 'Create database'. Choose a region close to your users (this cannot be changed later). For the security rules mode, select 'Start in test mode' — this allows all reads and writes for 30 days, which is sufficient for development. Click 'Enable'. Firestore will provision in about 30 seconds. If you prefer to access your project through the Google Cloud Console (console.cloud.google.com), the same Firestore database is visible under Firestore in the left menu. GCP also gives you access to Cloud Audit Logs, IAM roles for service accounts, and Firestore's export/import pipeline to Google Cloud Storage — useful for backups and data migrations. For Bolt development, the Firebase Console is simpler; switch to the GCP Console only when you need enterprise features. One key note: Firebase config values (apiKey, projectId, etc.) are designed to be public. They identify your project and are safe to commit to source code or include in client-side bundles. Security is enforced by Firestore Security Rules, not by keeping the config private. This is different from API keys for paid services — your Firebase apiKey being visible in browser DevTools is expected and not a vulnerability.

1// src/lib/firebase.ts
2import { initializeApp, getApps, getApp } from 'firebase/app';
3import { getFirestore } from 'firebase/firestore';
4
5const firebaseConfig = {
6  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
7  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
8  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
9  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
10  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
11  appId: import.meta.env.VITE_FIREBASE_APP_ID,
12};
13
14// Prevent re-initialization on Vite hot module replacement
15const app = getApps().length === 0 ? initializeApp(firebaseConfig) : getApp();
16
17export const db = getFirestore(app);
18export default app;

Firestore organizes data in a hierarchy: your database contains collections, each collection contains documents, and each document can contain subcollections. Think of it as: Database → Folders (collections) → Files (documents) → Nested folders (subcollections). A document is a map of key-value fields — strings, numbers, booleans, timestamps, arrays, nested maps, and references. There are no JOINs and no foreign keys; related data is either embedded in a document, stored in a subcollection, or linked by storing a document ID as a field. Subcollections are the key Firestore data modeling tool. A 'posts' collection can have a 'comments' subcollection under each post document. Reading a post does not automatically read its comments — you query the subcollection separately. This is fundamentally different from embedding comments as an array inside the post document: embedded arrays load entirely on each read and cannot be queried independently, but they cost fewer reads. Use subcollections when you expect many child records or need to query them independently. Use embedded arrays for small, fixed lists that you always need alongside the parent. Compound queries — filtering on multiple fields, or combining a filter with ordering — require composite indexes in Firestore. You cannot, for example, query where status == 'active' AND orderBy createdAt without a composite index on those two fields. Firestore will return a console error with a direct link to create the index in the Firebase Console with one click. Index creation takes 1-3 minutes. Plan your query patterns early and create indexes proactively. You can view and manage all indexes under Firestore Database → Indexes in the Firebase Console. Document ID strategy matters for performance. Auto-generated IDs (addDoc) are random strings that distribute writes evenly across Firestore's storage shards — use these by default. Sequential IDs (like timestamps or incrementing integers) can cause hotspot issues at scale because they route writes to the same shard. For lookups by a specific value (e.g., finding a user by their email), store that value as a field and query with where() rather than encoding it in the document ID.

1// src/types/firestore.ts
2import { Timestamp } from 'firebase/firestore';
3
4export interface Project {
5  id: string;
6  name: string;
7  description: string;
8  ownerId: string;
9  memberIds: string[];
10  status: 'active' | 'archived';
11  createdAt: Timestamp;
12  updatedAt: Timestamp;
13}
14
15export interface Task {
16  id: string;
17  title: string;
18  description: string;
19  assigneeId: string | null;
20  status: 'todo' | 'in-progress' | 'review' | 'done';
21  priority: 'low' | 'medium' | 'high';
22  dueDate: Timestamp | null;
23  createdAt: Timestamp;
24  updatedAt: Timestamp;
25}
26
27export interface Comment {
28  id: string;
29  body: string;
30  authorId: string;
31  authorName: string;
32  createdAt: Timestamp;
33}
34
35// Firestore path helpers
36export const PATHS = {
37  projects: () => 'projects',
38  project: (projectId: string) => `projects/${projectId}`,
39  tasks: (projectId: string) => `projects/${projectId}/tasks`,
40  task: (projectId: string, taskId: string) => `projects/${projectId}/tasks/${taskId}`,
41  comments: (projectId: string, taskId: string) =>
42    `projects/${projectId}/tasks/${taskId}/comments`,
43};

Firestore's onSnapshot is the standout feature for Bolt development. Unlike getDoc or getDocs (one-time fetches), onSnapshot registers a persistent listener that fires immediately with the current data, then fires again every time the data changes — in any browser tab connected to the same Firestore database. This works inside Bolt's WebContainer preview environment because Firestore's SDK uses WebSocket under the hood, which WebContainers support natively. You can open two browser windows in Bolt's preview side by side and watch data synchronize in real time. Every onSnapshot call returns an unsubscribe function. You must call this function when the component unmounts — typically in a React useEffect cleanup return. Failing to unsubscribe causes memory leaks and, more critically, Firestore connection errors after hot module replacements where the same snapshot is registered twice. The getApps() guard in your firebase.ts initialization handles the app-level duplicate, but you must handle the listener-level duplicate through proper cleanup. For write operations, Firestore provides addDoc (creates a document with an auto-generated ID), setDoc (creates or overwrites a document with a specific ID), updateDoc (merges fields into an existing document without overwriting the whole document), and deleteDoc. Use serverTimestamp() for createdAt and updatedAt fields — it uses Firebase's server clock rather than the client clock, preventing issues with user devices that have incorrect system times. Batch writes (writeBatch) let you execute multiple operations atomically — all succeed or all fail — useful for maintaining consistency across multiple documents, like updating a task status while also updating the project's lastActivityAt field. For queries, the query() function takes a collection reference and one or more constraint functions: where(), orderBy(), limit(), startAfter(), and endBefore(). Combining where() on one field with orderBy() on a different field requires a composite index. The Firebase Console will display a clickable link in the error message that creates the index automatically — this is the standard Firestore development workflow. For production, create indexes proactively based on your known query patterns.

1// src/hooks/useProjectTasks.ts
2import { useState, useEffect } from 'react';
3import {
4  collection,
5  query,
6  orderBy,
7  onSnapshot,
8  addDoc,
9  updateDoc,
10  deleteDoc,
11  doc,
12  serverTimestamp,
13} from 'firebase/firestore';
14import { db } from '@/lib/firebase';
15import type { Task } from '@/types/firestore';
16
17export function useProjectTasks(projectId: string) {
18  const [tasks, setTasks] = useState<Task[]>([]);
19  const [loading, setLoading] = useState(true);
20  const [error, setError] = useState<Error | null>(null);
21
22  useEffect(() => {
23    if (!projectId) return;
24
25    const tasksRef = collection(db, 'projects', projectId, 'tasks');
26    const q = query(tasksRef, orderBy('createdAt', 'desc'));
27
28    const unsubscribe = onSnapshot(
29      q,
30      (snapshot) => {
31        const taskList = snapshot.docs.map((d) => ({
32          id: d.id,
33          ...d.data(),
34        })) as Task[];
35        setTasks(taskList);
36        setLoading(false);
37      },
38      (err) => {
39        setError(err);
40        setLoading(false);
41      }
42    );
43
44    // Must unsubscribe to prevent memory leaks and duplicate listeners on HMR
45    return () => unsubscribe();
46  }, [projectId]);
47
48  return { tasks, loading, error };
49}
50
51export async function createTask(
52  projectId: string,
53  task: Omit<Task, 'id' | 'createdAt' | 'updatedAt'>
54) {
55  const tasksRef = collection(db, 'projects', projectId, 'tasks');
56  return addDoc(tasksRef, {
57    ...task,
58    createdAt: serverTimestamp(),
59    updatedAt: serverTimestamp(),
60  });
61}
62
63export async function updateTask(
64  projectId: string,
65  taskId: string,
66  changes: Partial<Omit<Task, 'id' | 'createdAt'>>
67) {
68  const taskRef = doc(db, 'projects', projectId, 'tasks', taskId);
69  return updateDoc(taskRef, { ...changes, updatedAt: serverTimestamp() });
70}
71
72export async function deleteTask(projectId: string, taskId: string) {
73  const taskRef = doc(db, 'projects', projectId, 'tasks', taskId);
74  return deleteDoc(taskRef);
75}

Firestore Security Rules are the access control layer for your database. They run server-side on Firebase's infrastructure and cannot be bypassed by client-side code, even if someone modifies your JavaScript bundle. Rules evaluate each read, write, create, update, and delete operation and return allow or deny. When you created your Firestore database in test mode, Firebase set a permissive rule that allows all access for 30 days — you must replace this before production. Rules use a declarative syntax with match statements that target document paths. The request object contains the incoming operation details: request.auth (the authenticated user's UID and token claims), request.resource.data (the data being written), and request.method (read/write). The resource object represents the current document being read or written. You can write helper functions within the rules file to avoid repeating logic — for example, an isOwner() function that checks if request.auth.uid matches a document's ownerId field. For the project management data model from Step 2, a practical rule set allows any authenticated user to read projects where their UID is in the memberIds array, but only the project owner to update or delete the project. Tasks within a project inherit this access pattern — any project member can create and update tasks, but only the task's assignee or the project owner can delete them. Comments can be edited only by their author. Rules do not cascade: a rule that allows reading a project document does not automatically allow reading its tasks subcollection. You must write explicit match statements for each path level. The Firebase Console's Rules Playground lets you simulate operations and verify that your rules behave correctly before publishing. Test with both authenticated and unauthenticated requests, and test edge cases like a user trying to access another user's data. Publish rules from Firebase Console → Firestore Database → Rules → Publish. Changes take effect globally within about 60 seconds.

1// firestore.rules
2rules_version = '2';
3service cloud.firestore {
4  match /databases/{database}/documents {
5
6    // Helper functions
7    function isAuthenticated() {
8      return request.auth != null;
9    }
10
11    function isProjectMember(projectId) {
12      return isAuthenticated() &&
13        request.auth.uid in get(/databases/$(database)/documents/projects/$(projectId)).data.memberIds;
14    }
15
16    function isProjectOwner(projectId) {
17      return isAuthenticated() &&
18        request.auth.uid == get(/databases/$(database)/documents/projects/$(projectId)).data.ownerId;
19    }
20
21    // Projects collection
22    match /projects/{projectId} {
23      allow read: if isProjectMember(projectId) || isProjectOwner(projectId);
24      allow create: if isAuthenticated();
25      allow update: if isProjectOwner(projectId);
26      allow delete: if isProjectOwner(projectId);
27
28      // Tasks subcollection
29      match /tasks/{taskId} {
30        allow read: if isProjectMember(projectId) || isProjectOwner(projectId);
31        allow create: if isProjectMember(projectId) || isProjectOwner(projectId);
32        allow update: if isProjectMember(projectId) || isProjectOwner(projectId);
33        allow delete: if isProjectOwner(projectId) ||
34          (isAuthenticated() && request.auth.uid == resource.data.createdBy);
35
36        // Comments subcollection
37        match /comments/{commentId} {
38          allow read: if isProjectMember(projectId) || isProjectOwner(projectId);
39          allow create: if isProjectMember(projectId) || isProjectOwner(projectId);
40          allow update, delete: if isAuthenticated() &&
41            request.auth.uid == resource.data.authorId;
42        }
43      }
44    }
45  }
46}

During development in Bolt's WebContainer, your Firestore reads, writes, and real-time listeners work in the preview. However, two important limitations apply before you deploy. First, incoming webhooks from external services cannot reach the WebContainer — there is no publicly accessible URL for the preview environment. If you plan to trigger Firestore writes from an external service (for example, a payment webhook that records a transaction), you must deploy first and then register the deployed URL as the webhook endpoint. Second, if your app uses Firebase Authentication with OAuth providers like Google, the OAuth redirect URI must point to your deployed domain — the preview URL is dynamic and cannot be pre-registered. To deploy, click the Publish button in Bolt's top-right corner. If you have Netlify connected via Settings → Applications, Bolt deploys automatically to a *.netlify.app URL in about 30 seconds. After deploying, go to Netlify Dashboard → Site Configuration → Environment Variables and add all six Firebase config values: VITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID, VITE_FIREBASE_STORAGE_BUCKET, VITE_FIREBASE_MESSAGING_SENDER_ID, and VITE_FIREBASE_APP_ID. Trigger a redeploy after adding environment variables — Netlify injects them at build time, so the currently deployed build does not have them yet. For Firebase Authentication with Google or GitHub login, add your deployed Netlify domain to the Firebase Console. Go to Firebase Console → Authentication → Settings → Authorized domains and add your *.netlify.app URL (and your custom domain if you have one). Without this step, OAuth login returns an auth/unauthorized-domain error on the live site. Test the full authentication flow on the deployed URL after adding the authorized domain. If your app scales beyond Netlify's free tier, exporting the Bolt project to GitHub and connecting it to Vercel works identically — Firestore and Firebase Auth are cloud services that don't care which hosting provider serves your frontend.

1// src/lib/firebase.ts
2/**
3 * DEPLOYMENT CHECKLIST
4 * Before going live, complete these steps:
5 *
6 * 1. NETLIFY ENVIRONMENT VARIABLES (Site Configuration → Environment Variables)
7 *    - VITE_FIREBASE_API_KEY
8 *    - VITE_FIREBASE_AUTH_DOMAIN
9 *    - VITE_FIREBASE_PROJECT_ID
10 *    - VITE_FIREBASE_STORAGE_BUCKET
11 *    - VITE_FIREBASE_MESSAGING_SENDER_ID
12 *    - VITE_FIREBASE_APP_ID
13 *    Then: Trigger a redeploy to inject env vars into the build.
14 *
15 * 2. FIREBASE AUTHORIZED DOMAINS (Firebase Console → Authentication → Settings → Authorized domains)
16 *    Add your deployed URL, e.g.:
17 *    - your-app.netlify.app
18 *    - your-custom-domain.com
19 *    Required for Google/GitHub OAuth login to work on production.
20 *
21 * 3. FIRESTORE SECURITY RULES (Firebase Console → Firestore Database → Rules)
22 *    Replace test mode rules with production rules that restrict access
23 *    to authenticated users only. Test mode expires after 30 days.
24 */
25
26import { initializeApp, getApps, getApp } from 'firebase/app';
27import { getFirestore } from 'firebase/firestore';
28import { getAuth } from 'firebase/auth';
29
30const firebaseConfig = {
31  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
32  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
33  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
34  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
35  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
36  appId: import.meta.env.VITE_FIREBASE_APP_ID,
37};
38
39const app = getApps().length === 0 ? initializeApp(firebaseConfig) : getApp();
40
41export const db = getFirestore(app);
42export const auth = getAuth(app);
43export default app;