How to Upload and Reference Static Assets (Images, Fonts, Files) in Lovable

Why static asset management in Lovable requires specific file placement

Lovable projects are built with Vite, which has a specific way of handling static files. There are two places you can put assets, and each works differently. The /public folder is for files that should be served as-is, without any processing. Files placed here are copied directly to the build output and accessible from the root URL. This is the right place for images, fonts, PDFs, favicons, and any file you want to reference by a fixed URL. The /src folder is for files that Vite processes during the build — like TypeScript files, CSS modules, and images you import directly into React components. When you import an image from /src, Vite adds a content hash to the filename for cache busting. This is useful for component-specific assets but unnecessary for most static files. The most common mistake is placing images in /src/assets and then referencing them with wrong paths in JSX. Another frequent issue is using relative paths (like 'images/logo.png' without a leading /) which break when the user navigates to a nested route like /dashboard/settings — the browser looks for images/logo.png relative to that route instead of the site root.

• Files placed in /src instead of /public — Vite processes them differently than expected
• Relative paths used instead of root-relative paths — breaks on nested routes
• Large files not uploaded to Supabase Storage — bloating the GitHub repo and build
• Binary files (images, fonts) added via AI prompt — Lovable cannot create binary files, only text
• Asset path works in preview but breaks after deployment to Vercel or Netlify

Error messages you might see

Before you start

• A Lovable project open in the editor
• The static files (images, fonts, documents) ready on your computer
• GitHub connected if uploading via GitHub (Settings → Connectors → GitHub)
• Dev Mode access (paid plans) if uploading via the built-in code editor

How to fix it

<!-- WRONG: referencing a file that does not exist in /public -->
<img src="images/hero.jpg" alt="Hero" />

<!-- CORRECT: file uploaded to /public/images/hero.jpg -->
<img src="/images/hero.jpg" alt="Hero" />

1// After uploading hero.jpg to /public/images/ via Dev Mode
2// Reference it in any React component:
3function HeroSection() {
4  return (
5    <div className="relative w-full h-96">
6      <img
7        src="/images/hero.jpg"
8        alt="Hero banner"
9        className="w-full h-full object-cover"
10      />
11    </div>
12  );
13}

// WRONG: URL path reference to a /src file — will 404
function Logo() {
  return <img src="/src/assets/logo.svg" alt="Logo" />;
}

// CORRECT: JavaScript import lets Vite handle the asset
import logoSvg from '@/assets/logo.svg';
function Logo() {
  return <img src={logoSvg} alt="Logo" />;
}

// WRONG: Storing large user files in /public via code
// This bloats the repository and does not scale

// CORRECT: Upload to Supabase Storage and get a public URL
import { supabase } from '@/integrations/supabase/client';
async function uploadFile(file: File) {
  const fileName = `${Date.now()}-${file.name}`;
  const { data, error } = await supabase.storage
    .from('uploads') // your bucket name
    .upload(fileName, file);
  if (error) throw error;
  // Get the public URL for the uploaded file
  const { data: urlData } = supabase.storage
    .from('uploads')
    .getPublicUrl(fileName);
  return urlData.publicUrl;
}

Complete code example

1import { useState } from 'react';
2import { supabase } from '@/integrations/supabase/client';
3
4// Demonstrates both /public assets and Supabase Storage usage
5export function ImageGallery() {
6  const [uploadedUrl, setUploadedUrl] = useState<string | null>(null);
7
8  // Static asset from /public folder — root-relative path
9  const staticLogo = '/images/logo.png';
10
11  // Handle user file upload to Supabase Storage
12  async function handleUpload(e: React.ChangeEvent<HTMLInputElement>) {
13    const file = e.target.files?.[0];
14    if (!file) return;
15
16    const fileName = `gallery/${Date.now()}-${file.name}`;
17    const { error } = await supabase.storage
18      .from('uploads')
19      .upload(fileName, file);
20
21    if (error) {
22      console.error('Upload failed:', error.message);
23      return;
24    }
25
26    const { data } = supabase.storage
27      .from('uploads')
28      .getPublicUrl(fileName);
29
30    setUploadedUrl(data.publicUrl);
31  }
32
33  return (
34    <div className="p-6 space-y-6">
35      {/* Static asset from /public */}
36      <img src={staticLogo} alt="Logo" className="h-12" />
37
38      {/* User upload to Supabase Storage */}
39      <div>
40        <label className="block text-sm font-medium mb-2">
41          Upload an image
42        </label>
43        <input type="file" accept="image/*" onChange={handleUpload} />
44      </div>
45
46      {uploadedUrl && (
47        <img
48          src={uploadedUrl}
49          alt="Uploaded"
50          className="max-w-md rounded-lg shadow"
51        />
52      )}
53    </div>
54  );
55}

Best practices to prevent this

• Place static assets in /public and reference them with root-relative paths starting with / — this works on all routes
• Use GitHub uploads for binary files (images, fonts, PDFs) that Lovable's AI cannot create from code
• Use Supabase Storage for user-uploaded content and large files over 5 MB to keep the repository small
• Organize /public with subfolders (/public/images, /public/fonts) to keep assets manageable
• Use JavaScript imports (import logo from '@/assets/logo.svg') for small component-specific assets in /src
• Optimize images before uploading — compress PNGs with TinyPNG and use WebP format where possible for faster loading
• Avoid spaces and special characters in filenames — use hyphens (hero-banner.jpg) for compatibility across platforms

Still stuck?

Copy one of these prompts to get a personalized, step-by-step explanation.

Related error patterns