PrerequisitesSection titled Prerequisites
- An Astro project- If you’d like to start with a fresh Astro project, read the installation guide. This guide follows a simplified version of the Astro Headless CMS Theme with Tailwind CSS for styling.
- A Cosmic account and Bucket - Create a free Cosmic account if you don’t have one. After creating your account, you’ll be prompted to create a new empty project. There’s also a Simple Astro Blog template available (this is the same template as the Astro Headless CMS Theme) to automatically import all of the content used in this guide.
- Your Cosmic API keys - From your Cosmic dasboard, you will need to locate both the Bucket slug and Bucket read key in order to connect to Cosmic.
Integrating Cosmic with AstroSection titled Integrating Cosmic with Astro
Installing Necessary DependenciesSection titled Installing Necessary Dependencies
Configuring API KeysSection titled Configuring API Keys
.env file at the root of your Astro project (if it does not already exist). Add both the Bucket slug and Bucket read key available from your Cosmic dashboard as public environment variables.
Fetching Data from CosmicSection titled Fetching Data from Cosmic
Create a new file called
cosmic.js. Place this file inside of the
src/libfolder in your project.
Add the following code to fetch data from Cosmic using the SDK and your environment variables.
The example below creates a function called
getAllPosts()to fetch metadata from Cosmic
Read more about queries in the Cosmic documentation.
Import your query function in a
.astrocomponent. After fetching data, the results from the query can be used in your Astro template.
The following example shows fetching metadata from Cosmic
postsand passing these values as props to a
<Card />component to create a list of blog posts:
Building a Blog with Astro and CosmicSection titled Building a Blog with Astro and Cosmic
You can manage your Astro blog’s content using Cosmic and create webhooks to automatically redeploy your website when you update or add new content.
Cosmic Content ObjectsSection titled Cosmic Content Objects
The following instructions assume that you have an Object Type in Cosmic called posts. Each individual blog post is a
post that is defined in the Cosmic dashboard with the following Metafields:
- Text input - Author
- Image - Cover Image
- Repeater - Tags
- Text input - Title
- Text area - Excerpt
- Rich Text - Content
Displaying a List of Blog Posts in AstroSection titled Displaying a List of Blog Posts in Astro
Using the same data-fetching method as above, import the
getAllPosts() query from your script file and await the data. This function provides metadata about each
post which can be displayed dynamically.
The example below passes these values to a
<Card /> component to display a formatted list of blog posts:
Generating Individual Blog Posts with AstroSection titled Generating Individual Blog Posts with Astro
To generate an individual page with full content for each blog post, create a dynamic routing page at
This page will export a
getStaticPaths() function to generate a page route at the
slug returned from each
post object. This function is called at build time and generates and renders all of your blog posts at once.
To access your data from Cosmic:
- Query Cosmic inside of
getStaticPaths()to fetch data about each post and provide it to the function.
- Use each
post.slugas a route parameter, creating the URLs for each blog post.
- Return each
Astro.props, making the post data available to HTML template portion of the page component for rendering.
The HTML markup below uses various data from Cosmic, such as the post title, cover image, and the rich text content (full blog post content). Use set:html on the element displaying the rich text content from Cosmic to render HTML elements on the page exactly as fetched from Cosmic.
Publishing your siteSection titled Publishing your site
To deploy your website, visit the deployment guides and follow the instructions for your preferred hosting provider.
Rebuild on Cosmic content updatesSection titled Rebuild on Cosmic content updates
You can set up a webhook in Cosmic directly to trigger a redeploy of your site on your hosting platform (e.g. Vercel) whenever you update or add content Objects.
Under “Settings” > “webhooks”, add the URL endpoint from Vercel and select the Object Type you would like to trigger the webhook. Click “Add webhook” to save it.
NetlifySection titled Netlify
To set up a webhook in Netlify:
- Go to your site dashboard and click on Build & deploy.
- Under the Continuous Deployment tab, find the Build hooks section and click on Add build hook.
- Provide a name for your webhook and select the branch you want to trigger the build on. Click on Save and copy the generated URL.
VercelSection titled Vercel
To set up a webhook in Vercel:
- Go to your project dashboard and click on Settings.
- Under the Git tab, find the Deploy Hooks section.
- Provide a name for your webhook and the branch you want to trigger the build on. Click Add and copy the generated URL.