Perché serve resource_type=raw per PDF e documenti Office?

Perché Cloudinary tratta di default i file come immagini; per file binari come PDF, Word o Excel occorre specificare esplicitamente resource_type=raw affinché vengano gestiti e serviti correttamente.

Un upload preset unsigned è sicuro da usare in produzione?

Può esserlo se configurato con attenzione: limitando dimensione massima, tipi di file ammessi e, se necessario, impostando restrizioni aggiuntive lato Cloudinary. Essendo pubblico, non offre lo stesso controllo di un upload firmato lato server.

Serve un backend per usare questo pattern?

No, l'obiettivo dello snippet è proprio evitare un backend dedicato, sfruttando l'endpoint di upload di Cloudinary direttamente dal browser con un preset unsigned.

← blog

JavaScript Cloudinary Zero backend Upload

Uploading files to Cloudinary with `resource_type: raw`

How to upload PDFs, Word docs, Excel files and other generic binary files to Cloudinary using an unsigned upload preset and resource_type=raw — fully client-side, no dedicated backend.

The problem

Cloudinary is great for images and video, but the default image type rejects generic binary files like PDFs or Office documents. To upload them you need to explicitly declare resource_type=raw in the upload endpoint URL.

Upload with FormData and fetch

upload.js

async function uploadFileRaw(file) {
  const fd = new FormData();
  fd.append('file', file);
  fd.append('upload_preset', 'NOME_PRESET'); // preset unsigned già configurato

  // resource_type=raw — obbligatorio per file non-immagine/video
  const res = await fetch(
    `https://api.cloudinary.com/v1_1/CLOUD_NAME/raw/upload`,
    { method: 'POST', body: fd }
  );

  const data = await res.json();
  if (!res.ok) throw new Error(data.error?.message || 'Upload fallito');

  return data.secure_url;
}

When to use it: chat attachments, internal document systems, any PWA upload without a dedicated backend — Cloudinary handles CDN, storage and public URLs automatically.

Configuring the unsigned preset

On Cloudinary, an unsigned upload preset allows direct client-side uploads without exposing the API secret. In the Cloudinary dashboard: Settings → Upload → Add upload preset, set Signing Mode: Unsigned and, critically, Resource type: Auto (not Image) — otherwise uploading a PDF returns a 400 error.

Warning: an unsigned upload preset is public — anyone who knows the preset name can upload files to your Cloudinary account. For public-facing use, set format and size limits in the preset, or switch to server-side signed uploads.

Sending documents in a Firebase + Cloudinary chat — full real-world case

→

When to use this Cloudinary upload pattern

This snippet shows how to upload binary files (PDF, Word, Excel) to Cloudinary using resource_type=raw and an unsigned upload preset, in vanilla JavaScript with no backend needed.

When to use it

You need to upload non-image documents (PDF, Word, Excel) to Cloudinary from a frontend without a dedicated server.

You want a direct browser upload without going through an intermediate backend, using an unsigned preset configured on the Cloudinary side.

You're quickly prototyping an upload feature without wanting to build a full server infrastructure.

When NOT to use it

You need to validate or process files before upload (e.g. antivirus scanning, conversion): a client-side unsigned preset doesn't allow server-side checks before upload.

You have strict security requirements for uploads: an unsigned preset is public by definition, so it needs to be carefully configured (size limits, allowed file types) on the Cloudinary side.

Alternatives

Signed uploads with a backend that generates the signature, when you need more control and security over the operation.

Official Cloudinary SDKs for specific frameworks (React, Vue) if the project already uses one of them.

Common mistakes

Forgetting to set resource_type=raw for non-image files: without this parameter, Cloudinary treats the file as an image and the upload can fail or behave unexpectedly.

Configuring an unsigned preset that's too permissive, with no limits on size or file type, exposing the endpoint to abuse.

Not handling upload errors (network, unsupported format), leaving the user with no feedback when something fails.

Frequently asked questions about uploading raw files to Cloudinary

Because Cloudinary treats files as images by default; for binary files like PDF, Word, or Excel, you need to explicitly specify resource_type=raw so they're handled and served correctly.

It can be, if carefully configured: limiting maximum size, allowed file types, and, if needed, setting additional restrictions on the Cloudinary side. Since it's public, it doesn't offer the same control as a server-side signed upload.

No, the whole point of this snippet is to avoid a dedicated backend, using Cloudinary's upload endpoint directly from the browser with an unsigned preset.

Uploading files to Cloudinary with resource_type: raw