Skip to main content

Introduction

Upload and manage files in cloud storage with automatic optimization.

🎯 What does this module do?​

The FileUploading module lets you upload, retrieve, and delete files in OneEntry cloud storage - images, PDFs, videos, documents, and any file type with automatic 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.

📖 Simple Explanation​

Imagine you're building an app where users can:

  • 📸 Upload profile photos - auto-resize and optimize
  • 📄 Upload documents - store PDFs, DOCs safely
  • 🖼️ Upload product images - multiple images per product
  • 🎥 Upload videos - store and stream video content
  • 📎 Upload attachments - any file type

Instead of managing your own storage:

  • ✅ Upload files to OneEntry cloud
  • ✅ Automatic image optimization (resize, compress)
  • ✅ Fast CDN delivery worldwide
  • ✅ Organize by entity type (product, user, page)
  • ✅ Get download URLs instantly
  • ✅ Delete files when no longer needed

Real-world example:

Without FileUploading (manual):
- Set up AWS S3 bucket ❌
- Configure CDN ❌
- Write image optimization code ❌
- Manage file permissions ❌
- Generate signed URLs ❌

With FileUploading (automatic):
- Upload file → Get download URL ✅
- Images auto-optimized ✅
- CDN delivery built-in ✅
- Easy file management ✅

✨ Key Concepts​

What is File Uploading?​

File uploading is storing files in cloud storage:

  • Upload - Send file to OneEntry cloud
  • Storage - Files stored securely in cloud
  • CDN - Fast delivery from servers near users
  • Optimization - Images auto-compressed and resized
  • URL - Get permanent download link

File Types Supported​

Upload any file type:

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)

Image Optimization​

When uploading images, OneEntry can:

  • 📐 Resize - Reduce dimensions (e.g., max 1920px width)
  • 🗜️ Compress - Reduce file size (smaller, faster)
  • 🖼️ Format - Convert to optimal format (WebP)
  • 📱 Responsive - Create multiple sizes

Example:

Original: 5MB, 4000x3000px
↓ (auto-optimize)
Optimized: 200KB, 1920x1440px

📋 What You Need to Know​

Upload Parameters​

When uploading files, you can specify:

await FileUploading.upload(file, {
  entity: 'product',     // Entity type (required)
  id: 123,               // Entity ID (optional)
  type: 'image',         // File type hint (optional)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true         // Compress images (optional)
});

Parameters explained:

  • file - The file object (from input or drag-drop)
  • entity - Category: product, page, block, user, form, general
  • id - Entity ID to associate file with (e.g., product ID)
  • type - File type hint (usually auto-detected)
  • width - Max width in pixels (images only)
  • height - Max height in pixels (images only)
  • compress - Enable compression (images only)

Upload Response​

After uploading, you get:

{
  filename: "abc123-photo.jpg",              // Unique filename
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size (bytes)
}

Important fields:

  • downloadLink - Use this URL in <img>, <a>, <video> tags
  • filename - Save this to delete file later
  • size - File size in bytes (204800 bytes = 200KB)

File Organization Best Practices​

Organize files by entity Type

Image Optimization Options​

Control how images are optimized:

OptionWhat It DoesExample
widthMax width (maintains aspect ratio)width: 1920
heightMax height (maintains aspect ratio)height: 1080
compressReduce file sizecompress: true

Aspect ratio is preserved:

Original: 4000x3000 (4:3 ratio)
With width: 800
Result: 800x600 (still 4:3 ratio)

Deleting Files​

Always provide entity, id, and filename to delete:

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

Why all three? Files are organized by entity → id → filename.

📊 Quick Reference Table - Methods​

MethodWhat It DoesWhen to Use
upload()Upload file to cloud storageUser uploads image, document
getFile()Get file info (size, type, URL)Check if file exists
delete()Delete file from storageRemove old files

❓ Common Questions (FAQ)​

What file types can I upload?​

Any file type is supported:

  • Images: JPG, PNG, GIF, WebP, SVG, BMP, TIFF
  • Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT
  • Videos: MP4, MOV, AVI, WebM, MKV
  • Archives: ZIP, RAR, TAR, GZ
  • Other: Any file type

Only images are auto-optimized. Other files are stored as-is.

What's the maximum file size?​

Check your OneEntry plan limits. Typically:

  • Free plan: 5MB per file
  • Paid plans: 50MB - 100MB per file

Best practice: Optimize images before upload to reduce size.

Are files stored permanently?​

Yes, files are stored until you delete them manually using FileUploading.delete().

Important: Clean up unused files to save storage space.

Can I upload files from frontend (browser)?​

Yes! Use file input or drag & drop.

How do I validate files before upload?​

Check file type and size.

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

Not directly with this SDK. You need to:

  1. Track filenames when uploading (save to database)
  2. Use OneEntry Admin API to list files

Best practice: Save uploaded filenames in your database.

How do I handle upload errors?​

Always use try/catch.

Can I upload files to CDN directly?​

No, uploads go through OneEntry API, which:

  1. Validates file
  2. Optimizes images (if enabled)
  3. Stores in cloud
  4. Returns CDN URL

This ensures security and optimization.

What happens to files if I delete an entity (product, user)?​

Files remain in storage even if entity is deleted.

Best practice: Delete files before deleting entity.

Can I resize images to exact dimensions?​

No, aspect ratio is always preserved to prevent distortion.

How it works:

  • You set width: 800, height: 600
  • Image is resized to fit within 800x600
  • Aspect ratio is preserved

Example:

Original: 1000x500 (2:1 ratio)
With width: 800, height: 600
Result: 800x400 (still 2:1 ratio, fits within 800x600)

💡 Important Notes​

File Security​

Uploaded files are publicly accessible via CDN:

  • ✅ Great for images, public documents
  • ⚠️ Don't upload sensitive files (passwords, private data)

For private files:

  • Use OneEntry Admin API with authentication
  • Or implement your own access control

Storage Limits​

Monitor your storage usage:

  • Each plan has storage limits
  • Clean up unused files regularly
  • Compress images before upload

Image Optimization Tips​

For best results:

  • ✅ Upload high-quality originals (let OneEntry optimize)
  • ✅ Use compress: true for web images
  • ✅ Set appropriate dimensions (e.g., 1920px for hero images, 500px for thumbnails)
  • ❌ Don't upload already-compressed images (quality loss)

Recommended sizes:

  • Profile photos: 500x500
  • Product images: 1920x1920
  • Hero banners: 1920x1080
  • Thumbnails: 300x300

🎓 Best Practices​

  • Validate file type and size before upload
  • Associate files with entity IDs for organization
  • Enable compression for web images
  • Handle upload errors gracefully
  • Save filenames to delete files later
  • Clean up unused files regularly
  • Show upload progress to users

Definition of the FileUploading module​


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

🔗 Related Documentation​