In web development, combining the flexibility of headless CMS with modern frontend frameworks and asset management tools is essential for building scalable, high-performance websites.
This is a two-part blog post that will walk through building a website using headless WordPress, Astro, WPGraphQL, Advanced Custom Fields, and Cloudinary. We’ll combine the flexibility of a decoupled CMS with the speed of Astro’s static site generation and Cloudinary’s media optimization.
By the end of this tutorial, you’ll have a better understanding and overall foundational setup that leverages the strengths of each technology to deliver optimized media-rich content. You’ll also have an understanding of the flexibility and developer-friendly experience of headless and decoupled architecture.
- Headless WordPress and why it’s a good fit for modern web projects.
- How Astro complements headless WordPress to deliver fast, static sites.
- The role Cloudinary plays in managing and delivering optimized media assets.
- Step-by-step instructions for connecting Astro, WordPress, WPGraphQL, and Cloudinary.
Before we begin, make sure you have:
- WordPress. For this blog post, I used the free Local tool but you can use any WP install you want.
- Node.js and npm. Installed on your development machine.
- A Cloudinary Account. I used the samples folder for this blog post.
Headless WordPress decouples the frontend from the backend. In a traditional setup, WordPress handles both content management and rendering through PHP templates. In a headless architecture, WordPress solely manages content while the frontend is handled by frameworks like Astro, which pull data from WordPress via APIs.
Using headless WordPress offers several advantages, including:
- Enhanced performance. By decoupling the frontend from the backend, you allow WordPress to focus solely on the content database and API interactions. This setup can lead to faster load times and improved responsiveness, as the API-driven approach optimizes data delivery and reduces overhead.
- Omnichannel experiences. Without a single frontend, headless WordPress can seamlessly integrate with various platforms and technologies. This means you can publish and display content across multiple channels simultaneously, such as websites, mobile apps, and even digital kiosks, allowing for a unified and versatile content distribution strategy.
- Improved security. Headless setups, especially static sites, eliminate traditional backend vulnerabilities since there’s no exposed database. This significantly reduces the risk of common security threats associated with WordPress, such as SQL injection attacks, making your content safer from potential breaches.
It’s important to note that headless WordPress requires a solid understanding of web development. Additionally, managing and maintaining a headless setup can be more complex than a standard WordPress installation, as it involves handling both the content management system and the separate frontend technology stack.
Astro is a modern, innovative framework designed for content-driven websites. It allows you to bring in components from frameworks like React, Vue, and Svelte, but the primary output is static HTML, which loads quickly and performs well.
Astro is a great fit for headless WordPress because it can render static pages, reducing server load and speeding up your website. Astro’s flexibility lets you dynamically fetch content from APIs (like WPGraphQL), and it’s excellent at handling content-heavy sites with media assets provided by Cloudinary.
Cloudinary is a cloud-based media management solution that optimizes and delivers images, videos, and other resources efficiently. When combined with a headless setup, Cloudinary ensures that your website loads media in the most optimized form, enhancing performance. Here are some of the many features Cloudinary has that we will utilize:
- Image and video optimization. Cloudinary automatically delivers media in the optimal format for the requesting device.
- Asset management. Organize and manage your assets with versioning and automatic optimization features.
- Transformation. Cloudinary allows you to dynamically resize, crop, and apply filters to media assets with URL-based transformations.
- Easy WordPress integration. Cloudinary has a plugin in its ecosystem for WordPress that automates the connection and configuration between the two platforms
Let’s dive in and create a site that utilizes all the technology of Cloudinary, WordPress, WPGraphQL, and Astro.
The first thing we need to do is set up our WordPress install to become a headless CMS.
- Install WPGraphQL Plugin. Go to your WordPress admin, navigate to Plugins > Add New Plugin, and install the search input bar, search for WPGraphQL, ACF, WPGraphQL for ACF, and Cloudinary.
- Activate and install all these plugins. Here’s what each of these plugins do respectively:
- WPGraphQL Plugin. This turns your WP install into a headless CMS by exposing your content via GraphQL API
- ACF. ACF will allow you to add custom fields to your posts.
- WPGraphQL for ACF. WPGraphQL for ACF ensures that these custom fields are available in your GraphQL schema.
- The Cloudinary Plugin. This will make the integration from Cloudinary into WordPress seamless and without heavy lifting.
After you download all four plugins, this is what your plugins page should look like:
Now that we have all the plugins activated, we’re ready for the next step.
To ensure that the correct media is displayed with the corresponding post, we need a way to associate each post with its corresponding Cloudinary asset. This is where the power and fun of decoupled and API driven development comes in. The ability to take different platforms and APIs and combine them together give you the flexibility no other tech stack can.
Since we downloaded the ACF plugin as well as its extension for WPGraphQL, we can now create a custom field in the native Post type of WordPress.
In your WordPress admin, navigate to ACF > Field Groups and you should have a page that looks like this:
At the top of the screen near the Field Groups heading, click +Add New and you should see this page:
The first input box is the Field Group Title. This is what will appear on the Title column within the Field Groups page. For this blog post, I named it “cloudinary public id”.
The second box is a drop-down and it’s what data type you want the field to be. This will just be a simple string text so selecting text is fine. The third box is the Field Label, which is the name that will appear on the EDIT page. The last input we need to fill out is Field Name and this is the name of the actual field itself.
After you fill the fields out, scroll down until you see the Settings section. You need to do two things here. First, make sure your rules are set for your field group. In this case, we want to show this field group if the Post Type is Post:
The second thing is to click the GraphQL tab and make sure this shows in GraphQL:
We’re all set on this section. The last thing we need to do is set our permalinks.
WordPress offers you the ability to create a custom URL structure for your permalinks and archives. Custom URL structures can improve the aesthetics, usability, and forward-compatibility of your links. In this blog post, we’ll go by Post name.
Navigate to Settings > Permalinks on the main hamburger menu from your WordPress admin. You should see this page:
Check Post name. Then scroll to the bottom of the page and click Save Changes. We’re done setting up our WordPress backend! Let’s move on to our Astro frontend.
For this section, we need to make sure that we have assets to load into the frontend and that we grab those public ids connected to each asset.
Log in to your Cloudinary account and navigate to Media Library > Folders > Samples > Landscapes and you should see a page like this:
(Just a note, you can use whatever folder you own that contains your assets you wish to use for this blog post. I’m just using the default landscape folder.)
Once you’re on your page that contains the assets, click any of the images to go into its asset detail page:
Focusing on the top left corner of the page, you’ll see the Cloudinary public id, which is the public id tied to the image you just clicked. You want to copy and save the entire path of the name. So in this image the public id would be “samples/landscapes/beach-boat”. Go ahead and copy your public id and then save them somewhere. We’ll need them in the next section.
Head back over to your WordPress admin. In your WP admin, navigate to Posts. Click any post you want to edit. You should have a page that looks like this:
At the bottom of the screen, you should be able to see the custom field you created. This is where you need to insert the Cloudinary public id you saved from your Cloudinary account. In this example, the id related to my asset is “samples/landscapes/landscape-panorama”. This custom field will allow WordPress and Cloudinary to connect and link the asset together.
Let’s make sure this works in WPGraphQL. Go to your GraphQL IDE at the top of the page and click it to reveal the IDE. Paste this query in the IDE to test:
query GetPosts {
posts {
nodes {
title
uri
cloudinaryAsset{
cloudinaryPublicId
}
}
}
}Press play to get the response, and you should get this JSON back:
Awesome! This works! We’re getting the custom field we made back.
We set up our WordPress backend to be a headless CMS with the custom field we needed to connect and link to our Cloudinary assets. In Part 2, we’ll spin up our Astro frontend, configure it with Cloudinary and WPGraphQL, and link the two systems together.
If you found this blog post helpful and want to discuss it in more detail, head over to Cloudinary Community forum and its associated Discord.
