FileUploading

Upload and manage files in cloud storage, with optional image compression.

More information about the module's user interface https://doc.oneentry.cloud/docs/attributes/types/#File (opens in a new tab)

---

The FileUploading module uploads, retrieves and deletes files in OneEntry cloud storage: images, PDFs, videos, documents, any file type. You upload a file once; OneEntry stores it and returns a download link. Pass compress: true to compress images.

Quickstart

Initialize the module from defineOneEntry:

const {  } = defineOneEntry(
  , {
    
  }
);

Upload a file and read the returned download link:

// upload() resolves to an array of uploaded files (IUploadingReturn[]).
const uploaded = await FileUploading.upload(file, {
  type: "image",
  entity: "product",
  id: 123,
  compress: true,
});

if (!Array.isArray(uploaded)) {
  throw new Error(uploaded.message); // IError: the upload was rejected
}

const { filename, downloadLink, size } = uploaded[0];
console.log(downloadLink); // use in <img>, <a>, <video>

Later, delete it by the filename from the upload result, with the same type, entity and id:

await FileUploading.delete(filename, { type: "image", entity: "product", id: 123 });

How storage works

When you upload a File or Blob, OneEntry stores it in cloud storage, organized by type → id → entity under a generated file name (the original name is not kept), and returns a permanent CDN link in downloadLink. The CDN serves files from servers close to your users. Images are compressed only when you pass compress: true: JPG and PNG files are re-encoded as WebP and get smaller, but keep their original extension and contentType (a compressed photo.jpg is WebP inside). The image is not resized. Browsers display such files normally; if your code checks the format by extension or contentType, keep this in mind.

Files stay in storage until you remove them with FileUploading.delete(). Deleting a product or page in the admin panel removes some of the files stored for it, but not all: uploads that no attribute references anymore and files in other folders stay in storage. Clean up unused files explicitly.

Supported file types

Any file type is accepted. With compress: true, JPG and PNG images are compressed; other files are stored as is.

Category	File Types	Compression
Images	JPG, PNG	With compress: true (re-encoded as WebP)
Images	GIF, SVG	No (stored as-is)
Documents	PDF, DOC, DOCX, XLS, XLSX	No (stored as-is)
Videos	MP4, MOV, AVI, WebM	No (stored as-is)
Archives	ZIP, RAR, TAR, GZ	No (stored as-is)
Other	Any file type	No (stored as-is)

The maximum file size depends on your OneEntry plan limits.

Uploading

upload(file, fileQuery) takes the file and a required query object that says where to store it:

await FileUploading.upload(file, {
  type: 'image',         // storage folder, required (any string)
  entity: 'product',     // storage folder, required (any string)
  id: 123,               // entity ID, required
  compress: true,        // compress images (optional)
});

• file: the File or Blob to upload (from a file input or drag and drop).
• type, entity, id: the storage folder, type/id/entity. type and entity are free-form strings (page, product, editor are examples, not a fixed enum); id is the ID of the entity the file belongs to. All three are required; the API rejects an upload with 400 if any of them is missing.
• compress: enables image compression. Turn it on for web images.

Image optimization

Pass compress: true to compress images on upload. The upload endpoint doesn't resize images: the SDK type accepts width and height, but the API doesn't use them, so images keep their original dimensions.

Upload response

upload() resolves to an array of IUploadingReturn. Each item has:

{
  filename: "files/project/image/123/product/3f2c9a1e-7b4d-4c1a-9e2f-5d6b8a0c1e4f.jpg", // path in storage
  downloadLink: "https://your-project.oneentry.cloud/cloud-static/files/project/image/123/product/3f2c9a1e-7b4d-4c1a-9e2f-5d6b8a0c1e4f.jpg", // download link
  size: 204800,              // file size in bytes
  contentType: "image/jpeg", // MIME type
}

Use downloadLink in <img>, <a> and <video> tags. Save filename: you need it to delete the file later. size is the file size in bytes.

The SDK can't list the files uploaded for an entity. Keep track of the filename values returned by upload() (for example, in your database) to manage files later.

Deleting files

Pass the file name first, then the same type, entity and id that were used for the upload. Without any of them, the API responds with 400 and the file stays in storage. You can pass either the full filename from the upload result or just the file name.

await FileUploading.delete('3f2c9a1e-7b4d-4c1a-9e2f-5d6b8a0c1e4f.jpg', {
  type: 'image',
  entity: 'product',
  id: productId,
});

Retrieving a file

getFile(id, type, entity, filename, template?) resolves to a raw Response, not parsed JSON. A missing file also resolves to a Response (status 404), so check response.ok, then call .blob(), .arrayBuffer() or a similar method.

Building a File from a URL

createFileFromUrl(url, filename, mimeType?) fetches a remote resource and resolves to a File, for example to re-upload an existing remote image. It doesn't check the HTTP status, so a failed request still produces a File with the error body.

---

Methods

Method	What It Does	When to Use
upload()	Upload file to cloud storage	User uploads image, document
getFile()	Fetch the file (raw Response)	Download a stored file
delete()	Delete file from storage	Remove old files
createFileFromUrl()	Build a File from a remote URL	Import a remote image before upload
searchFileContent()	Search the text of attached files	Full-text search in PDFs and documents

All methods are public: no user authorization is required. With the default errors.isShell: true, the methods resolve to an IError instead of throwing, so check the result (for example, 'statusCode' in result). With errors.isShell: false they throw. See Errors.

---

Related

• Products: upload product images
• FormsData: file fields are uploaded through this module on submit
• Users: upload user profile photos
• Pages: upload page content files

---