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.

This is a community library supported by the Cloudinary Developer Experience team.

📖 Table of Contents

- 🚀 Getting Started
- Install Package
- Configure Plugin
- Example usage
- 🖼️ Use with Gatsby Image
- Install Packages
- Configure Plugins
- Example usage
- 🔌 Pugin Options
- ⚠️ Gotchas
- 📚 Other Resources
- 🏴‍☠️ Contribute

🚀 Getting Started

$3

``bash
npm install gatsby-source-cloudinary
`

or

`bash
yarn add gatsby-source-cloudinary
`

$3

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

`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
},
},
],
};
`

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

$3

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

export default function BasicPage({ data }) {
return (



{data.allCloudinaryMedia.nodes.map((media, index) => (

))}


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.

$3

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

or

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

$3

`js
// 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.

$3

`jsx
// 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 (


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

🔌 Plugin Options

$3

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.

$3

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.

$3

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.

$3

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.

$3

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.

$3

Max number of resources to return.

Type: Integer\
Default: 10

$3

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

Type: Boolean\
Default: false

$3

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.

$3

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

$3

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

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

Type: String\
Default: n/a

$3

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

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

Type: String\
Default: n/a

$3

Relevant only for users on the Advanced plan or higher that have private CDN distribution. For details, see Private CDNs and CNAMEs.

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 with gatsby-transformer-cloudinary` the secureDistribution, cname and privateCdn options do not carry over, and there is no way to set them in that plugin.

📚 Other Resources

- Cloudinary image transformation reference

🏴‍☠️ Contribute

You may improve the documentation, help fellow users, report bugs, suggest enhancements, contribute code and more.

Get started by reading the contribution docs.