Instagram to Cloudinary
We're going to walk through setting up a Node.js project that will fetch Instagram posts, filter by a set of hashtags, then upload those images to Cloudinary, and then trigger a Netlify build. This script will run on a schedule through Github Actions.
Here's the instagram-cloudinary repo if you'd like to skip to the final code.
First, a little history...
I've been using the gatsby-source-instagram plugin for a while on my site to highlight some of my illustrations. I even added some functionality to the plugin so consumers could query their posts by hashtag.
The plugin author has done a great job tracking down issues and documenting the convoluted steps to get Facebook/Instagram API credentials. The plugin worked great for a while, but due to many changes in the Facebook/Instagram API, it became less reliable and harder to debug.
It got to a point where I couldn't update my site because of the errors from the Instagram API. I believe that part of the problem is the frequency of querying the API, where it seemed to only work every few minutes, throwing an error in between of "Please try again later." When working on the site locally, it would cause a cascade of errors in Gatsby's graph. Because of this and the ever-changing permissions in the Facebook API, the plugin has been much harder to maintain.
To query the Instagram API less frequently and have more control, I decided to set up a Node.js project to fetch posts from the Instagram API, filter and find hashtags, and then upload those to Cloudinary. When the posts send successfully, the script fires a Netlify build via a webhook.
To make this work for my case, I jotted down what I needed this script to do.
- fetch the latest posts from Instagram
- make sure we get the first few comments (I used to put the post's hashtags in the first comment)
- upload the posts that match my hashtag list to Cloudinary
- trigger a build of my site (my site is running gatsby-source-cloudinary)
Setting up a new project
The first thing to do is set up a new Node.js project. There are quite a few starters out there, but, for this, I just started from scratch.
Create the project folder and navigate to it.
Initialize the package.json. I use
yarn, but feel free to use
This is what my package.json file looks like after initialization:
I like to use TypeScript so that's the first dependency I'll add here. The
-D flag sets them as
ts-node is going to help run the script.
Next, it's time to set up the
tsconfig.json file. I usually run the
init and update the items as necessary.
This is how mine looks after cleanup.
Since we'll be using API keys for Instagram and Cloudinary, we can add
dotenv to help us with the environment variables.
Next is adding the script file in the
In this file we can add some pseudo code to help us step through. Our
src/index.ts can look like this:
Let's get those posts!
We'll start with adding axios as a dependency. Axios will help us with the requests.
Next, let's set up some environment variables for Instagram. For this, you'll need an access token and Instagram id from Facebook so that you can query Instagram. Honestly, I don't remember how I got these working correctly but, the directions on gatsby-source-instagram were helpful.
.env file at the root of your project and add your values like:
Now that we have these ready, we can start putting the script together. I'll put the Instagram fetching in its own function, so it's easier to reason about later.
First, we add the
require("dotenv").config(); so we have access to the environment variables that we set up above.
For the request, we're using axios and building the URL with our parameters. The parameters are specialized to what we need for grabbing all the user's posts and the first three comments on those posts.
We're using the environment variables declared above to place into these parameters for the id and access token. The
MAX_POSTS is a setting that we can increase whenever we need to do more or decrease if we're only trying to maintain the last few posts posted to Instagram.
We then use an
await to make sure the posts resolve before moving on to the next step. We can also add a try-catch in case there is a failure.
Prepare the Posts by Hashtag
Let's do this section in its own function as well. We can add the invocation of it to
instagramToCloudinary(). We'll add a type of
UploadPost that we can define in
src/types.ts and import into our script. The
UploadPost array will store our data in a way that we can pass to Cloudinary more easily.
Now, let's create the
convertInstagramPostToCloudinaryEntity() function. This one is fairly deep, so I'll try to walk through it in pieces, then put it all together. We can stub out the function and add a type of
Post which is, roughly, the shape we get back from the Instagram API.
Now that we have a function ready to start with, we need to figure out how to filter the posts based on a hashtag. I opted to create a list of the hashtags I would like to showcase on my site. The list has an
id and a
regex because I messed up the hashtags a few times on Instagram and didn't want to go back through to fix them.
First, we'll loop over the hashtag config and filter down to the posts that have the hashtags that we want. Then, we'll be able to combine the hashtags, if a post has more than one and create an entity that will be easier for the upload step. We can store these in a variable outside of the loop that will be returned at the end of the function.
Upload to Cloudinary
Now that we have an array of Cloudinary-like entities, we're ready to move on to uploading to Cloudinary. To achieve this, we'll need to make sure we have upload credentials.
Cloudinary API Credentials
If you have a Cloudinary account, you can log in and go to Settings -> Security -> Access Keys. Here, you can add a new pair, which will be used in this script.
Once finished, you should see all the details you'll need at the top of your Cloudinary dashboard.
Let's get the Cloudinary client connected. We'll need to add some items to our
We can now use these in our app to help us connect to Cloudinary. Here is the connection config. I placed this at the top of the index file, under the imports.
Start the Uploads
We're now ready to start the upload process. We'll start by creating a new async function because we want to know if all of the uploads made it successfully.
Cloudinary doesn't have a bulk upload script but their individual upload is very quick and can handle many uploads simultaneously so we can just loop over our entities and send them up. Here's the upload API we'll be using. There are a lot of options that can be adjusted based on the projects' needs. Here, we're just using the basic options.
I'm using an array of promises to help me determine if any had an error while uploading. This may not be necessary for all cases but I like to know, especially before kicking off a new build of the site.
The last argument in the upload function is a callback that can help us determine if the upload was successful or not. We can check against this in our
successfullyResolved check and return an appropriate status.
Trigger Netlify Deploy
If all the images were uploaded successfully, we'll trigger the build on Netlify. First, we'll need our Netlify webhook. You can set one up in the deploys settings
https://app.netlify.com/sites/<account>/settings/deploys under the Build Hooks section. Once you have the hook, you can add that to your
We'll now set up a conditional build script using
Our script should look something like this now:
Github Action to Run on Schedule
In your Github project you can create an action and use the following config for a daily run.
- cron: "0 0 * * *" is what configures the action to run once a day.
Offloading my Instagram posts to Cloudinary has made my site build more reliably, especially when I'm doing local development. The Cloudinary API has been rock solid for me so far and it's easier to work with.
Hopefully, this process is broken up enough that any service could be swapped out for another with little effort. I can see other social channels being aggregated into this pipeline as well.