Skip to main content

Introduction

Upload and manage files in cloud storage with automatic optimization.

More information about the module's user interface https://doc.oneentry.cloud/docs/attributes/types/#File

🎯 What does this module do?​

The FileUploading module lets you upload, retrieve, and delete files in OneEntry cloud storage - images, PDFs, videos, documents, any file type - with automatic image optimization and CDN delivery.

Think of it as your cloud storage manager - you upload files once, and OneEntry stores them, optimizes images automatically, and serves them fast via CDN.

🚀 Quickstart​

Initialize the module from defineOneEntry:


const { FileUploading } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Upload a file and read the returned download link:

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

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

Later, delete it by filename (the entity/id resolve the storage folder):

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

✨ Key Concepts​

What is File Uploading?​

File uploading is storing files in cloud storage and getting a permanent CDN link back:

  • Upload - send a File or Blob to OneEntry cloud
  • Storage - files are stored, organized by entity → id → filename
  • CDN - fast delivery from servers near users
  • Optimization - images can be auto-compressed and resized
  • URL - the response's downloadLink is the permanent link

File types supported​

Any file type is accepted. Only images are auto-optimized; everything else is stored as-is.

CategoryFile TypesAuto-Optimization
ImagesJPG, PNG, GIF, WebP, SVGYes (resize, compress)
DocumentsPDF, DOC, DOCX, XLS, XLSXNo (stored as-is)
VideosMP4, MOV, AVI, WebMNo (stored as-is)
ArchivesZIP, RAR, TAR, GZNo (stored as-is)
OtherAny file typeNo (stored as-is)

📋 What You Need to Know​

Upload parameters​

upload(file, fileQuery?) takes the file plus an optional query object:

await FileUploading.upload(file, {
  entity: 'product',     // Storage folder name (optional, any string)
  id: 123,               // Entity ID (optional)
  type: 'image',         // Folder/type hint (optional, any string)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true,        // Compress images (optional)
});
  • file — the File or Blob to upload (from an input or drag-drop)
  • entity — free-form folder name in storage (e.g. product, page, user, editor — examples, not a fixed enum)
  • id — entity ID to associate the file with
  • type — free-form folder/type hint string
  • width / height — max dimensions for images (aspect ratio is preserved)
  • compress — enable image compression

Upload response​

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

{
  filename: "uploads/abc123-photo.jpg",      // Filename with relative path
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size in bytes
  contentType: "image/png",                  // MIME type
}
  • downloadLink — use this URL in <img>, <a>, <video> tags
  • filename — save it to delete the file later
  • size — file size in bytes

Image optimization​

For images you can pass width, height, and compress. Aspect ratio is always preserved — the image is resized to fit within the given bounds, never stretched.

Deleting files​

Pass the filename first; the entity/id/type live in the optional query object that resolves the storage folder:

await FileUploading.delete('abc123-photo.jpg', {
  entity: 'product',
  id: productId,
});

Retrieving a file​

getFile(id, type, entity, filename, template?) returns a raw Response object (not parsed JSON) — call .blob(), .arrayBuffer(), etc. on it as needed.

Building a File from a URL​

createFileFromUrl(url, filename, mimeType?) fetches a remote resource and returns a browser File, handy for re-uploading an existing remote image.

📊 Quick Reference Table - Methods​

MethodWhat It DoesWhen to Use
upload()Upload file to cloud storageUser uploads image, document
getFile()Fetch the file (raw Response)Download a stored file
delete()Delete file from storageRemove old files
createFileFromUrl()Build a File from a remote URLImport a remote image before upload

All methods are public — no user authorization required.

❓ Common Questions (FAQ)​

What file types can I upload?​

Any file type. Only images are auto-optimized (resize/compress); other files are stored as-is.

What's the maximum file size?​

It depends on your OneEntry plan limits. Optimize images before upload to keep sizes down.

Are files stored permanently?​

Yes — files stay until you remove them with FileUploading.delete(). Files remain in storage even if the related entity is deleted, so clean them up explicitly.

Can I get a list of all uploaded files for an entity?​

Not directly via this SDK. Track the filename values you get back from upload() (e.g. save them in your database) to manage files later.

Can I resize images to exact dimensions?​

No — aspect ratio is always preserved. width/height define a bounding box the image is fit within, preventing distortion.

🎓 Best Practices​

  • Validate file type and size before calling upload().
  • Pass entity / id so files are organized by entity in storage.
  • Enable compress for web images.
  • Save the returned filename so you can delete() the file later.
  • Clean up unused files explicitly — they survive entity deletion.
  • Handle upload errors with try/catch and check the IError return shape.

🔗 Related Documentation​