Uploading Images & Videos

Astro Cloudinary provides a seamless way to integrate Cloudinary’s powerful upload capabilities into your Astro project. This guide will show you how to use the CldUploadWidget component to add upload functionality to your application.

CldUploadWidget Component

The CldUploadWidget component is a wrapper around Cloudinary’s Upload Widget, specifically optimized for Astro projects. It allows you to easily add upload functionality with minimal configuration.

Basic Usage

Here’s a simple example of how to use the CldUploadWidget:

import { CldUploadWidget } from 'astro-cloudinary';

<CldUploadWidget uploadPreset="<Your Upload Preset>">
  <button>Upload to Cloudinary</button>
</CldUploadWidget>

Replace <Your Upload Preset> with your actual Cloudinary upload preset.

Live Example

Here’s a live example of the CldUploadWidget in action:

Signed Uploads

For enhanced security, you can use signed uploads. This requires setting up a server-side endpoint to sign the upload parameters.

import { CldUploadWidget } from 'astro-cloudinary';

<CldUploadWidget
  uploadPreset="<Your Upload Preset>"
  signatureEndpoint="/api/sign-cloudinary-params"
>
  <button>Secure Upload</button>
</CldUploadWidget>

You’ll need to create an API route to handle the signature. Here’s an example of how your API route might look:

import type { APIRoute } from "astro";
import { v2 as cloudinary } from "cloudinary";

export const post: APIRoute = async ({ request }) => {
  const body = await request.json();
  const { paramsToSign } = body;
  const signature = cloudinary.utils.api_sign_request(
    paramsToSign,
    process.env.CLOUDINARY_API_SECRET
  );
  return new Response(JSON.stringify({ signature }), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
    },
  });
};

Configuration Options

The CldUploadWidget component accepts several props for customization:

uploadPreset: (Required) Your Cloudinary upload preset
signatureEndpoint: (Optional) Endpoint for signed uploads
onUpload: Callback function triggered after a successful upload
onError: Callback function triggered if an error occurs during upload

For a full list of options, refer to the CldUploadWidget Configuration page.

Best Practices and Tips

Always use upload presets to control what can be uploaded to your Cloudinary account.
Implement signed uploads for enhanced security, especially in production environments.
Use the onUpload callback to handle successful uploads, such as displaying the uploaded image or updating your application state.
Customize the upload widget to match your application’s design using CSS.
Consider implementing upload restrictions (file types, sizes) using Cloudinary’s upload presets.