phoenix-uploads

Phoenix File Uploads

RULES — Follow these with no exceptions

⚠️ priv/static/uploads is a DEV-ONLY pattern. In a release/container, priv/static is replaced on every deploy — user uploads are silently lost, and runtime files are never in the digest manifest. In production use object storage (S3 via :external uploads) or a configured writable directory outside the release (e.g. a mounted volume), served by a dedicated Plug.Static.

1. Default to manual uploads — auto_upload: true works with submit, but entries must be fully uploaded before you consume them; prefer manual uploads unless you need incremental upload UX
2. Always add upload directory to static_paths() — files won't be accessible without this
3. Handle upload errors — display error_to_string/1 output in templates
4. Create upload directories with File.mkdir_p! before saving files
5. Generate unique filenames — prevent collisions and path traversal attacks
6. Validate file types server-side — never trust client MIME types
7. If static_paths() changes don't take effect, restart the server — the code reloader usually recompiles the endpoint on the next request

---

Upload Configuration

Manual Upload (Recommended for Most Cases)

allow_upload(:upload_name,
  accept: ~w(.jpg .jpeg .png .pdf),
  max_entries: 10,
  max_file_size: 10_000_000
)

Template Requirements:

• Form with phx-submit event
• Submit button to trigger upload
• <.live_file_input> component
• Progress indicators

Auto Upload (Advanced - Use Sparingly)

Only use auto_upload: true when:

• Files should upload immediately on selection
• You have handle_progress/3 callback
• You consume entries outside form submission

auto_upload: true works with submit, but entries must be fully uploaded before you consume them — check entry.done? / rely on consume_uploaded_entries only after progress completes. Default to manual uploads unless you need incremental upload UX.