New Launch

Take a deep dive into the fastest Gatsby, yet: Gatsby 5!

ContactSign Up for Free
Community Plugin
View plugin on GitHub

Gatsby Source Cloudinary

Pull data from your Cloudinary account into the Gatsby data layer with gatsby-source-cloudinary. Creates a CloudinaryMedia node for each media file found.

 

📖 Table of Contents

 

🚀 Getting Started

Install Package

npm install gatsby-source-cloudinary

or

yarn add gatsby-source-cloudinary

Configure Plugin

Add gatsby-source-cloudinary to the plugin array in your gatsby-config.js file.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-cloudinary`,
      options: {
        cloudName: process.env.CLOUDINARY_CLOUD_NAME,
        apiKey: process.env.CLOUDINARY_API_KEY,
        apiSecret: process.env.CLOUDINARY_API_SECRET,
        // resourceType: `image`,
        // type: `twitter`,
        // maxResults: 22,
        // tags: true,
        // context: true,
        // prefix: `demo/animals`
      },
    },
  ],
};

process.env ⁉️ Read about env variables in the Gatsby docs.

Example usage

import React from 'react';
import { graphql } from 'gatsby';

export default function BasicPage({ data }) {
  return (
    <main>
      {data.allCloudinaryMedia.nodes.map((media, index) => (
        <img key={index} width="200px" src={media.secure_url} />
      ))}
    </main>
  );
}

export const query = graphql`
  query {
    allCloudinaryMedia {
      nodes {
        secure_url
      }
    }
  }
`;

 

🖼️ Use with Gatsby Plugin Image

To use gatsby-plugin-image with your CloudinaryMedia nodes, you need the gatsby-transformer-cloudinary to add the gatsbyImageData resolver needed.

Install Packages

npm install --save gatsby-transformer-cloudinary gatsby-plugin-image

or

yarn add --save gatsby-transformer-cloudinary gatsby-plugin-image

Configure Plugins

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-cloudinary`,
      options: {
        cloudName: process.env.CLOUDINARY_CLOUD_NAME,
        apiKey: process.env.CLOUDINARY_API_KEY,
        apiSecret: process.env.CLOUDINARY_API_SECRET,
        // resourceType: `image`,
        // type: `twitter`,
        // maxResults: 22,
        // tags: true,
        // context: true,
        // prefix: `demo/animals`
      },
    },
    {
      resolve: `gatsby-transformer-cloudinary`,
      options: {
        // Add the `gatsbyImageData` resolver to `CloudinaryMedia`
        transformTypes: [`CloudinaryMedia`],
      },
    },
    `gatsby-plugin-image`,
  ],
};

Check the gatsby-plugin-image docs and gatsby-transformer-cloudinary docs to learn more.

Example usage

import React from 'react';
import { graphql } from 'gatsby';
import { GatsbyImage, getImage } from 'gatsby-plugin-image';

export default function GasbyImagePage({ data }) {
  return (
    <main>
      {data.allCloudinaryMedia.nodes.map((media, index) => {
        const image = getImage(media);
        return <GatsbyImage key={index} image={image} />;
      })}
    </main>
  );
}

export const query = graphql`
  query {
    allCloudinaryMedia {
      nodes {
        gatsbyImageData(width: 300, placeholder: BLURRED)
      }
    }
  }
`;

 

🔌 Plugin Options

cloudName (required)

You’ll find your Cloudinary account’s cloudName in your Cloudinary console.

Type: String
Default: n/a
Note: Store and retrieve your cloudName as an environment variable.

apiKey (required)

The API Key of your Cloudinary account. You’ll find it in your Cloudinary console.

Type: String
Default: n/a
Note: Store and retrieve your apiKey as an environment variable.

apiSecret (required)

The API Secret of your Cloudinary account. You’ll find it in your Cloudinary console.

Type: String
Default: n/a
Note: Store and retrieve your apiSecret as an environment variable.

resourceType

The resource types to include when pulling data from Cloudinary.

Type: String
Default: image
Valid: image, raw and video
Note: Use the video resourceType for all video and audio files, such as .mp3 and .mp4.

type

The storage types to include when pulling data from your Cloudinary account.

Type: String
Default: n/a
Valid: upload, private, authenticated, facebook, twitter, gplus, instagram_name, gravatar, youtube, hulu, vimeo, animoto, worldstarhiphop and dailymotion
Note: When not given, all types are sourced.

maxResults

Max number of resources to return.

Type: Integer
Default: 10

tags

When true, includes the list of tag names assigned to each resource.

Type: Boolean
Default: false

prefix

Find all resources with a public ID that starts with the given prefix sorted by public ID in the response.

Type: String
Default: n/a
Note: Can be used to source only media files from a specific folder. However, you will need to specify both type and resourceType in the config options.

context

When true, includes the context data assigned to each resource. Helpful in retrieving alt text or custom metadata configured for the media file in Cloudinary.

Type: String
Default: n/a

 

⚠️ Gotchas

  • Gatsby pulls the data from Cloudinary when it builds; you need to trigger a rebuild whenever new media files are added to the Cloudinary account.
  • f_auto and q_auto Cloudinary transformations are applied automatically to the secure_url value optimizing the delivered media quality and format.

 

📚 Other Resources

 

🏴‍☠️ Contribute

Want to contribute to making the plugin even better? Feel free to send in issues and pull requests on feature requests, fixes, bugs, typos, performance lapses, or any other challenge faced using our plugin.

© 2022 Gatsby, Inc.