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 Organization

Files are organized by entity type:

Entity Type	Description	Example
product	Product images/files	Product gallery photos
page	Page content files	Hero images, backgrounds
block	Block content files	Banner images, icons
user	User uploaded files	Profile photos, documents
form	Form attachments	Contact form files
general	Miscellaneous files	Logos, favicons

File Types Supported

Upload any file type:

Category	File Types	Auto-Optimization
Images	JPG, PNG, GIF, WebP, SVG	✅ Yes (resize, compress)
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)

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

1. 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)

2. Upload Response

After uploading, you get:

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

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)

3. File Organization Best Practices

Organize files by entity Type

4. Image Optimization Options

Control how images are optimized:

Option	What It Does	Example
width	Max width (maintains aspect ratio)	width: 1920
height	Max height (maintains aspect ratio)	height: 1080
compress	Reduce file size	compress: true

Aspect ratio is preserved:

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

5. 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

Method	What It Does	When to Use
upload()	Upload file to cloud storage	User uploads image, document
getFile()	Get file info (size, type, URL)	Check if file exists
delete()	Delete file from storage	Remove old files

❓ Common Questions (FAQ)

Q: What file types can I upload?

A: 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.

Q: What's the maximum file size?

A: 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.

Q: Are files stored permanently?

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

Important: Clean up unused files to save storage space.

Q: Can I upload files from frontend (browser)?

A: Yes! Use file input or drag & drop

Q: How do I validate files before upload?

A: Check file type and size

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

A: 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

Q: How do I handle upload errors?

A: Always use try/catch

Q: Can I upload files to CDN directly?

A: 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.

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

A: Files remain in storage even if entity is deleted.

Best practice: Delete files before deleting entity:

Q: Can I resize images to exact dimensions?

A: 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

Do's:

• ✅ Validate file type and size before upload
• ✅ Use descriptive entity types (product, user, page)
• ✅ 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

Don'ts:

• ❌ Upload files without validation
• ❌ Upload sensitive/private data
• ❌ Forget to delete old files when replacing
• ❌ Use generic entity type for everything
• ❌ Upload huge files (compress first)
• ❌ Ignore error handling
• ❌ Lose track of filenames (can't delete later)
• ❌ Upload files synchronously (use async/await)

---

Definition of the FileUploading module

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

---

🔗 Related Documentation

• Products Module - Upload product images
• Users Module - Upload user profile photos
• Pages Module - Upload page content files
• Blocks Module - Upload block content files

---