npmpackage.info

Gathering detailed insights and metrics for @api-buddy/cloudinary

@api-buddy/cloudinary - 3.0.0 | npmpackage.info

@api-buddy/cloudinary

3.0.0

279.35 kB

Installations

npm install @api-buddy/cloudinary

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS

Node Version

18.18.0

NPM Version

9.8.1 Releases

Unable to fetch releases

Download Statistics

Total Downloads

Last Day

Last Week

Last Month

Last Year

Maintainers

Package Meta Information

Latest Version

3.0.0

Package Id

@api-buddy/cloudinary@3.0.0

Unpacked Size

279.35 kB

Size

62.04 kB

File Count

NPM Version

9.8.1

Node Version

18.18.0

Published on

Jul 01, 2025

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

NaN

Compared to previous day

Last Week

NaN

Compared to previous week

Last Month

NaN

Compared to previous month

Last Year

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

@api-buddy/cloudinary

A comprehensive Cloudinary integration for Next.js applications, providing a simple and type-safe way to upload, transform, and deliver images and videos.

Features

🚀 Easy Setup: Get started quickly with a few simple steps
🔒 Type-Safe: Full TypeScript support for all Cloudinary options and responses
⚡ Performance Optimized: Automatic image optimization and responsive images
🎣 React Hooks: Custom hooks for easy file uploads and media management
🖼️ Components: Pre-built React components for images and videos
🛠 CLI Tool: Quick project setup with the included CLI
🔄 Server & Client Support: Works with both server components and client components
📱 Responsive Images: Automatic srcset generation for responsive images
🎥 Video Support: Upload, transform, and deliver videos with ease

Installation

1# Using npm
2npm install @api-buddy/cloudinary cloudinary
3
4# Using yarn
5yarn add @api-buddy/cloudinary cloudinary
6
7# Using pnpm
8pnpm add @api-buddy/cloudinary cloudinary

If you're using TypeScript, you'll also want to install the Cloudinary types:

1npm install --save-dev @types/cloudinary

Quick Start

1. Set Up Environment Variables

Create a .env.local file in your project root and add your Cloudinary credentials:

1NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your_cloud_name
2NEXT_PUBLIC_CLOUDINARY_API_KEY=your_api_key
3CLOUDINARY_API_SECRET=your_api_secret
4NEXT_PUBLIC_CLOUDINARY_UPLOAD_PRESET=your_upload_preset

2. Set Up the Cloudinary Provider

Wrap your application with the CloudinaryProvider in your root layout:

1// app/layout.tsx
2'use client';
3
4import { CloudinaryProvider } from '@api-buddy/cloudinary';
5
6export default function RootLayout({
7  children,
8}: {
9  children: React.ReactNode;
10}) {
11  return (
12    <html lang="en">
13      <body>
14        <CloudinaryProvider 
15          config={{
16            // Optional: Configure default settings here
17            cloudName: process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME,
18            apiKey: process.env.NEXT_PUBLIC_CLOUDINARY_API_KEY,
19            apiSecret: process.env.CLOUDINARY_API_SECRET,
20            uploadPreset: process.env.NEXT_PUBLIC_CLOUDINARY_UPLOAD_PRESET,
21          }}
22        >
23          {children}
24        </CloudinaryProvider>
25      </body>
26    </html>
27  );
28}

3. Upload Files

Create an API route to handle file uploads:

1// app/api/upload/route.ts
2import { NextResponse } from 'next/server';
3import { upload } from '@api-buddy/cloudinary';
4
5export async function POST(request: Request) {
6  try {
7    const formData = await request.formData();
8    const file = formData.get('file') as File;
9    
10    if (!file) {
11      return NextResponse.json(
12        { success: false, error: 'No file provided' },
13        { status: 400 }
14      );
15    }
16
17    // Convert the file to a buffer
18    const buffer = Buffer.from(await file.arrayBuffer());
19    
20    // Upload to Cloudinary
21    const result = await upload(buffer, {
22      folder: 'uploads',
23      resourceType: 'auto',
24      public_id: file.name.replace(/\.[^/.]+$/, ''), // Remove file extension
25      filename_override: file.name,
26      context: {
27        filename: file.name,
28        format: file.type,
29        size: file.size,
30      },
31    });
32
33    return NextResponse.json({ success: true, data: result });
34  } catch (error) {
35    console.error('Upload error:', error);
36    return NextResponse.json(
37      { success: false, error: 'Failed to upload file' },
38      { status: 500 }
39    );
40  }
41}

4. Use the useCloudinaryUpload Hook

1'use client';
2
3import { useCloudinaryUpload } from '@api-buddy/cloudinary';
4
5export default function UploadForm() {
6  const { uploadFile, isUploading, progress, error } = useCloudinaryUpload({
7    options: {
8      folder: 'images',
9      resourceType: 'image',
10    },
11    onSuccess: (result) => {
12      console.log('Upload successful:', result);
13    },
14    onError: (error) => {
15      console.error('Upload error:', error);
16    },
17  });
18
19  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
20    const file = e.target.files?.[0];
21    if (file) {
22      await uploadFile(file);
23    }
24  };
25
26  return (
27    <div className="p-6 max-w-md mx-auto bg-white rounded-xl shadow-md">
28      <h2 className="text-xl font-semibold mb-4">Upload an Image</h2>
29      
30      <div className="mb-4">
31        <input
32          type="file"
33          accept="image/*"
34          onChange={handleFileChange}
35          disabled={isUploading}
36          className="block w-full text-sm text-gray-500
37            file:mr-4 file:py-2 file:px-4
38            file:rounded-md file:border-0
39            file:text-sm file:font-semibold
40            file:bg-blue-50 file:text-blue-700
41            hover:file:bg-blue-100"
42        />
43      </div>
44
45      {isUploading && (
46        <div className="w-full bg-gray-200 rounded-full h-2.5">
47          <div
48            className="bg-blue-600 h-2.5 rounded-full"
49            style={{ width: `${progress}%` }}
50          ></div>
51          <p className="text-sm text-gray-600 mt-1">Uploading: {progress}%</p>
52        </div>
53      )}
54
55      {error && (
56        <div className="mt-4 p-3 bg-red-100 text-red-700 rounded-md">
57          Error: {error.message}
58        </div>
59      )}
60    </div>
61  );
62}

5. Display Images

1import { CloudinaryImage } from '@api-buddy/cloudinary';
2
3export default function ProfileImage({ publicId }: { publicId: string }) {
4  return (
5    <div className="w-32 h-32 rounded-full overflow-hidden">
6      <CloudinaryImage
7        publicId={publicId}
8        alt="Profile image"
9        width={128}
10        height={128}
11        className="w-full h-full object-cover"
12        transformation={[
13          { width: 256, height: 256, crop: 'thumb', gravity: 'face' },
14          { radius: 'max' },
15        ]}
16      />
17    </div>
18  );
19}

CLI Setup

For a quick setup, use the included CLI:

1npx @api-buddy/cloudinary setup

This will:

Install required dependencies
Set up environment variables
Create example components and API routes
Configure your Next.js app to use Cloudinary

API Reference

`CloudinaryProvider`

A context provider that makes the Cloudinary client available throughout your application.

Props

config: Configuration object
- cloudName: Your Cloudinary cloud name (required)
- apiKey: Your Cloudinary API key (optional, defaults to process.env.NEXT_PUBLIC_CLOUDINARY_API_KEY)
- apiSecret: Your Cloudinary API secret (optional, defaults to process.env.CLOUDINARY_API_SECRET)
- uploadPreset: Your Cloudinary upload preset (optional)
- defaultUploadOptions: Default options for all uploads

`useCloudinary()`

A hook to access the Cloudinary client from the nearest CloudinaryProvider.

Returns

client: The Cloudinary client instance
config: The current Cloudinary configuration

`useCloudinaryUpload(options)`

A hook for handling file uploads to Cloudinary.

Parameters

options: Upload options
- options: Default upload options for all uploads
- onSuccess: Callback when an upload succeeds
- onError: Callback when an upload fails
- onProgress: Callback with upload progress (0-100)

Returns

uploadFile: Function to upload a single file
uploadFiles: Function to upload multiple files
isUploading: Boolean indicating if an upload is in progress
progress: Current upload progress (0-100)
error: Error object if an upload failed
reset: Function to reset the hook state

`CloudinaryImage`

A React component for displaying Cloudinary images with automatic optimization.

Props

publicId: The public ID of the image (required)
alt: Alternative text for the image (required)
width: Width of the image
height: Height of the image
className: CSS class name
style: Inline styles
loading: Loading behavior (lazy or eager)
transformation: Array of Cloudinary transformations
format: Image format to convert to
quality: Image quality (1-100)
responsive: Whether to generate responsive images
sizes: Sizes attribute for responsive images
srcSet: Custom srcset for responsive images
onLoad: Callback when the image loads
onError: Callback when the image fails to load

`CloudinaryVideo`

A React component for displaying Cloudinary videos.

Props

publicId: The public ID of the video (required)
width: Width of the video player
height: Height of the video player
className: CSS class name
style: Inline styles
autoPlay: Whether to autoplay the video
loop: Whether to loop the video
muted: Whether to mute the video
controls: Whether to show video controls
poster: URL of the poster image
transformation: Array of Cloudinary transformations
onPlay: Callback when the video starts playing
onPause: Callback when the video is paused
onEnded: Callback when the video ends
onError: Callback when the video fails to load

`upload(file, options)`

Upload a file to Cloudinary.

Parameters

file: File to upload (Buffer, ReadStream, or base64 string)
options: Upload options (see Cloudinary documentation)

Returns

A promise that resolves to the upload result.

`deleteFile(publicId, options)`

Delete a file from Cloudinary.

Parameters

publicId: The public ID of the file to delete
options: Delete options
- resourceType: Type of resource (image, video, raw, or auto)
- type: The type of the resource
- invalidate: Whether to invalidate the CDN cache

Returns

A promise that resolves to the delete result.

`getUrl(publicId, options)`

Generate a URL for a Cloudinary resource.

Parameters

publicId: The public ID of the resource
options: URL and transformation options
- transformation: Array of Cloudinary transformations
- resourceType: Type of resource (image, video, raw, or auto)
- type: The type of the resource
- format: Format to convert the resource to
- secure: Whether to use HTTPS
- signUrl: Whether to sign the URL
- version: The version of the resource

Returns

The generated URL as a string.

Examples

Uploading a File

1import { upload } from '@api-buddy/cloudinary';
2
3// In an API route or server component
4const file = // your file buffer or stream
5const result = await upload(file, {
6  folder: 'uploads',
7  resourceType: 'auto',
8  public_id: 'my-file',
9});
10
11console.log('File uploaded:', result.url);

Using Transformations

1import { CloudinaryImage } from '@api-buddy/cloudinary';
2
3function ProductImage({ publicId }: { publicId: string }) {
4  return (
5    <CloudinaryImage
6      publicId={publicId}
7      alt="Product image"
8      width={400}
9      height={400}
10      transformation={[
11        { width: 800, height: 800, crop: 'fill' },
12        { effect: 'sharpen' },
13        { quality: 'auto' },
14      ]}
15    />
16  );
17}

Responsive Images

1import { CloudinaryImage } from '@api-buddy/cloudinary';
2
3function HeroImage({ publicId }: { publicId: string }) {
4  return (
5    <CloudinaryImage
6      publicId={publicId}
7      alt="Hero image"
8      width={1200}
9      height={630}
10      className="w-full h-auto"
11      responsive
12      sizes="(max-width: 768px) 100vw, 50vw"
13      transformation={[
14        { width: 1200, height: 630, crop: 'fill' },
15        { quality: 'auto' },
16      ]}
17    />
18  );
19}

Error Handling

All functions throw a CloudinaryError when something goes wrong. You can catch and handle these errors:

1try {
2  await upload(file, options);
3} catch (error) {
4  if (error.name === 'CloudinaryError') {
5    console.error('Cloudinary error:', error.message);
6    // Handle specific error cases
7    if (error.code === 'LIMIT_FILE_SIZE') {
8      // Handle file size limit exceeded
9    } else if (error.code === 'UNAUTHORIZED') {
10      // Handle authentication error
11    } else {
12      // Handle other errors
13    }
14  } else {
15    // Handle non-Cloudinary errors
16    console.error('Unexpected error:', error);
17  }
18}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT

Acknowledgments

Cloudinary - Cloud-based image and video management
@cloudinary/url-builder - Official Cloudinary URL builder
@cloudinary/react - Official Cloudinary React components

No vulnerabilities found.

No security vulnerabilities found.

@api-buddy/cloudinary

Installations

Developer Guide

Yes

CommonJS

18.18.0

9.8.1

Releases

Unable to fetch releases

Download Statistics

Maintainers

Package Meta Information

Total Downloads

NaN

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

Peer Dependencies

Dev Dependencies

@api-buddy/cloudinary

Features

Installation

Quick Start

1. Set Up Environment Variables

2. Set Up the Cloudinary Provider

3. Upload Files

4. Use the useCloudinaryUpload Hook

5. Display Images

CLI Setup

API Reference

CloudinaryProvider

Props

useCloudinary()

Returns

useCloudinaryUpload(options)

Parameters

Returns

CloudinaryImage

Props

CloudinaryVideo

Props

upload(file, options)

Parameters

Returns

deleteFile(publicId, options)

Parameters

Returns

getUrl(publicId, options)

Parameters

Returns

Examples

Uploading a File

Using Transformations

Responsive Images

Error Handling

Contributing

License

Acknowledgments

`CloudinaryProvider`

`useCloudinary()`

`useCloudinaryUpload(options)`

`CloudinaryImage`

`CloudinaryVideo`

`upload(file, options)`

`deleteFile(publicId, options)`

`getUrl(publicId, options)`