How to Integrate Bolt.new with MongoDB (Self-Hosted)

Before writing any code, it is important to understand exactly what will and will not work in Bolt's preview when connecting to self-hosted MongoDB. Bolt's WebContainer virtualizes a Node.js runtime inside the browser using WebAssembly. The networking layer maps HTTP requests to the browser's fetch API and WebSocket connections to the browser's WebSocket API. However, raw TCP socket operations — which is how both the mongodb Node.js driver and mongoose connect to MongoDB servers — are not supported. When your app starts and mongoose calls mongoose.connect('mongodb://...'), the underlying driver attempts to open a TCP socket to the MongoDB port (default 27017). This TCP operation is silently rejected by the WebContainer, resulting in a 'MongooseServerSelectionError: connect ECONNREFUSED' or a timeout after 30 seconds. This limitation applies specifically to the Bolt WebContainer preview. The code itself is not wrong. The same mongoose connection string and code work perfectly on: - Netlify (after npm run build + deploy) - Vercel (after npm run build + deploy) - Render, Railway, Fly.io, or any VPS - Your local machine running Node.js outside of Bolt If you want to test database operations during development in Bolt, you have two viable options: (1) use MongoDB Atlas with its HTTP Data API, which communicates over HTTPS instead of TCP, or (2) use Supabase PostgreSQL, which uses HTTP via PostgREST. Both work in the WebContainer. If you need self-hosted MongoDB specifically for production (self-hosted gives you more control over data residency, costs, and schema), write the mongoose code in Bolt and test it by deploying — there is no workaround that makes TCP work in the WebContainer.

1// This is what fails in Bolt's WebContainer:
2// import mongoose from 'mongoose';
3// await mongoose.connect('mongodb://localhost:27017/mydb');
4// Error: MongooseServerSelectionError: connect ECONNREFUSED
5
6// This works in WebContainer (Atlas HTTP Data API):
7// await fetch('https://data.mongodb-api.com/app/data-abc/endpoint/data/v1/action/findOne', {
8//   method: 'POST',
9//   headers: { 'api-key': process.env.ATLAS_API_KEY, 'Content-Type': 'application/json' },
10//   body: JSON.stringify({ dataSource: 'Cluster0', database: 'mydb', collection: 'users', filter: {} })
11// });
12
13// The mongoose code below works correctly AFTER deployment to Netlify/Vercel.

If you are using self-hosted MongoDB and will test after deployment, set up the standard Next.js mongoose connection pattern. Next.js API routes are serverless functions — each function invocation may run in a separate process, and without connection caching, each request would open a new database connection, quickly exhausting MongoDB's connection pool limit. The solution is a global connection cache: store the mongoose connection promise in a global variable that persists between hot reloads during development and between Lambda invocations in the same container during production. The pattern uses a global variable (global.mongoose) to hold the cached connection. This is the approach recommended by Next.js in their official MongoDB example. Your MongoDB URI format: for self-hosted MongoDB, it follows the pattern mongodb://[username:password@]host[:port]/[database]. For local development, mongodb://localhost:27017/mydatabase. For a remote server, mongodb://username:password@your-server-ip:27017/mydatabase. For MongoDB Atlas (cloud), it looks like mongodb+srv://username:password@cluster.mongodb.net/mydatabase — the srv format uses DNS SRV records which also go over TCP, so Atlas TCP also fails in WebContainer. Use Atlas Data API instead for Bolt preview testing.

1// lib/mongodb.ts
2import mongoose from 'mongoose';
3
4const MONGODB_URI = process.env.MONGODB_URI!;
5
6if (!MONGODB_URI) {
7  throw new Error('MONGODB_URI environment variable is not defined');
8}
9
10interface MongooseCache {
11  conn: typeof mongoose | null;
12  promise: Promise<typeof mongoose> | null;
13}
14
15declare global {
16  // eslint-disable-next-line no-var
17  var mongoose: MongooseCache | undefined;
18}
19
20const cached: MongooseCache = global.mongoose || { conn: null, promise: null };
21global.mongoose = cached;
22
23export async function connectDB(): Promise<typeof mongoose> {
24  if (cached.conn) return cached.conn;
25
26  if (!cached.promise) {
27    cached.promise = mongoose
28      .connect(MONGODB_URI, { bufferCommands: false })
29      .then((m) => {
30        console.log('MongoDB connected');
31        return m;
32      });
33  }
34
35  cached.conn = await cached.promise;
36  return cached.conn;
37}

With the connection utility ready, define your mongoose schemas and models. A mongoose model describes the shape of your MongoDB documents — the fields, their types, validation rules, and default values. Keep models in a models/ directory, one file per collection. Models should only be defined once per process, so use the pattern: module.exports = mongoose.models.ModelName || mongoose.model('ModelName', schema) to prevent 'Cannot overwrite model once compiled' errors during Next.js hot reloading. API routes in Next.js are the correct place to connect and query MongoDB. Each API route is a serverless function that runs server-side — it has access to server-only environment variables, can make database connections, and doesn't run in the browser. Never import mongoose or call connectDB() in client components, React hooks, or client-side utilities. Only in app/api/ files. For standard CRUD operations, the pattern is: call connectDB() at the top of each handler, then use your mongoose model to execute queries. Mongoose queries return promises, so await them inside try/catch blocks. Return appropriate HTTP status codes — 200 for GET success, 201 for POST (created), 400 for validation errors, 404 for not found, 500 for server errors.

1// models/User.ts
2import mongoose, { Schema, Document } from 'mongoose';
3
4export interface IUser extends Document {
5  name: string;
6  email: string;
7  role: 'user' | 'admin';
8  createdAt: Date;
9}
10
11const UserSchema = new Schema<IUser>({
12  name: { type: String, required: [true, 'Name is required'] },
13  email: {
14    type: String,
15    required: [true, 'Email is required'],
16    unique: true,
17    lowercase: true,
18    match: [/^\S+@\S+\.\S+$/, 'Invalid email format'],
19  },
20  role: { type: String, enum: ['user', 'admin'], default: 'user' },
21  createdAt: { type: Date, default: Date.now },
22});
23
24export const User =
25  mongoose.models.User ||
26  mongoose.model<IUser>('User', UserSchema);
27
28// app/api/users/route.ts
29import { NextResponse } from 'next/server';
30import { connectDB } from '@/lib/mongodb';
31import { User } from '@/models/User';
32
33export async function GET() {
34  try {
35    await connectDB();
36    const users = await User.find({}).sort({ createdAt: -1 }).limit(100);
37    return NextResponse.json(users);
38  } catch (error: unknown) {
39    const e = error as { message: string };
40    return NextResponse.json({ error: e.message }, { status: 500 });
41  }
42}
43
44export async function POST(request: Request) {
45  try {
46    await connectDB();
47    const body = await request.json();
48    const user = new User(body);
49    await user.save();
50    return NextResponse.json(user, { status: 201 });
51  } catch (error: unknown) {
52    const e = error as { message: string; code?: number };
53    const status = e.code === 11000 ? 409 : 400;
54    return NextResponse.json({ error: e.message }, { status });
55  }
56}

If you want database operations to work during Bolt development — not just post-deployment — MongoDB Atlas with the Data API is the right choice. Atlas is MongoDB's managed cloud service, and it provides an HTTP REST API (the Data API) that lets you perform CRUD operations over HTTPS without any MongoDB driver or TCP connection. This is architecturally identical to how REST databases work, making it fully compatible with Bolt's WebContainer. To enable the Atlas Data API: log into cloud.mongodb.com, select your project, click on 'Data API' in the left sidebar (under 'Data Services'), enable Data API for your cluster, and create an API key. You will get a Data API endpoint URL (looks like https://data.mongodb-api.com/app/data-xxxxx/endpoint/data/v1) and an API key. All requests include the api-key header and a JSON body specifying the dataSource (cluster name), database, collection, and operation. The Data API supports the most common operations: findOne, find, insertOne, insertMany, updateOne, updateMany, replaceOne, deleteOne, deleteMany, and aggregate. This covers 95% of real app needs. It is slightly slower than a direct driver connection due to the HTTP overhead, but for most apps this difference is imperceptible. The major benefit for Bolt development is immediate: you can test and iterate on data operations in the Bolt preview without deploying.

1// lib/atlas.ts
2const DATA_API_URL = process.env.ATLAS_DATA_API_URL!;
3const API_KEY = process.env.ATLAS_API_KEY!;
4const DATA_SOURCE = process.env.ATLAS_DATA_SOURCE || 'Cluster0';
5const DATABASE = process.env.ATLAS_DATABASE!;
6
7interface AtlasRequestBody {
8  dataSource: string;
9  database: string;
10  collection: string;
11  [key: string]: unknown;
12}
13
14async function atlasRequest<T>(action: string, body: Omit<AtlasRequestBody, 'dataSource' | 'database'>): Promise<T> {
15  const response = await fetch(`${DATA_API_URL}/action/${action}`, {
16    method: 'POST',
17    headers: {
18      'api-key': API_KEY,
19      'Content-Type': 'application/json',
20    },
21    body: JSON.stringify({ dataSource: DATA_SOURCE, database: DATABASE, ...body }),
22  });
23
24  if (!response.ok) {
25    const text = await response.text();
26    throw new Error(`Atlas Data API ${action} failed: ${text}`);
27  }
28
29  return response.json() as Promise<T>;
30}
31
32export const atlas = {
33  findDocuments: <T>(collection: string, filter = {}, projection?: object) =>
34    atlasRequest<{ documents: T[] }>('find', { collection, filter, projection }),
35
36  findOne: <T>(collection: string, filter: object) =>
37    atlasRequest<{ document: T | null }>('findOne', { collection, filter }),
38
39  insertOne: <T>(collection: string, document: T) =>
40    atlasRequest<{ insertedId: string }>('insertOne', { collection, document }),
41
42  updateOne: (collection: string, filter: object, update: object) =>
43    atlasRequest<{ matchedCount: number; modifiedCount: number }>('updateOne', {
44      collection, filter, update,
45    }),
46
47  deleteOne: (collection: string, filter: object) =>
48    atlasRequest<{ deletedCount: number }>('deleteOne', { collection, filter }),
49};

After building your application logic in Bolt, deploy to Netlify or Bolt Cloud to test the self-hosted MongoDB connection in a real Node.js environment. Self-hosted MongoDB deployment requires your MongoDB server to be accessible from the internet with the correct firewall rules, authentication, and connection string. For Netlify deployment: connect your Bolt project to Netlify via Settings → Applications → Netlify. After your first deploy, go to Netlify Dashboard → Site Settings → Environment Variables and add MONGODB_URI with your production MongoDB connection string. Trigger a redeploy after setting the environment variable. Important network requirements for self-hosted MongoDB: your MongoDB server must allow inbound connections from Netlify's or Vercel's serverless function IP ranges. Netlify runs functions on AWS Lambda (us-east-1 primarily); Vercel also uses AWS Lambda. You cannot use specific IP allowlists with serverless platforms since function IPs change dynamically — you must either open MongoDB to all IPs (0.0.0.0/0) with strong authentication, use VPN/tunnel, or use MongoDB Atlas which does not have this problem. Test the deployment: after setting MONGODB_URI in Netlify, your API routes should connect successfully. Check Netlify's function logs for connection errors. Common issues: MongoDB server not accessible from Netlify's network, authentication credentials wrong, firewall blocking port 27017, or TLS/SSL misconfiguration. For production, always enable TLS on your MongoDB server.

1# netlify.toml
2[build]
3  command = "npm run build"
4  publish = ".next"
5
6[build.environment]
7  NODE_VERSION = "20"
8
9[[plugins]]
10  package = "@netlify/plugin-nextjs"