A simple and effective JavaScript library to interact with the Cloudflare Image API. This wrapper simplifies tasks such as uploading, listing, and managing images in your Cloudflare account.
While this library covers a broad range of Cloudflare Image API functionalities, there are certain features not included. These features are more efficiently managed directly through the Cloudflare Dashboard rather than through code.
- Image Uploads: Upload images directly from URLs or files.
- Image Management: List images, delete images, and update image metadata.
- Image Retrieval: Retrieve details about specific images and download them.
- Batch Requests: Supports batch token management for efficient API usage.
- Custom ID Validation: Includes methods to validate and handle custom IDs.
- UUID Encoding/Decoding: Encode UUIDs to Base64 and decode them back.
Please note that this tool is designed to be used in a Node.js environment only. Due to CORS (Cross-Origin Resource Sharing) restrictions, the Cloudflare Image API cannot be directly accessed from web browsers.
Install the library using npm:
npm install zod cloudflare-images-kitFirst, configure your Cloudflare account details:
import CloudflareImages from "cloudflare-images-kit";
const cloudflareImages = new CloudflareImages({
accountId: process.env.ACCOUNT_ID,
apiKey: process.env.API_KEY,
});const valid = cloudflareImages.isValidCustomId("example-id-123"); // BooleanThis function will throw an error if the custom ID:
- Is an empty string.
- Starts or ends with a slash.
- Is a full UUIDv4.
- Exceeds the maximum length of 1024 characters.
The encodeUUID and decodeUUID functions provide utilities for encoding a UUID to a Base64 string and decoding it back to a UUID format. Note that UUIDs cannot be used as custom IDs directly in Cloudflare due to their format restrictions.
const uuid = uuidv4();
const encoded = cloudflareImages.encodeUUID(uuid); // Outputs the Base64 encoded version of the UUID
const decoded = cloudflareImages.decodeUUID(encoded); // Outputs the original UUIDYou can upload images directly from URLs or from files using one of the following methods:
To upload an image from a URL, use the uploadImage method. You can optionally specify a custom ID, metadata, and whether to require signed URLs for access:
async () => {
const imageUrl = "https://picsum.photos/id/237/1280/720";
const customId = cloudflareImages.encodeUUID(uuidv4()); // Optional
const metadata = { key1: "value1", key2: "value2" }; // Optional
const requireSignedURLs = false; // Optional
const res = await cloudflareImages.uploadImage(
imageUrl,
customId,
metadata,
requireSignedURLs
);
};To upload an image from a file, use the uploadImageWithFile method.
async () => {
const customId = cloudflareImages.encodeUUID(uuidv4()); // Optional
const metadata = { key1: "value1", key2: "value2" }; // Optional
const requireSignedURLs = false; // Optional
const res = await cloudflareImages.uploadImageWithFile(
file, // Image File
customId,
metadata,
requireSignedURLs
);
};To upload an image from a buffer, use the uploadImageWithBuffer method.
async () => {
const customId = cloudflareImages.encodeUUID(uuidv4()); // Optional
const metadata = { key1: "value1", key2: "value2" }; // Optional
const requireSignedURLs = false; // Optional
const res = await cloudflareImages.uploadImageWithBuffer(
buffer, // Image Buffer
"image.jpg", // Image Filename
customId,
metadata,
requireSignedURLs
);
};For managing images, you can list, update, or delete images as follows:
async () => {
const res = await cloudflareImages.listImages();
};async () => {
const images = await cloudflareImages.getFullListImages();
};async () => {
const imageId = "your-image-id";
const metadata = { key1: "new-value1", key2: "new-value2" }; // New metadata
const requireSignedURLs = false; // Optional
const res = await cloudflareImages.updateImage(
imageId,
metadata,
requireSignedURLs
);
};async () => {
const imageId = "your-image-id";
const res = await cloudflareImages.deleteImage(imageId);
};async () => {
const imageId = "your-image-id";
const res = await cloudflareImages.getImageDetails(imageId);
};If you need to download the original image (as a Blob object), use the getBaseImage method:
async () => {
const imageId = "your-image-id";
const blob = await cloudflareImages.getBaseImage(imageId);
};For efficient management of large numbers of requests, the library supports batch operations. You can refresh the batch token and perform batch operations like uploading, updating, or deleting images:
async () => {
const success = await cloudflareImages.refreshBatchToken();
if (success) {
// Batch operations turn on, 200 requests per batch
// Batch operations:
// uploadImage
// uploadImageWithFile
// uploadImageWithBuffer
// updateImage
// getImageDetails
// deleteImage
const promises = Array.from({ length: 200 }, () =>
cloudflareImages.uploadImage(
"https://picsum.photos/id/237/1280/720",
cloudflareImages.encodeUUID(uuidv4())
)
);
await Promise.all(promises);
}
};You can retrieve your Cloudflare Image API usage statistics, including the allowed and current upload counts:
async () => {
const res = await cloudflareImages.getUsageStats();
};For more detailed examples and usage patterns, you can refer to the /demo/index.ts file in the repository.
Contributions are welcome! Please fork the repository and submit pull requests with your proposed changes. For major changes, please open an issue first to discuss what you would like to change.
This project is licensed under the MIT License - see the LICENSE file for details.
If you have any questions or need support with the library, please open an issue in the repository.