How to Integrate Lovable with Filestack

Log in to your Filestack account at app.filestack.com. The main dashboard shows your API Key prominently — it is a short alphanumeric string like AHZb0pCeRvK8dpW7RqmTzC. This is your public API key, safe to use in client-side code and in the Filestack Picker widget configuration. Unlike most API keys, the Filestack API key is intentionally public-facing — it identifies your Filestack account but does not grant destructive API access by itself. For security-restricted operations (generating signed URLs, processing workflows, webhook verification), you also need the API Secret. Find it by going to your Filestack Dashboard → Security → Security Policy. The API Secret is the longer key shown there. This key is sensitive — treat it like a password. It must only be used in your Edge Function via Cloud Secrets, never in frontend code. Also note your Filestack Security settings. By default, Filestack allows unrestricted access to any uploaded file via its CDN URL. For production apps with user-uploaded content, enable security policies in the Filestack dashboard (Security → Policies tab). With security enabled, every file access requires a signed policy — the Edge Function generates these on-demand. Start with security disabled during development for simpler testing, then enable it before going to production. Optionally, configure your Filestack application's storage settings: in the Dashboard → App Settings, you can configure whether Filestack stores files in its own S3 infrastructure (default) or in your own S3 bucket (Intelligent Ingestion). Using your own S3 bucket keeps you in control of the files long-term but requires additional AWS configuration.

Store your Filestack API Secret in Lovable's Cloud Secrets. Open the Cloud tab in Lovable, click Secrets, and add FILESTACK_API_SECRET with your API secret value. You do not need to add the API key as a secret since it is safe to use in frontend code — but you may want to add it as NEXT_PUBLIC_FILESTACK_API_KEY or VITE_FILESTACK_API_KEY so it is configured in one place even if technically safe in source code. Next, install the Filestack JavaScript SDK in your Lovable project. Use the Lovable chat to request the package installation: 'Add the filestack-js npm package to the project as a dependency.' Lovable updates package.json and the package becomes available for import in your React components. The SDK provides both the Picker component and utility functions for constructing transformation URLs. For the Edge Function, Filestack's Node.js SDK (@filestack/sdk) can be imported in Deno using the npm: specifier. However, for most Edge Function use cases (generating security policies, calling the Filestack API), you can use standard fetch calls with the API secret rather than importing the full SDK — keeping the Edge Function lightweight. The Filestack Picker is typically loaded either as an npm package import or via a script tag from Filestack's CDN. For Lovable React projects, the npm package approach is cleaner: import { PickerOverlay } from 'filestack-react' and use it as a React component in your upload UI. The PickerOverlay component handles the full upload flow and calls an onSuccess callback with the uploaded file's URL and handle.

The Edge Function handles the server-side operations that require the API secret: generating signed security policies for restricted file access, and calling Filestack's workflow API for server-side processing operations. For basic Filestack integrations without security policies enabled, this Edge Function is optional — but it becomes necessary as soon as you enable Filestack security. Filestack security policies consist of a policy JSON object (specifying which operations are allowed, expiry time, and optionally which file handles or paths are allowed) and an HMAC-SHA256 signature of that policy computed using your API secret. The signed policy + signature combination is appended to CDN URLs or API calls to authorize restricted operations. The Edge Function takes a request specifying what operation the user needs to perform (view a specific file, upload, transform), computes the policy and signature, and returns them to the frontend. The frontend then appends the policy and signature to Filestack URLs or API calls. This keeps the secret entirely server-side while giving the frontend the tokens it needs for authorized access. For image transformation, Filestack transformation URLs do not require a secret — they are publicly accessible URL parameters on the Filestack CDN URL. Construct them in the frontend directly by manipulating the CDN URL string. Only add security policy tokens to transformation URLs if Filestack security is enabled on your account.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2import { encodeBase64 } from 'https://deno.land/std@0.168.0/encoding/base64.ts'
3
4const corsHeaders = {
5  'Access-Control-Allow-Origin': '*',
6  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
7  'Access-Control-Allow-Methods': 'POST, OPTIONS',
8}
9
10async function hmacSha256(secret: string, message: string): Promise<string> {
11  const encoder = new TextEncoder()
12  const key = await crypto.subtle.importKey(
13    'raw',
14    encoder.encode(secret),
15    { name: 'HMAC', hash: 'SHA-256' },
16    false,
17    ['sign']
18  )
19  const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(message))
20  return Array.from(new Uint8Array(sig)).map(b => b.toString(16).padStart(2, '0')).join('')
21}
22
23serve(async (req) => {
24  if (req.method === 'OPTIONS') {
25    return new Response('ok', { headers: corsHeaders })
26  }
27
28  const apiSecret = Deno.env.get('FILESTACK_API_SECRET')
29  if (!apiSecret) {
30    return new Response(
31      JSON.stringify({ error: 'FILESTACK_API_SECRET not configured' }),
32      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
33    )
34  }
35
36  try {
37    const { operation = 'read', handle, expiresIn = 3600 } = await req.json()
38
39    const expiry = Math.floor(Date.now() / 1000) + expiresIn
40    const policyObj: Record<string, unknown> = {
41      call: [operation],
42      expiry,
43    }
44    if (handle) policyObj.handle = handle
45
46    const policyJson = JSON.stringify(policyObj)
47    const policyEncoded = encodeBase64(policyJson)
48      .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
49
50    const signature = await hmacSha256(apiSecret, policyEncoded)
51
52    return new Response(
53      JSON.stringify({ policy: policyEncoded, signature }),
54      { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
55    )
56  } catch (err) {
57    return new Response(
58      JSON.stringify({ error: err instanceof Error ? err.message : 'Unknown error' }),
59      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
60    )
61  }
62})

Filestack's most powerful feature for Lovable apps is transformation URLs — on-the-fly image processing without any server-side code. A Filestack CDN URL looks like https://cdn.filestackcontent.com/HANDLE. By inserting transformation parameters between the base URL and the handle, you get different processed versions of the same file. Common transformation operations useful in Lovable apps: resize (width, height, fit mode) for generating different image sizes; output format conversion (output=format:webp) for converting JPEGs and PNGs to WebP for better compression; quality reduction (quality=value:75) for balancing file size and visual quality; smart crop (crop=faces) for intelligent face-centered cropping for profile photos; and compress for automatic optimization without explicit quality setting. Construct transformation URLs in your React components by building a transformation chain string. The chain is inserted as URL segments: https://cdn.filestackcontent.com/resize=width:400,height:300,fit:crop/output=format:webp/quality=value:80/HANDLE. This single URL serves a 400x300px WebP image at 80% quality — all processed and cached by Filestack's CDN from the original uploaded file. For profile photos, a common transformation chain is: resize=width:200,height:200,fit:crop/crop=faces:true/output=format:webp — this resizes to 200x200, crops to the face, and outputs as WebP. Build a utility function in your Lovable project that constructs these URLs from a Filestack handle and a size/format specification, then use it consistently throughout all image display components.

1// src/lib/filestack.ts
2const FILESTACK_CDN = 'https://cdn.filestackcontent.com'
3
4interface TransformOptions {
5  width?: number
6  height?: number
7  format?: 'webp' | 'jpeg' | 'png' | 'auto'
8  quality?: number
9  fit?: 'crop' | 'scale' | 'fill' | 'max'
10  faceCrop?: boolean
11}
12
13export function getFilestackUrl(handle: string, options: TransformOptions = {}): string {
14  // Extract handle if full URL was passed
15  const h = handle.includes('cdn.filestackcontent.com')
16    ? handle.split('/').pop() ?? handle
17    : handle
18
19  const transforms: string[] = []
20
21  if (options.width || options.height) {
22    const parts = []
23    if (options.width) parts.push(`width:${options.width}`)
24    if (options.height) parts.push(`height:${options.height}`)
25    if (options.fit) parts.push(`fit:${options.fit}`)
26    transforms.push(`resize=${parts.join(',')}`)
27  }
28
29  if (options.faceCrop) {
30    transforms.push('crop=faces:true')
31  }
32
33  const fmt = options.format ?? 'webp'
34  if (fmt !== 'auto') {
35    transforms.push(`output=format:${fmt}`)
36  }
37
38  if (options.quality) {
39    transforms.push(`quality=value:${options.quality}`)
40  }
41
42  const chain = transforms.length > 0 ? transforms.join('/') + '/' : ''
43  return `${FILESTACK_CDN}/${chain}${h}`
44}
45
46export function getAvatarUrl(handle: string, sizePx: number): string {
47  return getFilestackUrl(handle, {
48    width: sizePx * 2, // 2x for retina
49    height: sizePx * 2,
50    fit: 'crop',
51    faceCrop: true,
52    format: 'webp',
53    quality: 85,
54  })
55}
56
57export function getThumbnailUrl(handle: string): string {
58  return getFilestackUrl(handle, { width: 160, height: 160, fit: 'crop', format: 'webp', quality: 75 })
59}