gatsby-plugin-cloudinary-social-cards

gatsby-plugin-cloudinary-social-cards

Add social sharing cards to your Gatsby sites using Cloudinary!

This plugin will:

• Look for a template image in your repo
• Upload that template to your Cloudinary account
• Automatically create social media sharing images with the title (and optional tagline) of your post

Installation

# install the plugin and its peer dependencies
npm install gatsby-plugin-cloudinary-social-cards react-helmet gatsby-plugin-react-helmet

Create a new API key and secret in your Cloudinary console and set the following environment variables (create a file called .env locally):

CLOUDINARY_API_KEY=<your API key>
CLOUDINARY_API_SECRET=<your API secret>

Next, configure the plugin in your gatsby-config.js:

require('dotenv').config();

module.exports = {
  plugins: [
    'gatsby-plugin-react-helmet',
    {
      resolve: 'gatsby-plugin-cloudinary-social-cards',
      options: {
        cloudName: 'jlengstorf',
        apiKey: process.env.CLOUDINARY_API_KEY,
        apiSecret: process.env.CLOUDINARY_API_SECRET,
        imageTemplate: 'src/assets/social-card-template.jpg',
      },
    },
  ],
};

Configuration

Option	Required	Default	Description
cloudName	true		Your Cloudinary cloud name (usually your account name).
apiKey	true		Your Cloudinary API key (get one here).
apiSecret	true		Your Cloudinary API secret (get one here).
imageTemplate	true		Path to the social card image template. This should be a local file in your repo.
uploadFolder		null	Optional subfolder where the template should be uploaded in your Cloudinary account.
imageOptions		{}	Additional settings for your template image.

If you need a template, I wrote a post on creating a social sharing template image.

imageOptions

The options passed in imageOptions can be any of the available options for the @jlengstorf/get-share-image utility.

NOTE: The cloudName, apiKey, apiSecret, title, tagline, and imagePublicID settings will be overridden by the settings in the plugin.

Usage

There are two ways to use this plugin:

• Import the GatsbySocialImage component
• Use the getSocialCard GraphQL query

Import the GatsbySocialImage component

In most cases, the easiest solution is to use the built-in React component:

import React from 'react';
import { Helmet } from 'react-helmet';
import { GatsbySocialImage } from 'gatsby-plugin-cloudinary-social-cards';

export default () => {
  const title = 'This Page Boops';
  const tagline = 'I hope you like corgis.';

  return (
    <>
      <Helmet>
        <title>{title}</title>
      </Helmet>
      <GatsbySocialImage title={title} tagline={tagline} />
      <h1>{title}</h1>
      <p>{tagline}</p>
    </>
  );
};

The component adds an og:image meta tag to the page:

The generated social card looks like this:

Use the getSocialCard GraphQL query

You can also query for the image URL, which is an alternative for dynamically generated pages.

In gatsby-node.js:

const pages = [
  {
    path: '/test1',
    title: 'The First Test Page',
    tagline: 'This page needs a snappy tagline.',
  },
  {
    path: '/test2',
    title: 'Another Test Page',
  },
];

exports.createPages = ({ actions }) => {
  pages.forEach((page) => {
    actions.createPage({
      path: page.path,
      component: require.resolve('./src/templates/dynamic.js'),
      context: {
        title: page.title,
        tagline: page.tagline,
      },
    });
  });
};

in src/templates/dynamic.js:

import React from 'react';
import { graphql } from 'gatsby';
import { Helmet } from 'react-helmet';

export const query = graphql`
  query($title: String!, $tagline: String) {
    getSocialCard(title: $title, tagline: $tagline) {
      url
    }
  }
`;

export default ({ data, pageContext: { title } }) => {
  return (
    <>
      <Helmet>
        <title>{title}</title>
        <meta property="og:image" content={data.getSocialCard.url} />
      </Helmet>
      <h1>{title}</h1>
    </>
  );
};

The page will have the meta tag added like so:

The generated card looks like this: