Building a blog with React and Next.js is one of the most common use cases for modern web development. But where you store and manage your content matters just as much as the frontend you choose.

In this tutorial, you'll learn how to build a fast, production-ready React blog using the Next.js App Router and Cosmic as your headless CMS.

Want to skip ahead? Grab the free Simple React Blog template and deploy in minutes.

Why Use a Headless CMS for a React Blog?

Managing blog content directly in your codebase works fine for a handful of posts, but it breaks down fast. Markdown files scattered across a repo, no visual editing interface, and every content update requiring a developer and a deployment are all pain points that accumulate quickly.

A headless CMS solves this by separating your content layer from your presentation layer. You manage posts, authors, and categories in a structured dashboard. Your Next.js app fetches that content via the REST API at build time or on demand. Non-technical editors can publish without touching code, and developers stay focused on the frontend.

Cosmic gives you a clean API, a TypeScript SDK, a generous free tier, and zero infrastructure to manage.

Prerequisites

Before you start, you'll need:

• Node.js 18 or later
• A free Cosmic account
• Basic familiarity with React and TypeScript

Step 1: Set Up Your Cosmic Bucket and Content Model

After signing up for a free Cosmic account, create a new bucket. You can start from the Simple React Blog template to get a pre-configured bucket with sample content and a ready-to-deploy Next.js app, or follow along manually.

Creating a Blog Posts Object Type

In your Cosmic dashboard, navigate to Object Types and create a new type called blog-posts. Add the following metafields:

• Title - Text (built-in)
• Slug - Text (built-in)
• Cover Image - File (image)
• Excerpt - Textarea
• Content - Markdown
• Published Date - Date
• Author - Text

Once saved, create a few sample posts so you have content to query during development.

Get Your API Credentials

Go to Settings > API Keys in your bucket. You'll need:

• Bucket Slug (e.g. my-blog-production)
• Read Key (for public content fetching)

Save these as environment variables.

Step 2: Create a New Next.js App

npx create-next-app@latest my-blog --typescript --app
cd my-blog

Install the Cosmic SDK:

npm install @cosmicjs/sdk

Create a .env.local file:

COSMIC_BUCKET_SLUG=your-bucket-slug
COSMIC_READ_KEY=your-read-key

Step 3: Initialize the Cosmic Client

Create a shared Cosmic client at lib/cosmic.ts:

import { createBucketClient } from '@cosmicjs/sdk'

export const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG as string,
  readKey: process.env.COSMIC_READ_KEY as string,
})

Step 4: Define Your TypeScript Types

// types/post.ts
export interface Post {
  id: string
  slug: string
  title: string
  metadata: {
    content: string
    excerpt: string
    cover_image: { imgix_url: string }
    published_date: string
    author: string
  }
}

Step 5: Fetch Posts from the Cosmic REST API

Fetch All Posts (Blog Index)

const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts' })
  .props(['id', 'slug', 'title', 'metadata'])
  .depth(1)

Fetch a Single Post by Slug

const { object: post } = await cosmic.objects
  .findOne({ type: 'blog-posts', slug: params.slug })
  .props(['id', 'slug', 'title', 'metadata'])
  .depth(1)

Step 6: Build the Blog with Next.js App Router

Blog Index Page (app/blog/page.tsx)

import { cosmic } from '@/lib/cosmic'
import Link from 'next/link'

export default async function BlogPage() {
  const { objects: posts } = await cosmic.objects
    .find({ type: 'blog-posts' })
    .props(['id', 'slug', 'title', 'metadata'])

  return (
    <main>
      <h1>Blog</h1>
      {posts.map((post) => (
        <article key={post.id}>
          <Link href={`/blog/${post.slug}`}>
            <h2>{post.title}</h2>
          </Link>
          <p>{post.metadata.excerpt}</p>
        </article>
      ))}
    </main>
  )
}

Dynamic Post Page (app/blog/[slug]/page.tsx)

import { cosmic } from '@/lib/cosmic'
import { marked } from 'marked'

export async function generateStaticParams() {
  const { objects: posts } = await cosmic.objects
    .find({ type: 'blog-posts' })
    .props(['slug'])
  return posts.map((post) => ({ slug: post.slug }))
}

export default async function PostPage({ params }: { params: { slug: string } }) {
  const { object: post } = await cosmic.objects
    .findOne({ type: 'blog-posts', slug: params.slug })
    .props(['title', 'metadata'])

  const html = marked(post.metadata.content)

  return (
    <main>
      <h1>{post.title}</h1>
      <img src={`${post.metadata.cover_image.imgix_url}?w=1200&auto=format`} alt={post.title} />
      <div dangerouslySetInnerHTML={{ __html: html }} />
    </main>
  )
}

Step 7: Optimize Images with Imgix

Cosmic stores all media through Imgix, a powerful image CDN. Append transformation parameters directly to any media URL:

https://imgix.cosmicjs.com/your-image.jpg?w=800&auto=format&q=80&fit=crop

Common params:

• w= sets width
• auto=format serves WebP to supported browsers
• q=80 reduces file size
• fit=crop crops to exact dimensions

Step 8: Deploy to Vercel

1. Push your project to a GitHub repository
2. Go to vercel.com and import the repo
3. Add your environment variables under Settings > Environment Variables:
   • COSMIC_BUCKET_SLUG
   • COSMIC_READ_KEY
4. Click Deploy

Vercel will detect Next.js automatically, build your app, and give you a live URL in under a minute.

Enable On-Demand Revalidation (Optional)

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache'
import { NextRequest } from 'next/server'

export async function POST(request: NextRequest) {
  revalidatePath('/blog')
  return Response.json({ revalidated: true })
}

Then configure a Cosmic webhook to call this endpoint whenever a post is published.

What You've Built

• A Next.js App Router project with TypeScript
• A Cosmic bucket with a structured content model
• Server-side data fetching via the @cosmicjs/sdk
• Static pre-rendering with generateStaticParams
• Imgix-powered image optimization
• Live on Vercel with optional on-demand revalidation

Your editors can log into the Cosmic dashboard and publish new posts without touching your codebase. Your readers get a fast, statically rendered experience. And your SEO improves because every post is pre-rendered HTML at build time.

Start with the Free Template

Don't want to build from scratch? The Simple React Blog template gives you everything in this tutorial, already wired up and ready to deploy with one click.

Get the free React blog template

Start building free

Have questions or want to talk through your project? Book a quick intro call with the Cosmic team.