Gatsby-source-cloudinary NPM

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 based on your configuration.

Use together with gatsby-transformer-cloudinary to:

🖼️ Add gatsby-plugin-image support to the sourced CloudinaryMedia nodes.
📤 Upload local images and remote images to Cloudinary from within your Gatsby project.

📖 Table of Contents

🚀 Getting Started

Install Package

npm install gatsby-source-cloudinary

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 # https version of the url
        # url - http version of the url
      }
    }
  }
`;

🖼️ Use with Gatsby Plugin Image

To add support for gatsby-plugin-image you'll need the gatsby-transformer-cloudinary plugin.

Install Packages

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

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

Configure Plugins

// File: ./gatsby-config.js

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

// File: ./pages/images.js

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: Boolean\ Default: n/a

`secureDistribution`

The custom domain name (CNAME) to use for building secure URLs (https).

Relevant only for users on Advanced plan or higher that have a custom CNAME. For details, see Private CDNs and CNAMEs.

Type: String\ Default: n/a

`cname`

The custom domain name (CNAME) to use for building non-secure URLs (http).

Relevant only for users on Advanced plan or higher that have a custom CNAME. For details, see Private CDNs and CNAMEs.

Type: String\ Default: n/a

`privateCdn`

Set this parameter to true if you are on an Advanced plan user with a private CDN distribution.

Type: Boolean\ Default: false

⚠️ 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 and url value optimizing the delivered media quality and format.
If you use this plugin together wih gatsby-transformer-cloudinary the secureDistribution, cname and privateCdn options do not carry over, and as of now there is no way to set them in that plugin.