---

name: bknd-file-upload description: Use when uploading files to Bknd storage. Covers MediaApi SDK methods (upload, uploadToEntity), REST endpoints, React integration with file inputs, progress tracking with XHR, browser upload patterns, and entity field attachments.

File Upload

Upload files to Bknd storage using the MediaApi SDK or REST endpoints.

Prerequisites

• Media module enabled in Bknd config
• Storage adapter configured (S3, R2, Cloudinary, or local)
• bknd package installed
• For entity uploads: target entity has media() field defined

When to Use UI Mode

• Admin panel > Media section > drag-and-drop upload
• Quick testing of storage configuration
• One-off file uploads without code

When to Use Code Mode

• Programmatic uploads from frontend
• Upload with progress tracking
• Attach files to entity records
• Custom upload UI components

Step-by-Step: UI Approach

Step 1: Open Admin Panel

Navigate to http://localhost:7654 (or your Bknd URL).

Step 2: Go to Media Section

Click "Media" in sidebar to access file management.

Step 3: Upload Files

• Drag files into the upload area, OR
• Click "Upload" button and select files

Step 4: Verify Upload

Files appear in the list with name, size, type, and date.

Step-by-Step: Code Approach

Basic File Upload

Copyimport { Api } from "bknd";

const api = new Api({ host: "http://localhost:7654" });

// From File object (browser)
const input = document.querySelector('input[type="file"]');
const file = input.files[0];

const { ok, data, error } = await api.media.upload(file);

if (ok) {
  console.log("Uploaded:", data.name);
  console.log("Size:", data.meta.size);
  console.log("Type:", data.meta.type);
}

Upload with Custom Filename

Copyconst { ok, data } = await api.media.upload(file, {
  filename: "custom-name.png",
});

Upload from URL

Copy// Direct URL string
const { ok, data } = await api.media.upload("https://example.com/image.png");

// Or from fetch Response
const response = await fetch("https://example.com/image.png");
const { ok, data } = await api.media.upload(response);

Upload to Entity Field

Attach file directly to an entity record:

Copy// Assumes "posts" entity has a media() field called "cover_image"
const { ok, data } = await api.media.uploadToEntity(
  "posts",           // entity name
  123,               // record ID
  "cover_image",     // field name
  file,
  { overwrite: true }  // replace existing file
);

if (ok) {
  console.log("File attached:", data.result.cover_image);
}

React Integration

Simple File Input

Copyfunction FileUpload({ onUploaded }) {
  const { api } = useApp();  // or your Api instance
  const [uploading, setUploading] = useState(false);
  const [error, setError] = useState(null);

  const handleChange = async (e) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setUploading(true);
    setError(null);

    const { ok, data, error } = await api.media.upload(file);

    setUploading(false);

    if (ok) {
      onUploaded(data);
    } else {
      setError(error?.message || "Upload failed");
    }
  };

  return (
    <div>
      <input
        type="file"
        onChange={handleChange}
        disabled={uploading}
      />
      {uploading && <span>Uploading...</span>}
      {error && <span style={{ color: "red" }}>{error}</span>}
    </div>
  );
}

Image Upload with Preview

Copyfunction ImageUpload({ value, onChange }) {
  const { api } = useApp();
  const [preview, setPreview] = useState(value);
  const [uploading, setUploading] = useState(false);

  const handleChange = async (e) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // Show local preview immediately
    const localUrl = URL.createObjectURL(file);
    setPreview(localUrl);

    setUploading(true);
    const { ok, data } = await api.media.upload(file);
    setUploading(false);

    if (ok) {
      // Clean up local preview
      URL.revokeObjectURL(localUrl);
      // Use server URL
      onChange(data.name);
    }
  };

  return (
    <div>
      {preview && (
        <img
          src={preview}
          alt="Preview"
          style={{ maxWidth: 200, opacity: uploading ? 0.5 : 1 }}
        />
      )}
      <input type="file" accept="image/*" onChange={handleChange} />
      {uploading && <span>Uploading...</span>}
    </div>
  );
}

Upload with Progress Tracking

For large files, use XHR for progress:

Copyfunction ProgressUpload({ onUploaded }) {
  const { api } = useApp();
  const [progress, setProgress] = useState(0);
  const [uploading, setUploading] = useState(false);

  const uploadWithProgress = (file) => {
    return new Promise((resolve, reject) => {
      const xhr = new XMLHttpRequest();
      const url = api.media.getFileUploadUrl({ path: file.name });

      xhr.upload.addEventListener("progress", (e) => {
        if (e.lengthComputable) {
          setProgress(Math.round((e.loaded / e.total) * 100));
        }
      });

      xhr.addEventListener("load", () => {
        if (xhr.status >= 200 && xhr.status < 300) {
          resolve(JSON.parse(xhr.responseText));
        } else {
          reject(new Error(xhr.statusText));
        }
      });

      xhr.addEventListener("error", () => reject(new Error("Upload failed")));

      xhr.open("POST", url);
      xhr.setRequestHeader("Content-Type", file.type);

      // Add auth if using header transport
      const token = api.getAuthState().token;
      if (token) {
        xhr.setRequestHeader("Authorization", `Bearer ${token}`);
      }

      xhr.send(file);
    });
  };

  const handleChange = async (e) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setUploading(true);
    setProgress(0);

    try {
      const result = await uploadWithProgress(file);
      onUploaded(result);
    } catch (err) {
      console.error("Upload failed:", err);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input type="file" onChange={handleChange} disabled={uploading} />
      {uploading && (
        <div>
          <progress value={progress} max={100} />
          <span>{progress}%</span>
        </div>
      )}
    </div>
  );
}

Avatar Upload Component

Complete avatar upload with entity attachment:

Copyfunction AvatarUpload({ userId, currentAvatar }) {
  const { api } = useApp();
  const [preview, setPreview] = useState(currentAvatar);
  const [uploading, setUploading] = useState(false);

  const handleChange = async (e) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // Validate image
    if (!file.type.startsWith("image/")) {
      alert("Please select an image file");
      return;
    }

    if (file.size > 5 * 1024 * 1024) {
      alert("Image must be under 5MB");
      return;
    }

    setPreview(URL.createObjectURL(file));
    setUploading(true);

    const { ok, data } = await api.media.uploadToEntity(
      "users",
      userId,
      "avatar",
      file,
      { overwrite: true }
    );

    setUploading(false);

    if (ok) {
      setPreview(data.result.avatar);
    }
  };

  return (
    <div>
      <img
        src={preview || "/default-avatar.png"}
        alt="Avatar"
        style={{
          width: 100,
          height: 100,
          borderRadius: "50%",
          opacity: uploading ? 0.5 : 1
        }}
      />
      <label>
        <input
          type="file"
          accept="image/*"
          onChange={handleChange}
          disabled={uploading}
          style={{ display: "none" }}
        />
        <button type="button" disabled={uploading}>
          {uploading ? "Uploading..." : "Change Avatar"}
        </button>
      </label>
    </div>
  );
}

REST API

Upload Endpoint

Copy# Basic upload (filename in path)
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @image.png \
  http://localhost:7654/api/media/upload/image.png

# Upload to entity field
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg \
  "http://localhost:7654/api/media/entity/users/123/avatar?overwrite=true"

Response Format

Copy{
  "name": "image.png",
  "meta": {
    "type": "image/png",
    "size": 24680,
    "width": 800,
    "height": 600
  },
  "etag": "abc123...",
  "state": {
    "name": "image.png",
    "path": "image.png"
  }
}

Entity Media Field

Define a media field to link files to records:

Copyimport { em, entity, text, media } from "bknd";

const schema = em({
  posts: entity("posts", {
    title: text(),
    cover_image: media(),  // Stores file reference
  }),

  users: entity("users", {
    name: text(),
    avatar: media(),
  }),
});

Media fields store the filename, not the file content.

Server-Side Upload

Upload files in Bknd server context (seeds, flows):

Copy// In seed function
export default defineConfig({
  options: {
    seed: async (ctx) => {
      const media = ctx.server?.modules.media;
      if (!media) return;

      // Upload from URL
      const response = await fetch("https://example.com/default-avatar.png");
      const buffer = await response.arrayBuffer();

      await media.adapter.putObject(
        "default-avatar.png",
        new Uint8Array(buffer)
      );
    },
  },
});

Handling Upload Response

Copyconst { ok, data, error } = await api.media.upload(file);

if (!ok) {
  // Handle error
  if (error?.status === 413) {
    console.error("File too large");
  } else if (error?.status === 401) {
    console.error("Not authenticated");
  } else if (error?.status === 403) {
    console.error("No upload permission");
  } else {
    console.error("Upload failed:", error?.message);
  }
  return;
}

// Success - use data
console.log("Filename:", data.name);
console.log("MIME type:", data.meta.type);
console.log("Size (bytes):", data.meta.size);

// For images
if (data.meta.width && data.meta.height) {
  console.log("Dimensions:", data.meta.width, "x", data.meta.height);
}

Common Pitfalls

File Too Large (413 Error)

Problem: Upload fails with 413 status.

Fix: Increase body_max_size in config:

Copyexport default defineConfig({
  media: {
    enabled: true,
    body_max_size: 50 * 1024 * 1024,  // 50MB
    adapter: { ... },
  },
});

Missing Content-Type Header

Problem: File uploaded with wrong MIME type.

Fix: Always set Content-Type in REST uploads:

Copy# WRONG - no content type
curl -X POST --data-binary @image.png .../upload/image.png

# CORRECT
curl -X POST \
  -H "Content-Type: image/png" \
  --data-binary @image.png \
  .../upload/image.png

SDK handles this automatically from File object.

CORS Errors

Problem: Browser blocks upload to S3.

Fix: Configure CORS on storage bucket (not Bknd):

Copy{
  "CORSRules": [{
    "AllowedOrigins": ["https://yourapp.com"],
    "AllowedMethods": ["GET", "PUT", "POST"],
    "AllowedHeaders": ["*"]
  }]
}

Auth Token Missing in XHR Upload

Problem: 401 error when using XHR progress upload.

Fix: Add Authorization header:

Copyconst token = api.getAuthState().token;
if (token) {
  xhr.setRequestHeader("Authorization", `Bearer ${token}`);
}

Media Field Not Defined

Problem: uploadToEntity fails with "field not found".

Fix: Ensure entity has media() field:

Copy// WRONG - no media field
posts: entity("posts", {
  title: text(),
  cover_image: text(),  // This is just a string
}),

// CORRECT
posts: entity("posts", {
  title: text(),
  cover_image: media(),  // Proper media field
}),

Memory Issues with Large Files

Problem: Browser crashes on large file upload.

Fix: Use streaming or chunked upload:

Copy// For very large files, consider chunked upload
// Bknd doesn't have native chunking, so use S3 presigned URLs
// or implement custom chunking endpoint

Verification

Test upload works correctly:

Copyasync function testUpload() {
  // 1. Check media enabled
  const { ok: listOk } = await api.media.listFiles();
  console.log("Media module enabled:", listOk);

  // 2. Test file upload
  const testFile = new File(["test"], "test.txt", { type: "text/plain" });
  const { ok, data, error } = await api.media.upload(testFile);
  console.log("Upload result:", ok ? data.name : error);

  // 3. Verify file exists
  const { data: files } = await api.media.listFiles();
  const exists = files.some(f => f.key === "test.txt");
  console.log("File in list:", exists);

  // 4. Clean up
  if (exists) {
    await api.media.deleteFile("test.txt");
    console.log("Test file deleted");
  }
}

DOs and DON'Ts

DO:

• Validate file type/size before upload
• Show upload progress for large files
• Handle all error cases (401, 403, 413)
• Use uploadToEntity for entity attachments
• Clean up object URLs after upload completes
• Set appropriate body_max_size limit

DON'T:

• Upload without auth when permissions require it
• Forget Content-Type header in REST uploads
• Store sensitive files without access control
• Allow unlimited file sizes in production
• Use local adapter in production

Related Skills

• bknd-storage-config - Configure storage backends
• bknd-serve-files - Serve uploaded files
• bknd-add-field - Add media field to entity
• bknd-crud-update - Update records with file references
• bknd-assign-permissions - Set media.create permission