Assets

Assets are files uploaded to the platform's blob storage. They are managed from Admin > Assets and can also be uploaded inline when editing other records (e.g., product images, article featured images).

Uploading Files

Files can be uploaded in two ways:

  • Direct upload - Use the Assets table in the Manager to upload standalone files. Each asset has a name, description, file attachment, and status.
  • Inline upload - When editing a product, article, slide, or other record, file fields have built-in upload controls. These files are attached directly to the record rather than managed as standalone assets.

Uploaded files are stored in Vercel Blob Storage and served through a CDN for fast global delivery.

Supported Formats

The platform accepts most common file types. Each file field may specify additional constraints via its accept validation. Common supported types include:

  • Images - JPEG, PNG, WebP, GIF, SVG
  • Fonts - WOFF, WOFF2, TTF, OTF (for custom typography in Site Config)
  • Documents - PDF
  • Icons - ICO, SVG, PNG (for favicons)
  • Video - MP4, WebM (where configured)

Size Limits

Each file field defines a maximum upload size via its mbLimit validation. Typical limits:

  • Avatars - 1 MB
  • Product images - 2-5 MB per image
  • Slide images - 5 MB
  • Logos & favicons - 2 MB
  • Font files - 2 MB

The platform validates file size before upload. When an image exceeds the limit (or the wrong shape — see Smart Image Uploads below), the upload modal offers a one-click in-browser fix instead of rejecting outright. Non-image files exceeding the limit are still rejected with a validation error.

Smart Image Uploads

JPEG and PNG images that fail the field's size or dimension validations can be auto-transformed in the browser, no external tools required. The upload modal shows side-by-side Before → After previews — including pixel dimensions and file size — so the editor can confirm the result before committing.

What can be auto-fixed

  • Oversized files (mbLimit) — quality and dimensions are reduced iteratively until the image fits under the limit.
  • Wrong aspect ratio (aspectRatio) — the image is center-cropped to the required ratio (e.g., 1:1 avatars, 1200:630 social cards).
  • Wrong pixel dimensions (pixelDims) — the image is center-cropped and scaled to the exact required dimensions.
  • Combinations of the above — crop and resize run together so a single 4032×3024 phone photo can become a 1200×630 OG image under 2 MB in one step.

Limitations

  • Only JPEG and PNG are transformable. GIF, SVG, HEIC, AVIF and other formats fall through to the standard validation error.
  • Cropping is automatic and centered on the source image. There is no draggable crop frame — for off-center subjects, the editor should crop manually before uploading.
  • Source MIME is preserved (PNGs keep alpha, JPEGs stay JPEGs). Format conversion (e.g. to WebP) is not performed.
The transform runs entirely in the browser — original files are never sent to the server before processing. This keeps oversized phone photos from blowing past Vercel's 4.5 MB request body limit.

Private File Storage

Assets support private visibility for files that should not be publicly accessible. When an asset's visibility is set to private, the file is uploaded to a separate private blob store and cannot be accessed via a direct URL.

How It Works

Private files are stored on Vercel Blob with private access. The CDN blocks all direct requests to private blob URLs. Instead, files are served through an authenticated server-side proxy that verifies the user's session and checks per-asset permissions before streaming the file.

Visibility Options

  • Public (default) - Files are stored in the standard public blob store and accessible to anyone with the URL.
  • Private - Files are stored in the private blob store. Only authenticated users who pass the asset's permission checks can access them.

Access Restrictions

When an asset is private, you can further restrict who can view it:

  • Uploader Only - Only the user who uploaded the file can access it. Useful for personal documents or submissions.
  • Allowed Roles - Restrict access to specific roles from your RBAC system. For example, only users with the editor or manager role can view the file. This field is hidden when Uploader Only is enabled since it would not apply.
Super users always have access to all private assets regardless of these settings. If neither restriction is configured, any signed-in user can access the private file.

Setup

Private file storage requires a separate private Vercel Blob store for each environment (development and production). See the README setup guide for instructions on creating private blob stores and configuring the BLOB_PRIVATE_READ_WRITE_TOKEN environment variable.

Placeholders & Fallbacks

The platform uses configurable fallback images when no file has been uploaded. These are set in Site Config > Placeholders and include defaults for missing avatars, product images, and hero banners. This ensures the site never displays broken image links.

API Access

File and image fields are read-only via the external API. You can read file URLs from records but cannot upload files through the API. All file uploads must go through the CMS Manager.