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.
gatsby-plugin-image
compatible when used withgatsby-transformer-cloudinary
.- To upload images already in the Gatsby data layer (such as local files) to Cloudinary use
gatsby-transformer-cloudinary
.
📖 Table of Contents
- 🚀 Getting Started
- 🖼️ Use with Gatsby Image
- 🔌 Pugin Options
- ⚠️ Gotchas
- 📚 Other Resources
- 🏴☠️ Contribute
🚀 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
andq_auto
Cloudinary transformations are applied automatically to thesecure_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.