Good for one clear asset
Single-file uploads fit avatars, documents, one hero image, or any workflow where one field maps to one uploaded file.
Upload a Single File
Upload one file to your server with a workflow that keeps destination, naming, and later usage predictable.
Introduction
Section titled “Introduction”In Demo Projects HQ, the Files page turns single-file upload into a concrete workflow: choose the file, post it to /api/files/upload, and keep the stored reference predictable for later listing and download. The important part is not just selecting a file. It is deciding where the file goes, how the saved name is handled, and how the rest of the page or data workflow refers back to that uploaded asset afterwards.
Still needs a destination model
Even one file should have a predictable folder, naming rule, and later reference in the application.
Treat the upload as part of a full data workflow, not an isolated input.
Decide the upload destination before you connect the form.
Keep the stored file reference predictable for later display or download.
Make replacement behavior explicit when users upload a newer file later.
Keep the single-file workflow explicit
Section titled “Keep the single-file workflow explicit”One file is simple only when the rest of the workflow stays clear.
Pick the right destination
Section titled “Pick the right destination”A single uploaded file should land in a folder that matches its purpose. When files are mixed into arbitrary locations, later pages and server actions become harder to reason about.
Stable organization
A predictable destination makes later linking, cleanup, and publishing easier.
Treat the uploaded file reference as data
Section titled “Treat the uploaded file reference as data”The uploaded filename or path usually needs to become part of a saved record, page state, or later display binding. Make that handoff explicit instead of assuming the upload alone completed the feature.
Upload plus persistence
The system still needs a trustworthy reference after the transfer finishes.
Plan for replacement and cleanup
Section titled “Plan for replacement and cleanup”A single-file field often implies later replacement. Decide whether new uploads overwrite, version, or leave old files behind so the behavior stays understandable over time.
Lifecycle matters
Uploads should have a clear story for first use, replacement, and cleanup.
Next steps
Section titled “Next steps”Single-file uploads are the foundation. From here, the workflow usually expands in one of two directions: richer upload UX, or stronger persistence rules for the uploaded filename.