How to Integrate Bolt.new with Filestack

Filestack uses a simple API key for client-side authentication. Unlike OAuth-based services, there is no multi-step authentication flow for basic uploads — just include your API key in the Picker initialization. Sign up at filestack.com, log into the dashboard, and your API key is displayed prominently on the main dashboard page. For security, Filestack's API key is a public key (it identifies your application, not a secret credential). You can safely expose it in client-side code with the VITE_ prefix for Vite projects. The API key grants upload permissions to your Filestack account — rate limiting and storage limits are enforced server-side by Filestack. If you need to restrict who can upload (prevent unauthorized uploads to your account), implement Filestack Security Policies using your App Secret — covered in step 4. The free Filestack plan (Starter) includes 5GB storage, 1,000 uploads per month, 500 transformations, and access to all cloud source connectors (Google Drive, Dropbox, Instagram). This is sufficient for development and low-traffic production apps. Paid plans (Growth $35/mo, Scale $149/mo) increase storage and transformation limits and add features like workflow automations.

1# .env
2VITE_FILESTACK_API_KEY=your_filestack_api_key_here
3
4# For Next.js projects:
5NEXT_PUBLIC_FILESTACK_API_KEY=your_filestack_api_key_here
6
7# Only needed for security policies (optional):
8FILESTACK_APP_SECRET=your_app_secret_here
9
10# Note: API key is a PUBLIC identifier, safe to expose client-side with VITE_ prefix.
11# App Secret must NEVER be in client-side code — server-only.

Filestack's React package (@filestack/react) provides pre-built components for the most common upload patterns. The two main components are PickerOverlay (opens as a modal overlay when triggered) and PickerInline (renders inline in your page layout). For most upload flows, PickerOverlay is the right choice — it opens on a button click and closes after upload completes. The Picker configuration object (options prop) controls all aspects of the upload experience. Key options: accept (array of MIME types or extensions), maxFiles (max number of files per upload session), maxSize (max file size in bytes), sources (which upload sources to show — local_file_system, googledrive, dropbox, instagram, facebook, url, imagesearch), imageMin / imageMax (pixel dimension constraints), transformations (built-in image editor features — crop, circle, rotate, filter). The onSuccess callback receives a PickerResponse object containing filesUploaded (array of PickerFileMetadata objects, each with handle, url, filename, mimetype, size, and more). The handle is the unique identifier for the file — store this in your database. The url is the full CDN URL. Both are permanent. Important WebContainer note: the Picker widget opens as a modal and communicates with Filestack's servers over HTTPS — this works perfectly in Bolt's WebContainer preview. The widget handles file selection UI, progress tracking, and upload entirely client-side. No server-side route is needed for basic uploads.

1// components/FilestackUploader.tsx
2import { useState } from 'react';
3import { PickerOverlay } from '@filestack/react';
4
5interface UploadedFile {
6  handle: string;
7  url: string;
8  filename: string;
9  mimetype: string;
10  size: number;
11}
12
13interface FilestackUploaderProps {
14  onUploadComplete: (files: UploadedFile[]) => void;
15  accept?: string[];
16  maxFiles?: number;
17  label?: string;
18}
19
20export function FilestackUploader({
21  onUploadComplete,
22  accept = ['image/*', 'application/pdf'],
23  maxFiles = 5,
24  label = 'Upload Files',
25}: FilestackUploaderProps) {
26  const [isOpen, setIsOpen] = useState(false);
27  const apikey = import.meta.env.VITE_FILESTACK_API_KEY;
28
29  return (
30    <div>
31      <button
32        onClick={() => setIsOpen(true)}
33        className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700 transition-colors"
34      >
35        {label}
36      </button>
37
38      {isOpen && (
39        <PickerOverlay
40          apikey={apikey}
41          onSuccess={(res) => {
42            const files: UploadedFile[] = res.filesUploaded.map((f) => ({
43              handle: f.handle,
44              url: f.url,
45              filename: f.filename,
46              mimetype: f.mimetype,
47              size: f.size,
48            }));
49            onUploadComplete(files);
50            setIsOpen(false);
51          }}
52          onError={(err) => {
53            console.error('Filestack upload error:', err);
54            setIsOpen(false);
55          }}
56          onClose={() => setIsOpen(false)}
57          pickerOptions={{
58            accept,
59            maxFiles,
60            sources: ['local_file_system', 'googledrive', 'dropbox', 'url'],
61            storeTo: {
62              location: 'gcs',
63              path: '/uploads/',
64            },
65          }}
66        />
67      )}
68    </div>
69  );
70}

Filestack's most powerful feature beyond the upload widget is its transformation API: you can resize, crop, convert, watermark, and optimize any uploaded image by modifying the CDN URL. No backend processing required — transformations are applied by Filestack's CDN servers on-the-fly and cached for subsequent requests. Transformation URL format: https://cdn.filestackcontent.com/[transformations]/[handle]. Multiple transformations are chained with / separators. Common transformations: - resize=width:300,height:300 — resize to 300x300 (may distort) - resize=width:300,height:300,fit:crop — resize and crop to exactly 300x300 - resize=width:600 — resize to 600px wide, maintain aspect ratio - quality=value:80 — compress to 80% quality (JPEG) - output=format:webp — convert to WebP format - rotate=deg:90 — rotate 90 degrees - flip — flip horizontally - watermark=file:https://example.com/logo.png,size:15,position:bottom-right — add watermark - circle — crop to circle (great for avatars) - blur=amount:5 — apply Gaussian blur Create a utility function that generates transformation URLs from a Filestack handle and a configuration object. This makes it easy to generate thumbnails, medium-size images, and full-size images from the same handle stored in your database.

1// lib/filestack-transforms.ts
2const CDN = 'https://cdn.filestackcontent.com';
3
4function buildUrl(handle: string, transforms: string): string {
5  return `${CDN}/${transforms}/${handle}`;
6}
7
8export const filestack = {
9  // 200x200 square thumbnail (default)
10  thumbnail(handle: string, size = 200): string {
11    return buildUrl(handle, `resize=width:${size},height:${size},fit:crop/quality=value:80`);
12  },
13
14  // Responsive width with quality optimization
15  medium(handle: string, width = 600): string {
16    return buildUrl(handle, `resize=width:${width}/quality=value:85`);
17  },
18
19  // Full size with mild compression
20  full(handle: string): string {
21    return buildUrl(handle, 'quality=value:90');
22  },
23
24  // Circular crop (perfect for avatars)
25  avatar(handle: string, size = 120): string {
26    return buildUrl(handle, `resize=width:${size},height:${size},fit:crop/circle`);
27  },
28
29  // WebP conversion for modern browsers
30  webp(handle: string, width?: number): string {
31    const resize = width ? `resize=width:${width}/` : '';
32    return buildUrl(handle, `${resize}output=format:webp/quality=value:85`);
33  },
34
35  // Direct download link
36  download(handle: string, filename?: string): string {
37    const dl = filename ? `?dl=${encodeURIComponent(filename)}` : '?dl=true';
38    return `${CDN}/content/${handle}${dl}`;
39  },
40
41  // Raw CDN URL
42  raw(handle: string): string {
43    return `${CDN}/${handle}`;
44  },
45};
46
47// Usage example:
48// filestack.thumbnail('AbC123', 100)  → tiny square
49// filestack.avatar('AbC123')          → circular profile photo
50// filestack.medium('AbC123', 800)     → blog post hero image

By default, any JavaScript application with your Filestack API key can upload files to your account. For production apps where you need to restrict uploads — prevent unauthorized users from uploading, limit file types at the API level, or set per-user upload quotas — implement Filestack Security Policies. Filestack Security works by generating a policy and signature on your server using your App Secret. The policy is a JSON object specifying what is allowed (expiry time, maximum file size, allowed MIME types, allowed operations). The signature is an HMAC-SHA256 hash of the base64-encoded policy using your App Secret. You pass both policy and signature to the Picker instead of just the API key. Since the policy must be signed server-side (the App Secret must never reach the client), create a Next.js API route that generates a fresh policy+signature pair. Call this endpoint before opening the Picker and pass the returned values as pickerOptions.policy and pickerOptions.signature. Policies have an expiry time (set to 30–60 minutes) — generate a new policy each time the user opens the Picker. This security layer is optional for most Bolt apps — basic API key authentication is sufficient if you trust your users. Implement Security Policies for apps handling sensitive files, apps with paid upload plans where you need to prevent abuse, or apps with strict compliance requirements.

1// app/api/filestack/policy/route.ts
2import { NextResponse } from 'next/server';
3import crypto from 'crypto';
4
5export async function GET() {
6  const appSecret = process.env.FILESTACK_APP_SECRET;
7  if (!appSecret) {
8    return NextResponse.json({ error: 'Filestack App Secret not configured' }, { status: 500 });
9  }
10
11  const expiry = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
12
13  const policyObject = {
14    expiry,
15    call: ['read', 'store', 'convert', 'pick', 'run_workflow'],
16    maxSize: 20 * 1024 * 1024, // 20MB max file size
17  };
18
19  const policy = Buffer.from(JSON.stringify(policyObject)).toString('base64url');
20  const signature = crypto
21    .createHmac('sha256', appSecret)
22    .update(policy)
23    .digest('hex');
24
25  return NextResponse.json({ policy, signature });
26}
27
28// In your FilestackUploader component (secure version):
29// const [security, setSecurity] = useState<{policy: string; signature: string} | null>(null);
30// useEffect(() => {
31//   fetch('/api/filestack/policy').then(r => r.json()).then(setSecurity);
32// }, []);
33//
34// Then pass to PickerOverlay:
35// pickerOptions={{ ...options, policy: security?.policy, signature: security?.signature }}