How to Integrate Bolt.new with OpenAI GPT

Bolt's AI agent has deep knowledge of the OpenAI SDK and can generate a complete working integration from a single well-crafted prompt. The agent will install the openai package, create the API route file, set up streaming, and generate a chat UI component automatically. You don't need to write the boilerplate code yourself — your job is to describe what you want clearly. The most important detail to specify is streaming behavior: without it, your app will wait for the full response before displaying anything, which feels sluggish for longer answers. Also specify that you want the API key read from environment variables (not hardcoded), which Bolt handles correctly by default but it's good to be explicit. After Bolt generates the code, you'll see a message in the chat asking you to add your API key to the .env file.

After Bolt generates the integration code, you need to add your real OpenAI API key to the .env file in your project root. In a Next.js project, server-side environment variables (without a NEXT_PUBLIC_ prefix) are only readable by API routes and server components — they never get bundled into client JavaScript. Your OPENAI_API_KEY must never have a NEXT_PUBLIC_ prefix. Find your API key at platform.openai.com/api-keys. If you don't have one yet, click 'Create new secret key' and give it a descriptive name like 'bolt-app'. Copy the key immediately — OpenAI only shows it once. Paste it into your .env file. You may also want to set an optional OPENAI_MAX_TOKENS variable to control response length and manage API costs. After saving .env, the Bolt preview should automatically restart the dev server and pick up the new variable.

1# .env — add your real API key here, never commit this file
2OPENAI_API_KEY=sk-proj-your-api-key-here
3OPENAI_MODEL=gpt-4o-mini
4# Optional: limit response length to control costs
5OPENAI_MAX_TOKENS=1000

Bolt generates the API route automatically, but understanding the streaming pattern helps you customize it. The route uses OpenAI's stream: true option combined with a ReadableStream response. Instead of waiting for the full completion, the API route creates a ReadableStream that yields text chunks as they arrive from OpenAI. The client reads this stream and appends each chunk to the displayed message. This is fundamentally different from a regular JSON response — the HTTP connection stays open until OpenAI finishes generating, and data flows incrementally. One important detail: the route must set appropriate response headers (Content-Type: text/plain or text/event-stream) so the browser knows to process it as a stream rather than waiting for the complete response body. Bolt handles this correctly in the generated code, but if you see responses that appear all at once after a delay, check that the streaming headers are set correctly.

1import OpenAI from 'openai';
2import { NextResponse } from 'next/server';
3
4const openai = new OpenAI({
5  apiKey: process.env.OPENAI_API_KEY,
6});
7
8export async function POST(request: Request) {
9  try {
10    const { messages } = await request.json();
11
12    const stream = await openai.chat.completions.create({
13      model: process.env.OPENAI_MODEL || 'gpt-4o-mini',
14      messages,
15      stream: true,
16      max_tokens: parseInt(process.env.OPENAI_MAX_TOKENS || '1000'),
17    });
18
19    // Create a ReadableStream to pipe chunks to the client
20    const readableStream = new ReadableStream({
21      async start(controller) {
22        const encoder = new TextEncoder();
23        for await (const chunk of stream) {
24          const text = chunk.choices[0]?.delta?.content || '';
25          if (text) {
26            controller.enqueue(encoder.encode(text));
27          }
28        }
29        controller.close();
30      },
31    });
32
33    return new Response(readableStream, {
34      headers: {
35        'Content-Type': 'text/plain; charset=utf-8',
36        'Transfer-Encoding': 'chunked',
37      },
38    });
39  } catch (error: unknown) {
40    const message = error instanceof Error ? error.message : 'OpenAI API error';
41    return NextResponse.json({ error: message }, { status: 500 });
42  }
43}

The system prompt is the most powerful way to customize how GPT responds. It defines the AI's persona, knowledge scope, response format, and behavioral constraints. You pass it as the first message in the messages array with role: 'system'. Good system prompts are specific about format (bullet points vs paragraphs, response length), scope (what topics the AI should and shouldn't discuss), and persona (formal vs casual, expert vs beginner-friendly). In Bolt apps, the system prompt is typically hardcoded in the API route for security — you don't want users to override it via client-side manipulation. For more dynamic applications, you can store system prompts in your database and load them server-side before passing to OpenAI. Test your system prompt thoroughly before deploying, as it significantly affects user experience.

1// In your API route, construct messages with system prompt
2const messagesWithSystem = [
3  {
4    role: 'system' as const,
5    content: `You are a helpful assistant. Be concise and accurate.
6    Format responses with bullet points when listing multiple items.
7    If you don't know something, say so rather than guessing.`,
8  },
9  ...messages, // user conversation messages from the request
10];
11
12// Then pass messagesWithSystem to the OpenAI call
13const stream = await openai.chat.completions.create({
14  model: 'gpt-4o-mini',
15  messages: messagesWithSystem,
16  stream: true,
17});

Testing in Bolt's WebContainer preview is useful for development, but you must deploy to confirm the integration works in production. During Bolt development, direct client-to-OpenAI calls may occasionally encounter CORS issues due to WebContainer's security headers — these problems disappear in deployment because API routes execute as true server-side functions outside the browser sandbox. To deploy via Netlify: connect your GitHub repository in Bolt's settings, push your code, then log into Netlify and add your environment variables in Site Settings → Environment Variables. Add OPENAI_API_KEY, OPENAI_MODEL, and OPENAI_MAX_TOKENS. For Vercel, add them in Project Settings → Environment Variables. Note that incoming webhooks from OpenAI (for features like Assistants API callback) cannot be received during WebContainer development — you need a deployed URL. For rate limit management in production, consider adding request debouncing in the chat component to prevent users from sending messages before the previous response completes.