Simple File Upload

This add-on is operated by Bitmapped Designs LLC

AI-augmented file uploads: alt-tags, face crop, background removal

Simple File Upload

Last updated July 30, 2025

Heroku Add-on Documentation

Simple File Upload is available as a Heroku add-on, making it easy to add file uploading capabilities to your Heroku applications. This guide covers installation, configuration, and management of Simple File Upload through Heroku.

What is Simple File Upload?

Simple File Upload is the easiest way to allow users to add files to your app. We handle all of the tooling surrounding file uploading for you. No cloud storage account needed.

How Does Simple File Upload Work with Heroku?

Simple File Upload loads as a web component via JavaScript. When your user adds a file, it is uploaded to the cloud and a URL that links to that file is returned.

Simple File Upload is specifically designed to work with Heroku’s ephemeral filesystem. Files are uploaded directly to the cloud from your user’s browser, without passing through your application. This is crucial on Heroku, because your app’s dynos have an ephemeral filesystem - all files that aren’t part of your app’s slug are lost whenever a dyno restarts or is replaced (this happens at least once daily).

Uploaded files are served behind a CDN for blazing fast performance. You can optionally use our resize API to dynamically serve files at any size.

Provisioning the Add-on

Simple File Upload can be attached to a Heroku application via the CLI:

$ heroku addons:create simple-file-upload
-----> Adding simple-file-upload to sharp-mountain-4005... done, v18 ($35/month)

A list of all plans available can be found here.

After you provision Simple File Upload, your public upload key will be available in your app’s configuration. You can access this key from your dashboard.

Accessing Your Dashboard

The Simple File Upload dashboard allows you to access your public upload key and see your current usage.

Access the dashboard via CLI:

$ heroku addons:open simple-file-upload
Opening simple-file-upload for sharp-mountain-4005

Or visit the Heroku Dashboard and select your application. Select Simple File Upload from the Add-ons menu.

Quick Start Guide
Step 1: Add JavaScript

Install the JavaScript library by adding this to the <head> of your site:

<script type="module" src="https://cdn.simplefileupload.com/simple-file-upload.latest.js"></script>

Add the web component wherever you want the uploader to appear:

<simple-file-upload
  public-key="YourPublicKey"
></simple-file-upload>
Step 2: Customize

Configure the uploader with these attributes:

  • multiple="true|false" - Show the multi-file uploader (default) or the single-file uploader
  • max-files="number" - Set maximum number of files
  • max-file-size="number" - Set maximum file size in bytes
Step 3: Handle Events

Listen for upload events and handle file data:

<script>
  // Listen for change events on the uploader
  document.addEventListener('DOMContentLoaded', function() {
    const uploader = document.querySelector('simple-file-upload');
    uploader.addEventListener('change', function(e) {
      console.log('Upload details:', e.detail);
      // Handle the uploaded files
      const files = e.detail.allFiles;
      // Your code here
    });
  });
</script>
Step 4: Serve Files

Resize your images on demand by adding query parameters:

  • Add ?w=width&h=height to any image URL (e.g., ?w=200&h=200 for a 200x200 image)
  • Use &fit=fill to control how images are cropped

Example: “`javascript // Original URL const { cdnUrl } = event.detail.allFiles[0];

// Resized to 200x200 const resized = cdnUrl + ‘?w=200&h=200’; ”`

Using React

For React applications, install the simple-file-upload-react package:

npm install simple-file-upload-react

Then import and use the component:

import { SimpleFileUpload } from 'simple-file-upload-react'

function MyComponent() {
  return (
    <SimpleFileUpload
      publicKey="YOUR_PUBLIC_KEY"
      onChange={(event) => console.log("Files changed:", event)}
    />
  )
}
AI Features
Background Removal API

Remove backgrounds from uploaded images programmatically. Perfect for user-generated content like profile photos or product images.

API Endpoint POST /api/v1/images/remove-background

Request Example (cURL) bash curl -X POST https://app.simplefileupload.com/api/v1/images/remove-background \ -H "Content-Type: application/json" \ -u YOUR_API_KEY:YOUR_SECRET \ -d '{ "url": "https://yoursubdomain.files-simplefileupload.com/path/to/image.jpg" }'

Response json { "data": { "id": "123", "type": "files", "attributes": { "original_url": "https://yoursubdomain.files-simplefileupload.com/original.jpg", "processed_url": "https://yoursubdomain.files-simplefileupload.com/original_no_bg.png", "filename": "original_no_bg.png", "tag": { "name": "removed-bg" } } } }

Important Notes: - Only works with images already uploaded to your Simple File Upload account - Processed images are automatically tagged with “removed-bg” - Basic plans include 20 background removals per month - Store API credentials securely - never expose them in client-side code

Alt-Text Generation

Automatically generate accessible alt-text for uploaded images using AI. This helps make your application more accessible to users with screen readers and improves SEO.

Enable Alt-Text Generation

Add the alt-text attribute to your web component:

<simple-file-upload
  public-key="YourPublicKey"
  alt-text
></simple-file-upload>

Listen for Alt-Text Events

const uploader = document.querySelector('simple-file-upload');

// Listen for alt-text generation
uploader.addEventListener('altTextGenerated', (event) => {
  const { fileId, altText, cdnUrl } = event.detail;

  // Update your image with the generated alt-text
  const img = document.querySelector(`img[data-file-id="${fileId}"]`);
  if (img) {
    img.alt = altText;
  }
});

React Example

function ImageUploader() {
  const [uploadedFiles, setUploadedFiles] = useState([]);

  const handleFileChange = (event) => {
    if (event.allFiles) {
      const files = event.allFiles.map(file => ({
        id: file.id,
        url: file.cdnUrl,
        altText: 'Processing image...'
      }));
      setUploadedFiles(files);
    }
  };

  const handleAltTextGenerated = (event) => {
    setUploadedFiles(prev => prev.map(img =>
      img.id === event.fileId
        ? { ...img, altText: event.altText }
        : img
    ));
  };

  return (
    <simple-file-upload
      public-key="YourPublicKey"
      onChange={handleFileChange}
      onAltTextGenerated={handleAltTextGenerated}
      alt-text
    />
  );
}

Best Practices: - Alt-text generation happens asynchronously (takes a few seconds) - Store generated alt-text in your database for future use - Provide meaningful fallback text while processing - Alt-text events are separate from upload events - match them using the fileId

Migrating Between Plans

Use the heroku addons:upgrade command to migrate to a new plan:

$ heroku addons:upgrade simple-file-upload:newplan
-----> Upgrading simple-file-upload:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: simple-file-upload:newplan
Removing the Add-on

You can remove Simple File Upload via the CLI:

Warning: This will destroy all associated data and cannot be undone! Download all your files before removing the add-on.

$ heroku addons:destroy simple-file-upload
-----> Removing simple-file-upload from sharp-mountain-4005... done, v20 ($35/month)

Before removing Simple File Upload, export your data by downloading all stored files.

Support

If you have any trouble, drop us a line at support@simplefileupload.com — we have the best customer support around.

Questions about direct uploads, file storage, or need help adding the upload widget? Book a time to talk with an uploading engineer.

Feedback

Log in to submit feedback.