Using the Public Folder

The public folder allows you to store static files that should be accessible in both preview and published sites without being processed by the bundler.

What is the Public Folder?

The /public folder is a special directory in your project where you can place static files that need to be accessible at runtime. Files in this folder are:

Copied to the root of your site (without the /public prefix)
Not processed or bundled by esbuild
Accessible in both preview mode and published sites
Perfect for assets like images, PDFs, text files, or any static content

How to Use It

1. Create the Public Folder

In your project, create a folder named /public at the root level (same level as your index.html).

2. Add Your Static Files

Place any files you want to serve statically in the /public folder. Common examples:

favicon.ico or favicon.png - Site icon
robots.txt - Search engine instructions
sitemap.xml - SEO sitemap
manifest.json - PWA manifest
sw.js - Service worker (not bundled by default)
terms.txt - Terms of service or privacy policy
Any images, PDFs, or downloadable files

3. Access the Files

Example 1: Fetch API (Dynamic Loading)

Load files dynamically using the Fetch API. For example, loading /public/terms.txt:

index.html

script.js

public/terms.txt

const btn = document.getElementById('loadBtn');
const output = document.getElementById('output');

btn.addEventListener('click', async () => {
  try {
    const response = await fetch('/terms.txt');
    const text = await response.text();
    output.textContent = text;
  } catch (error) {
    output.textContent = 'Error: ' + error.message;
  }
});

Click "Run in Playground" to try this example! Click the button to fetch and display the terms file from the /public folder.

Example 2: Direct HTML Links

Reference files directly in your HTML for static content:

index.html

style.css

public/favicon.png

public/logo.png

public/terms.txt

<!DOCTYPE html>
<html>
<head>
  <title>Public Folder - HTML Links</title>
  <link rel="icon" href="/favicon.png" type="image/png">
  <link rel="stylesheet" href="/style.css">
</head>
<body>
  <h1>Public Folder Files</h1>

  <div class="section">
    <h2>Downloadable Files</h2>
    <a href="/terms.txt" download>Download Terms of Service</a>
  </div>

  <div class="section">
    <h2>Images</h2>
    <img src="/logo.png" alt="Logo" class="logo">
  </div>

  <div class="section">
    <h2>Favicon</h2>
    <p>Check the browser tab - it should show the favicon!</p>
  </div>
</body>
</html>

This example shows various ways to use public folder files: favicon, downloadable link, and image.

Important Notes

Path Mapping

Files in /public are mapped to the root of your site. This means /public/terms.txt becomes accessible at /terms.txt (the /public prefix is removed).

Preview vs Production

The public folder works identically in both preview and published sites. The DistSaverPlugin automatically handles both environments:

Preview (local): Files are copied to /_dist_/ in the virtual file system for instant access
Published sites (production): Files are uploaded to S3 and served from the global CDN

No configuration needed! The bundler plugin detects production builds automatically and includes public files in both cases.

When to Use Public Folder

Use the public folder for:

Favicon - favicon.ico or favicon.png in the root
SEO files - robots.txt, sitemap.xml
PWA files - manifest.json, service workers
Downloadable content - PDFs, text files, documents
Static assets - Images, videos, fonts that need exact URLs
External references - Files referenced by third-party services

When NOT to Use Public Folder

Don't use the public folder for:

Images or assets imported in your code (use regular imports instead - they'll be optimized by the bundler)
JavaScript or CSS files (these should be bundled)
Files that need processing or transformation

Example: Terms of Service

A common use case is providing a terms of service or privacy policy as a downloadable text file:

Create /public/terms.txt in your project
Add your terms content to the file

In your HTML, add a link:

html

 <a href="/terms.txt" download>Download Terms</a>

When you publish, the file will be included automatically

Technical Details

The DistSaverPlugin in the bundler automatically handles public folder files in all environments:

Preview mode: Files are copied to /_dist_/ in the browser's virtual file system (VFS) and served by the service worker
Production builds: Files are included in buildResult.outputFiles and uploaded to S3 alongside your bundled code
Path mapping: The /public prefix is automatically removed (e.g., /public/favicon.ico becomes /favicon.ico)
Format preservation: Binary and text files maintain their format automatically

This automatic handling ensures files work identically in preview and production, eliminating the common "works locally but fails when published" issue.