Manage Cloudinary media assets in TinaCMS.

The following guide uses NextJS's API functions to authenticate the 3rd-party media interactions. If you are using another framework with Vercel, this guide still applies (with a small tweak that you need to use /api/... instead of /pages/api for your Serverless function).

Installation

yarn add next-tinacms-cloudinary @tinacms/auth

Connect with Cloudinary

You need to provide your Cloudinary credentials to connect to your media library. Do register on Cloudinary if you don't have an account yet, your account details are displayed on the Cloudinary dashboard.

Add the following variables to an .env file.

CLOUDINARY_CLOUD_NAME=<Your Cloudinary Cloud Name>

CLOUDINARY_API_KEY=<Your Cloudinary API key>

CLOUDINARY_API_SECRET=<Your Cloudinary API secret>

Register the Media Store

Now, you can replace the default repo-based media with the external media store. You can register the Cloudinary Media store via the loadCustomStore prop.

The loadCustomStore prop can be configured within tina/config.{js,ts}.

//tina/config.{ts,js}

export default defineConfig({
  //...
  media: {
-    tina: {
-      publicFolder: 'public',
-      mediaRoot: 'uploads',
-    },
+    loadCustomStore: async () => {
+      const pack = await import("next-tinacms-cloudinary");
+      return pack.TinaCloudCloudinaryMediaStore;
+    },
  },
})

Set up API routes

Tina's "external media provider" support requires a light backend media handler, that needs to be setup/hosted by the user. There are multiple ways to setup this handler:

"NextJS API Routes"

For sites using NextJS, you can setup the handler as a NextJS Server function. To do so, create a pages/api/cloudinary/[...media].ts file in your project, with the following implementation:

// pages/api/cloudinary/[...media].ts

import {
  mediaHandlerConfig,
  createMediaHandler,
} from 'next-tinacms-cloudinary/dist/handlers'

import { isAuthorized } from '@tinacms/auth'

export const config = mediaHandlerConfig

export default createMediaHandler({
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  authorized: async (req, _res) => {
    try {
      if (process.env.NODE_ENV == 'development') {
        return true
      }

      const user = await isAuthorized(req)

      return user && user.verified
    } catch (e) {
      console.error(e)
      return false
    }
  },
})

Here's what's happening in the above snippet:

• We call createMediaHandler to set up routes and connect your instance of the Media Store to your Cloudinary account.
• The authorized key will make it so only authorized users within TinaCloud can upload and make media edits.

Framework Agnostic implementations

In the above example, we showed how to host the backend handler as a NextJS API function. If you are using Vercel with another framework, the same approach applies (with the small difference that you need to use /api/... instead of /pages/api/... for your handler).

You can also check out our Netlify Functions implementation.

Update Schema

Now that the media store is registered and the API route for media set up, let's add an image to your schema.

In your tina/config.{ts,tsx,js} add a new field for the image, e.g:

 {
  name: 'hero',
  type: 'image',
  label: 'Hero Image',
 }

Now, when editing your site, the image field will allow you to connect to your Cloudinary account via the Media Store to manage your media assets.