Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cloudinary-community/gatsby-source-cloudinary
Source media from your Cloudinary account 📥 🖼
https://github.com/cloudinary-community/gatsby-source-cloudinary
gatsby gatsby-plugin gatsbyjs hacktoberfest
Last synced: about 2 months ago
JSON representation
Source media from your Cloudinary account 📥 🖼
- Host: GitHub
- URL: https://github.com/cloudinary-community/gatsby-source-cloudinary
- Owner: cloudinary-community
- License: mit
- Created: 2018-10-06T18:29:19.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-04-05T17:24:20.000Z (9 months ago)
- Last Synced: 2024-04-14T03:39:35.034Z (8 months ago)
- Topics: gatsby, gatsby-plugin, gatsbyjs, hacktoberfest
- Language: JavaScript
- Homepage:
- Size: 612 KB
- Stars: 28
- Watchers: 8
- Forks: 18
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 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`](https://www.gatsbyjs.com/plugins/gatsby-transformer-cloudinary/) to:
- 🖼️ Add [gatsby-plugin-image](https://www.gatsbyjs.com/plugins/gatsby-plugin-image/) support to the sourced `CloudinaryMedia` nodes.
- 📤 Upload local images and remote images to [Cloudinary](https://cloudinary.com/) from within your Gatsby project.
**This is a community library supported by the Cloudinary Developer Experience team.**
## 📖 Table of Contents
- [🚀 Getting Started](#🚀-getting-started)
- [Install Package](#install-package)
- [Configure Plugin](#configure-plugin)
- [Example usage](#example-usage)
- [🖼️ Use with Gatsby Image](#🖼️-use-with-gatsby-plugin-image)
- [Install Packages](#install-packages)
- [Configure Plugins](#configure-plugins)
- [Example usage](#example-usage)
- [🔌 Pugin Options](#🔌-plugin-options)
- [⚠️ Gotchas](#⚠️-gotchas)
- [📚 Other Resources](#📚-other-resources)
- [🏴☠️ Contribute](#🏴☠️-contribute)
## 🚀 Getting Started
### Install Package
```bash
npm install gatsby-source-cloudinary
```
or
```bash
yarn add gatsby-source-cloudinary
```
### Configure Plugin
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](https://www.gatsbyjs.com/docs/how-to/local-development/environment-variables/).
### Example usage
```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`](https://www.gatsbyjs.com/plugins/gatsby-plugin-image/) you'll need the [`gatsby-transformer-cloudinary`](https://www.gatsbyjs.com/plugins/gatsby-transformer-cloudinary/) plugin.
### Install Packages
```bash
npm install gatsby-transformer-cloudinary gatsby-plugin-image
```
or
```bash
yarn add gatsby-transformer-cloudinary gatsby-plugin-image
```
### Configure Plugins
```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](https://www.gatsbyjs.com/plugins/gatsby-plugin-image/) and [`gatsby-transformer-cloudinary` docs](https://www.gatsbyjs.com/plugins/gatsby-transformer-cloudinary/) to learn more.
### Example usage
```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 (
{data.allCloudinaryMedia.nodes.map((media, index) => {
const image = getImage(media);
return ;
})}
);
}
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](https://cloudinary.com/console/).
**Type:** String\
**Default:** n/a\
**Note:** Store and retrieve your `cloudName` as [an environment variable](https://www.gatsbyjs.com/docs/how-to/local-development/environment-variables/).
### `apiKey` (required)
The API Key of your Cloudinary account. You'll find it in your [Cloudinary console](https://cloudinary.com/console/).
**Type:** String\
**Default:** n/a\
**Note:** Store and retrieve your `apiKey` as [an environment variable](https://www.gatsbyjs.com/docs/how-to/local-development/environment-variables/).
### `apiSecret` (required)
The API Secret of your Cloudinary account. You'll find it in your [Cloudinary console](https://cloudinary.com/console/).
**Type:** String\
**Default:** n/a\
**Note:** Store and retrieve your `apiSecret` as [an environment variable](https://www.gatsbyjs.com/docs/how-to/local-development/environment-variables/).
### `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 the Advanced plan or higher that have a custom CNAME. For details, see [Private CDNs and CNAMEs](https://cloudinary.com/documentation/advanced_url_delivery_options#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 the Advanced plan or higher that have a custom CNAME. For details, see [Private CDNs and CNAMEs](https://cloudinary.com/documentation/advanced_url_delivery_options#private_cdns_and_cnames).
**Type:** String\
**Default:** n/a
### `privateCdn`
Relevant only for users on the Advanced plan or higher that have private CDN distribution. For details, see [Private CDNs and CNAMEs](https://cloudinary.com/documentation/advanced_url_delivery_options#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`](https://www.gatsbyjs.com/plugins/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](https://cloudinary.com/documentation/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](https://github.com/cloudinary-devs/gatsby-source-cloudinary/blob/main/CONTRIBUTING.md).