How to Integrate Bolt.new with Backblaze B2

Before writing any code, set up your Backblaze B2 storage bucket and generate the credentials your Bolt app will use. Log into backblaze.com, navigate to B2 Cloud Storage → Buckets, and click 'Create a Bucket'. Choose a globally unique bucket name (B2 bucket names are global across all Backblaze accounts), set access to 'Private' for secure applications (you will use pre-signed URLs) or 'Public' for assets you want universally accessible like profile images. Select your preferred region — us-west-004 (Western US) is Backblaze's primary region. After creating the bucket, note the bucket's Endpoint URL shown in the bucket settings — it follows the format s3.[region].backblazeb2.com. This is your S3-compatible endpoint and the most important configuration value. Next, create an Application Key: navigate to Account → App Keys → Add a New Application Key. Give it a descriptive name ('my-app-uploads'), optionally restrict it to your specific bucket (recommended for security — don't grant access to all buckets), and select the capabilities you need: readFiles, writeFiles, deleteFiles. After creating, immediately copy the keyID and applicationKey — Backblaze only shows the applicationKey once. Store these as environment variables in your Bolt project's .env file: B2_KEY_ID, B2_APP_KEY, B2_BUCKET_NAME, and B2_ENDPOINT. Never paste these credentials into your Bolt chat or code directly.

1# .env
2B2_KEY_ID=your_application_key_id_here
3B2_APP_KEY=your_application_key_here
4B2_BUCKET_NAME=your-bucket-name
5B2_ENDPOINT=https://s3.us-west-004.backblazeb2.com
6B2_REGION=us-west-004
7
8# Optional: Cloudflare CDN domain connected to your B2 bucket
9# Enables free egress for public files
10VITE_B2_CDN_URL=https://cdn.yourdomain.com

Install the AWS S3 SDK packages and configure the S3 client to point at Backblaze B2. The @aws-sdk/client-s3 package is the official modular AWS SDK v3 for S3 operations. The @aws-sdk/s3-request-presigner package generates pre-signed URLs for browser-side uploads and downloads. Both are pure JavaScript packages with no native binaries — they install and run correctly in Bolt's WebContainer. The S3 client configuration for B2 has four key differences from standard AWS S3: the endpoint is set to B2's regional URL (https://s3.us-west-004.backblazeb2.com), credentials use B2's keyId/appKey values in the accessKeyId/secretAccessKey fields, the region is set to the B2 region code (us-west-004), and forcePathStyle must be set to true (B2 uses path-style bucket URLs like s3.endpoint.com/bucket-name instead of AWS's virtual-hosted-style bucket-name.s3.amazonaws.com). Create the S3 client in a lib/b2.ts file that is imported by your API routes. Because this file uses process.env credentials, it runs only in server-side contexts (Next.js API routes) — never in browser-side components. The Vite VITE_ prefix is for client-side public values only; B2 credentials must stay in server-side environment variables without the VITE_ prefix.

1// lib/b2.ts
2import { S3Client } from '@aws-sdk/client-s3';
3
4const endpoint = process.env.B2_ENDPOINT;
5const region = process.env.B2_REGION || 'us-west-004';
6const accessKeyId = process.env.B2_KEY_ID!;
7const secretAccessKey = process.env.B2_APP_KEY!;
8
9if (!endpoint || !accessKeyId || !secretAccessKey) {
10  throw new Error('Missing Backblaze B2 environment variables: B2_ENDPOINT, B2_KEY_ID, B2_APP_KEY');
11}
12
13export const b2Client = new S3Client({
14  endpoint,
15  region,
16  credentials: {
17    accessKeyId,
18    secretAccessKey,
19  },
20  forcePathStyle: true, // Required for B2 — path-style URLs
21});
22
23export const b2Bucket = process.env.B2_BUCKET_NAME!;
24
25if (!b2Bucket) {
26  throw new Error('Missing B2_BUCKET_NAME environment variable');
27}

The pre-signed URL pattern is the recommended way to upload files to B2 from a browser. A pre-signed URL is a temporary, time-limited URL that grants permission to upload a specific file to B2 without exposing your B2 credentials to the browser. The flow is: browser asks your API route for a pre-signed URL, API route generates the URL using your server-side B2 credentials, browser uploads directly to B2 using that URL, B2 accepts the upload without needing to know your app's credentials. The API route for generating upload URLs uses PutObjectCommand from @aws-sdk/client-s3 and getSignedUrl from @aws-sdk/s3-request-presigner. You define the target S3 key (the object path within your bucket), set the expiry time (60–300 seconds is typical for interactive uploads), and optionally specify the content type. The API route returns the pre-signed URL to the browser. For the S3 object key naming strategy, include path prefixes to organize uploads: 'profile-photos/' for avatars, 'documents/' for PDFs, 'uploads/[userId]/' for user-specific files. Include a timestamp or UUID in the filename to prevent collisions. For example: profile-photos/2026-01-15-550e8400-e29b-41d4-a716-446655440000.jpg. This key becomes the file's address within your B2 bucket and, once served through Cloudflare CDN, the path portion of your CDN URL.

1// app/api/upload-url/route.ts
2import { NextResponse } from 'next/server';
3import { PutObjectCommand } from '@aws-sdk/client-s3';
4import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
5import { b2Client, b2Bucket } from '@/lib/b2';
6import crypto from 'crypto';
7
8function sanitizeFilename(filename: string): string {
9  return filename
10    .replace(/[^a-zA-Z0-9._-]/g, '-')
11    .replace(/--+/g, '-')
12    .toLowerCase();
13}
14
15export async function POST(request: Request) {
16  try {
17    const { filename, contentType, folder = 'uploads' } = await request.json();
18
19    if (!filename || !contentType) {
20      return NextResponse.json(
21        { error: 'filename and contentType are required' },
22        { status: 400 }
23      );
24    }
25
26    const sanitized = sanitizeFilename(filename);
27    const objectKey = `${folder}/${Date.now()}-${crypto.randomUUID()}-${sanitized}`;
28
29    const command = new PutObjectCommand({
30      Bucket: b2Bucket,
31      Key: objectKey,
32      ContentType: contentType,
33    });
34
35    const uploadUrl = await getSignedUrl(b2Client, command, { expiresIn: 120 });
36
37    const cdnBase = process.env.VITE_B2_CDN_URL;
38    const b2Base = process.env.B2_ENDPOINT;
39    const publicUrl = cdnBase
40      ? `${cdnBase}/${objectKey}`
41      : `${b2Base}/file/${b2Bucket}/${objectKey}`;
42
43    return NextResponse.json({ uploadUrl, objectKey, publicUrl });
44  } catch (error: unknown) {
45    const e = error as { message: string };
46    return NextResponse.json({ error: e.message }, { status: 500 });
47  }
48}

With the pre-signed URL API route in place, build the React component that handles the user-facing upload experience. The upload flow has three steps: (1) user selects a file, (2) component calls /api/upload-url to get a pre-signed URL, (3) component uploads the file directly to B2 using a PUT request to the pre-signed URL. This entire flow works in Bolt's WebContainer preview because it uses only outbound HTTPS requests — no incoming webhooks or TCP connections. For progress tracking, use XMLHttpRequest instead of fetch. XHR provides an upload.onprogress event that fires with loaded and total bytes, enabling a real-time progress bar. Fetch does not have a progress API for upload tracking. The XHR pattern: create an XMLHttpRequest, open a PUT request to the pre-signed URL, set the Content-Type header, listen for upload.onprogress, and call xhr.send(file) to start the upload. After a successful upload, the publicUrl returned by /api/upload-url is immediately usable if your B2 bucket is public. For private buckets, generate a separate pre-signed GetObject URL via a download API route. Store the objectKey (not the pre-signed URL, which expires) in your database — generate fresh download URLs on demand from the objectKey whenever a user requests access.

1// components/FileUploader.tsx
2import { useState, useCallback } from 'react';
3
4interface FileUploaderProps {
5  onUploadComplete: (publicUrl: string, objectKey: string) => void;
6  accept?: string;
7  maxSizeMB?: number;
8  folder?: string;
9}
10
11export function FileUploader({
12  onUploadComplete,
13  accept = 'image/*,application/pdf',
14  maxSizeMB = 20,
15  folder = 'uploads',
16}: FileUploaderProps) {
17  const [progress, setProgress] = useState(0);
18  const [status, setStatus] = useState<'idle' | 'uploading' | 'done' | 'error'>('idle');
19  const [error, setError] = useState('');
20  const [isDragging, setIsDragging] = useState(false);
21
22  const uploadFile = useCallback(async (file: File) => {
23    if (file.size > maxSizeMB * 1024 * 1024) {
24      setError(`File exceeds ${maxSizeMB}MB limit`);
25      return;
26    }
27
28    setStatus('uploading');
29    setProgress(0);
30    setError('');
31
32    try {
33      // Step 1: Get pre-signed URL
34      const res = await fetch('/api/upload-url', {
35        method: 'POST',
36        headers: { 'Content-Type': 'application/json' },
37        body: JSON.stringify({ filename: file.name, contentType: file.type, folder }),
38      });
39      const { uploadUrl, objectKey, publicUrl } = await res.json();
40
41      // Step 2: Upload directly to B2 with progress tracking
42      await new Promise<void>((resolve, reject) => {
43        const xhr = new XMLHttpRequest();
44        xhr.open('PUT', uploadUrl);
45        xhr.setRequestHeader('Content-Type', file.type);
46        xhr.upload.onprogress = (e) => {
47          if (e.lengthComputable) setProgress(Math.round((e.loaded / e.total) * 100));
48        };
49        xhr.onload = () => (xhr.status === 200 ? resolve() : reject(new Error(`Upload failed: ${xhr.status}`)));
50        xhr.onerror = () => reject(new Error('Network error during upload'));
51        xhr.send(file);
52      });
53
54      setStatus('done');
55      onUploadComplete(publicUrl, objectKey);
56    } catch (err: unknown) {
57      const e = err as { message: string };
58      setError(e.message);
59      setStatus('error');
60    }
61  }, [onUploadComplete, folder, maxSizeMB]);
62
63  return (
64    <div
65      onDragOver={(e) => { e.preventDefault(); setIsDragging(true); }}
66      onDragLeave={() => setIsDragging(false)}
67      onDrop={(e) => { e.preventDefault(); setIsDragging(false); const f = e.dataTransfer.files[0]; if (f) uploadFile(f); }}
68      className={`border-2 border-dashed rounded-xl p-8 text-center transition-colors ${
69        isDragging ? 'border-blue-500 bg-blue-50' : 'border-gray-300 bg-gray-50 hover:bg-gray-100'
70      }`}
71    >
72      {status === 'idle' && (
73        <>
74          <p className="text-gray-600 mb-3">Drop a file here or</p>
75          <label className="cursor-pointer bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700">
76            Browse Files
77            <input type="file" accept={accept} className="hidden" onChange={(e) => { const f = e.target.files?.[0]; if (f) uploadFile(f); }} />
78          </label>
79        </>
80      )}
81      {status === 'uploading' && (
82        <div>
83          <p className="text-gray-600 mb-2">Uploading... {progress}%</p>
84          <div className="w-full bg-gray-200 rounded-full h-2">
85            <div className="bg-blue-600 h-2 rounded-full transition-all" style={{ width: `${progress}%` }} />
86          </div>
87        </div>
88      )}
89      {status === 'done' && <p className="text-green-600 font-medium">Upload complete!</p>}
90      {status === 'error' && <p className="text-red-600">{error}</p>}
91    </div>
92  );
93}

Deploy your Bolt project to Netlify or Bolt Cloud to move into a real Node.js environment. After deployment, update your environment variables in the hosting dashboard (Netlify: Site Settings → Environment Variables) with your B2 credentials. The B2 API route runs as a serverless function post-deployment, keeping credentials secure. To connect Cloudflare for free B2 egress — one of B2's most compelling advantages — follow these steps: add your domain to Cloudflare, create a CNAME DNS record pointing to your B2 bucket's download endpoint (for public buckets: f004.backblazeb2.com or the region-specific equivalent). Enable Cloudflare proxy (orange cloud icon). Your B2 files are now served through Cloudflare's global CDN with no B2 egress charges. Update the VITE_B2_CDN_URL environment variable in your deployment to your Cloudflare-proxied domain. For private buckets, you can use Cloudflare Workers to add authentication headers before forwarding requests to B2 — but this is an advanced pattern. For most Bolt apps, use a public B2 bucket for user-generated content like profile photos and use pre-signed download URLs for sensitive documents. The WebContainer TCP limitation note: during Bolt development, the file upload (outbound PUT request) works fine in the preview. Bolt's WebContainer cannot receive incoming requests from B2, so if B2 sends event notifications (available in B2 Event Notifications beta), register notification URLs using your deployed Netlify or Bolt Cloud domain, not a localhost or WebContainer preview URL.

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"
11
12# Environment variables to add in Netlify Dashboard:
13# B2_KEY_ID = your_application_key_id
14# B2_APP_KEY = your_application_key
15# B2_BUCKET_NAME = your_bucket_name
16# B2_ENDPOINT = https://s3.us-west-004.backblazeb2.com
17# B2_REGION = us-west-004
18# VITE_B2_CDN_URL = https://cdn.yourdomain.com (if using Cloudflare)