How to Integrate Bolt.new with MongoDB Atlas

The Atlas Data API is not enabled by default. You need to activate it for your cluster before you can make HTTP requests. Log into MongoDB Atlas at cloud.mongodb.com. In the left sidebar, click 'Data API' under the Services section. On the Data API page, click 'Enable the Data API.' Choose which data sources (clusters) to enable it for and select your cluster. Once enabled, you'll see your App Services URL — this is the base URL for all Data API requests, in the format https://data.mongodb-api.com/app/{App-ID}/endpoint/data/v1. Next, create an API key by clicking 'Create API Key.' Give it a name (like 'bolt-dev') and copy the key immediately — it's shown only once. Store both your App ID and API Key somewhere safe. Note the exact database and collection names you plan to query, as the Data API requires them in every request.

Store your Atlas Data API credentials in your Bolt project's .env file. These are server-side credentials that must never be exposed to the browser. In your Next.js project, environment variables without a NEXT_PUBLIC_ prefix are only accessible in API routes and server components — they never get bundled into client JavaScript. You'll need three variables: the Data API URL (which includes your App ID), your API key, and the database name. The collection name can be hardcoded in your API routes or stored as an additional environment variable if you have multiple collections. After adding these to .env, prompt Bolt to create a MongoDB utility module that initializes a reusable API client — this prevents you from repeating the Atlas URL and API key in every API route.

1# .env
2MONGODB_DATA_API_URL=https://data.mongodb-api.com/app/data-abcde/endpoint/data/v1
3MONGODB_API_KEY=your-atlas-api-key-here
4MONGODB_DATABASE_NAME=your-database-name

The Atlas Data API communicates via JSON over HTTPS. Each operation (find, insert, update, delete) corresponds to a specific HTTP endpoint. Every request includes your API key in the apiKey header, and the request body specifies the data source, database, and collection. The response is JSON containing a document or documents array. Building a typed TypeScript client that wraps these HTTP calls makes your API routes much cleaner and reusable across your application. The client you build here works identically in the Bolt WebContainer preview and in production — it's just fetch calls, nothing environment-specific.

1// lib/mongodb.ts
2const DATA_API_URL = process.env.MONGODB_DATA_API_URL!;
3const API_KEY = process.env.MONGODB_API_KEY!;
4const DATABASE = process.env.MONGODB_DATABASE_NAME!;
5
6const headers = {
7  'Content-Type': 'application/json',
8  'apiKey': API_KEY,
9};
10
11async function dataApiRequest<T>(
12  action: string,
13  collection: string,
14  body: Record<string, unknown>
15): Promise<T> {
16  const response = await fetch(`${DATA_API_URL}/action/${action}`, {
17    method: 'POST',
18    headers,
19    body: JSON.stringify({
20      dataSource: 'Cluster0', // your cluster name
21      database: DATABASE,
22      collection,
23      ...body,
24    }),
25  });
26  if (!response.ok) {
27    const error = await response.text();
28    throw new Error(`MongoDB Data API error: ${error}`);
29  }
30  return response.json();
31}
32
33export const mongodb = {
34  async findMany<T>(collection: string, filter = {}, options: { sort?: Record<string, 1 | -1>; limit?: number } = {}): Promise<T[]> {
35    const result = await dataApiRequest<{ documents: T[] }>('find', collection, {
36      filter,
37      sort: options.sort,
38      limit: options.limit,
39    });
40    return result.documents;
41  },
42
43  async findOne<T>(collection: string, filter: Record<string, unknown>): Promise<T | null> {
44    const result = await dataApiRequest<{ document: T | null }>('findOne', collection, { filter });
45    return result.document;
46  },
47
48  async insertOne<T>(collection: string, document: Record<string, unknown>): Promise<{ insertedId: string }> {
49    return dataApiRequest('insertOne', collection, { document });
50  },
51
52  async updateOne(
53    collection: string,
54    filter: Record<string, unknown>,
55    update: Record<string, unknown>
56  ): Promise<{ matchedCount: number; modifiedCount: number }> {
57    return dataApiRequest('updateOne', collection, { filter, update });
58  },
59
60  async deleteOne(collection: string, filter: Record<string, unknown>): Promise<{ deletedCount: number }> {
61    return dataApiRequest('deleteOne', collection, { filter });
62  },
63};

Now build the API routes that your React frontend will call. Each route uses the mongodb utility from lib/mongodb.ts to perform database operations. Because the utility handles the Atlas Data API HTTP calls internally, your route code looks clean and focused on business logic. The routes run server-side within Bolt's WebContainer Node.js process, so they can access environment variables and make outbound HTTP calls to Atlas without any CORS restrictions. Your React components on the client side call these API routes using normal fetch requests to relative URLs like /api/products. This two-layer architecture (client → your API route → Atlas Data API) properly keeps credentials server-side and gives you a place to add authentication, validation, and business logic.

1// app/api/items/route.ts
2import { NextResponse } from 'next/server';
3import { mongodb } from '@/lib/mongodb';
4
5export async function GET(request: Request) {
6  try {
7    const { searchParams } = new URL(request.url);
8    const category = searchParams.get('category');
9    const filter = category ? { category } : {};
10
11    const items = await mongodb.findMany('items', filter, {
12      sort: { createdAt: -1 },
13      limit: 100,
14    });
15    return NextResponse.json({ items });
16  } catch (error) {
17    return NextResponse.json({ error: 'Failed to fetch items' }, { status: 500 });
18  }
19}
20
21export async function POST(request: Request) {
22  try {
23    const body = await request.json();
24    const result = await mongodb.insertOne('items', {
25      ...body,
26      createdAt: new Date().toISOString(),
27    });
28    return NextResponse.json(result, { status: 201 });
29  } catch (error) {
30    return NextResponse.json({ error: 'Failed to create item' }, { status: 500 });
31  }
32}

Once your app is deployed to a real server (Netlify serverless functions, Vercel serverless functions, or a Node.js server), you're no longer constrained by the WebContainer's TCP limitation. You can optionally migrate from the Atlas Data API to mongoose for a richer development experience: schema validation, middleware hooks, populate for references, a cleaner query API, and better TypeScript integration through typed schemas. The migration involves installing mongoose, creating model files, and replacing the Data API fetch calls in lib/mongodb.ts with mongoose model methods. Your API routes barely change since they're already abstracted behind the mongodb utility. Whether to migrate is a product decision: if your Data API implementation is working well in production, there's no urgent need to change it. Migrate if you need features like mongoose middleware, complex aggregations, or you're onboarding other developers who know mongoose better.

1// lib/mongoose.ts — alternative to Data API for deployed environments
2import mongoose from 'mongoose';
3
4const MONGODB_URI = process.env.MONGODB_URI!; // Full connection string with TCP
5
6if (!MONGODB_URI) {
7  throw new Error('Please define MONGODB_URI in .env');
8}
9
10let cached = global.mongoose;
11if (!cached) {
12  cached = global.mongoose = { conn: null, promise: null };
13}
14
15export async function connectDB() {
16  if (cached.conn) return cached.conn;
17  cached.promise = mongoose.connect(MONGODB_URI);
18  cached.conn = await cached.promise;
19  return cached.conn;
20}