This course has been updated! We now recommend you take the Intermediate Gatsby, v2 course.
Transcript from the "Images & Cloudinary" Lesson
[00:00:00]
>> Jason Lengstorf: We're gonna use Cloudinary for handling assets on our site and the reason for that is that the typical path if you watch the other Gatsby workshop that I did on Frontend Masters, we used a plugin called Sharp. And Sharp will handle everything locally, it generates all the different assets as part of the build pipeline and stores them in your local file system and there are a couple reasons that we're not gonna do that this time.
[00:00:25] The first one is that Sharp is really powerful, but it's also kind of finicky and if your node version changes or if your yarn.lock, it's a little bit out of sync between machines then sharp will fail with really cryptic errors and it can be kind of hard to debug.
[00:00:42] Especially if you're on a team where lots of people are gonna be touching it and they're not necessarily using exactly the same machine setup. So we wanna avoid that hassle, we wanna avoid that confusion. Another issue that will run into is that Nullify just introduced restrictions on the amount of time that you get for free for build minutes.
[00:01:02] So every time that you run a build on that Nullify, it's going to take a set amount of time and they track those bills minutes against your monthly total. If you exceed that monthly total then you know they don't take your site down or anything but you do have to start paying for building minutes.
[00:01:16] And what that means for us is that anything that we can take out of that build pipeline without degrading our sites gives us an advantage to keep stuff that we're building free, right? And for personal projects we don't wanna have to be shelling out a bunch of cash for that so Cloudinary has an extremely generous free tier and when we use Cloudinary as our asset management pipeline, we get to do two things.
[00:01:45] First, we dropped Sharp out of the processing pipeline, which means that we eliminate some cryptic errors and potential confusion for us and our team and we eliminate extra work done during the build process. Which will speed up our builds and cut down on the number of build minutes that we're using through something like Nullify, which will help us stay in our free tier and keep things affordable for us on our projects.
[00:02:08] Let's add support for images so, one of the best things about this drink is this gorgeous red color, right? And it comes with an orange peel and It's a very aesthetically pleasing drink so we really aren't getting the full effect on this website when we're just looking at text, we wanna be able to look at these images.
[00:02:23] So let's get these going and the images that we have are here, we can see got these nice looking images and so let's get these into the site. To do that, because we don't want to really elongate the length of our build, we're gonna use Cloudinary to handle asset management for us.
[00:02:47] So there is a transformer plugin for Cloudinary that we're going to use and we will use that by installing the let's say yarn workspace.negronis add, we're gonna add gatsby-transformer-cloudinary. And in order to get to the images, we need to use gatsby-source-filesystem and then, because we wanna be able to display those images, we're gonna import Gatsby image which is a helper component for a reactor tat will do a lot of lazy loading and it waits until the image is in the view port to start loading and all those nice things to make sure that we get a very fast performance with our images without us having to do a bunch of manual work.
[00:03:44] So we'll get those installed and while we're waiting for those to install we can jump into our Gatsby config and I will configure this, we're going to first install gatsby-source-filesystem and for the options, we're gonna get given a name images. Again, because this is the site and not the theme, we can be a little more like it's our site, we don't have to worry about incompatibility downstream and then, the path that we wanna use is source images and that’ll give us these images here.
[00:04:28] So the next thing that we wanna do is, we want to use the transformer for cloudinary and for the options, it’s going to need out cloudname, our API key, an API secret and where we wanna store things. So we just choose an upload folder and I'll just set this to like frontendmasters workshop.
[00:04:58] To get the rest of these, we need to go to Cloudinary so I'm just gonna jump over to the cloudinary.com site and I'm going to log in. Cloudinary has a really generous free tier so it's a really good tool for kinda getting started with image asset management, you're gonna be able to go quite a ways before you hit their caps.
[00:05:18] Once you are in your dashboard, once you're signed up, you'll be at cloudinary.com/console, I'm gonna go up to this, the settings cog at the top right. And then I'm going to go to the Security tab and scroll all the way to the bottom and there's a link under Access keys to generate a new pair.
[00:05:38] I've created a couple of these already in order to avoid showing API tokens that I would then have to go and validate, I have a disabled key that I can show instead. So the API key that we're gonna pull is this one here and then you get to play this fun game with Cloudinary API where you click on this and it becomes visible.
[00:06:00] Now this is a disable key so this won't work but to select it you have to move off and then kind of drag over here and then copy it and then when you go into your actual files it's gonna have a bunch of junk on it so just make sure that you actually only select that text.
[00:06:21] That's a very fun UI quirk where because if you try to actually select it it will go invisible again. [LAUGH]. So it's not very fun but anyways, so you're then going to put it into a .end.development so I've got a live API key in there so I'm not gonna show that but I will show this example file which is exactly the same except I've replaced these here.
[00:06:44] So the cloud name is gonna match your cloundinary.com Cloudbucket, which you can find up here so mine is jlengstorf so I put in jlengstorf here. Then for the API key, that's the one that's always visible and then the API secret is this one here so those are the values that you have to set.
[00:07:07] Once you've set those values we then need to pull those in to Gatsby's environment, Gadsby ships with dotenv already installed so we can just use it. So I'm gonna go into the Gatsby config and up at the top, I'm going to require dotenv and then we call the config method and to follow Gatsby's pattern we're gonna use dotenv.development instead of like just a plain .env file.
[00:07:40] And to make sure the .env pick set up, we do .env.process.env.NODE_ENV, in that way what will happen is when we're in development mode, it will pick up this .env.development file. And when you're in production mode, you will have to add the same keys that are in this .Example, you'll just add this to whatever your deploy pipeline is.
[00:08:06] So if you're using Nullify, you'll only did declare environment variables to add them there Travis Jenkins, whatever you're using, you would just set those environment variables up so they're available during the build. Once we have these, we can use them, let's see. Cloud name so Then we can get the API key.
[00:08:34] Process.env API_Key. And then one more for API_SECRET. Okay. Which those configured we are able to actually get files uploaded. To Cloudinary and we'll be able to see the result of that in our GraphQL there. So let's start this up, yarn workspace negronis develop.
>> Jason Lengstorf: Okay, and so the way that that transformer works is that during the build it will just upload images from the file system to Cloudinary.
[00:09:28] And then it gets back in asset name, and then based on that asset name, Cloudinary URLs are, you configure everything in the URL itself so we're able to say give it to me with 200, with 400, with 600, and that allows us to set up responsive images with sore sets.
[00:09:48] It's probably just easier if I just show you how it works. So let's look at the GraphiQL layer and we can clear this out, and so we can see now that we've got all CloudinaryAsset. And if I go into the nodes, we can see that we've got fixed and fluid, fixed width is a Gatsby image Convention for setting images that never change in width.
[00:10:10] So if you have an avatar, for example, that's always going to be 40 pixels wide, you would use fixed at 40 pixels wide and that way the image comes out, optimized for that width. If you use fluid, fluid is for images that will scale depending on the viewport.
[00:10:25] So if you're doing like a banner image, you wanna use fluid because as the viewport gets wider or narrower, you only wanna be showing an image that's big enough for the current size of the viewport. You don't wanna have like a 1,600 pixel image squish down to a 300 pixel viewport on a feature phone, it's a lot of wasted bandwidth.
[00:10:44] So, if we get into these nodes, let's get into fluid and let's just take a look at the source. So, from the image that we uploaded, we can see here that we've got a whole array of image asset pass back and they come in at 200 pixels wide, 461, 646, and 650 because we've set 650 as our max width.
[00:11:12] So, let's just take a look at what one of these, it looks like.
>> Jason Lengstorf: And this is kind of where Cloundinary is really fascinating because you can just control all of these different things. So if I set this to 800, the image will come back much bigger, if I set it to Like a different aspect ratio so let's say I want it to be an aspect ratio of 16 by 9.
[00:11:40]
>> Jason Lengstorf: I put that in the wrong place, let's move it over here, aspect ratio of 16 by 9. So we can just add any of these transformations that we want, and it will kinda clean that stuff up for us so we're able to go through and kinda add the transformations as we see fit.
[00:11:59] And Cloudinary handles that for us on the fly, we don't have to manage the, different asset generation, it just does it for us. And this has a ton of really advanced features that I'm not gonna get into today, I'd encourage you to go explore the Cloudinary dots. You can do things like watermark your images, you can mess with the colors, you can do SVG tracing, you can find faces, you can blur out faces actually really, really powerful stuff, it's a very cool API.
[00:12:27] But once we have this, once we're able to actually get this, then we can start using it in our site