Forem: Tony Spiro

How We Built AI Agents Into a Headless CMS

Tony Spiro — Tue, 28 Apr 2026 22:13:43 +0000

Most AI features in a CMS are cosmetic. Autocomplete here. A "generate with AI" button there. Useful, sure, but they don't change how teams actually work.

We wanted to go further. We wanted the CMS to have its own team.

This post is a technical walkthrough of how we built four specialized AI agents directly into Cosmic, how they communicate, what they can actually do, and how you can chain them together into fully automated workflows.

The Problem We Were Solving

Every content team we talked to had a version of the same story: someone needed a page updated, a blog post published, or a feature shipped, and it was stuck in a queue. Not because anyone was lazy. Because developer time is finite and content operations compete with product work.

The answer wasn't a better editor. It was removing the dependency entirely.

The Four Agent Types

Cosmic ships with four purpose-built agent types. Each one is optimized for a specific domain.

1. Team Agent

The Team Agent lives in your messaging tools: Slack, WhatsApp, and Telegram. You define its persona, give it a goal, and it communicates with your team like a real colleague. Under the hood, it maintains persistent conversation memory, understands context across sessions, and can trigger actions in the CMS, your codebase, or third-party APIs based on natural language instructions.

Example use case: A content team member messages the agent in Slack: "Write a blog post about our new integration with Vercel and publish it as a draft for review." The Team Agent delegates to the Content Agent, monitors execution, and reports back in the thread.

2. Content Agent

The Content Agent is a CMS-native worker. It can:

Research topics by browsing the web
Generate text, images, and structured content
Create and update CMS objects
Auto-publish or queue content for human review
Run on a schedule or be triggered via webhook

It operates against your existing content models, so it understands your schema, your object types, and your metadata structure.

3. Code Agent

The Code Agent connects to your GitHub repository and can:

Read the full file tree and specific files
Write new features or fix bugs in your codebase
Commit changes to branches
Open pull requests automatically
Respond to code-related tasks described in plain language

This is where things get interesting for developer teams. A PM can say "add a newsletter signup form to the homepage" and the Code Agent will find the right files, write the component, create the content model in Cosmic to save newsletter subscribers, commit it, and open a PR for review.

4. Computer Use Agent

The Computer Use Agent operates a real browser using visual AI. It can:

Navigate websites and interact with UI elements
Record demo videos
Extract structured data from any page
Cross-post media between platforms
Run visual QA on deployed pages
Fill out and submit forms with dynamic input handling
Authenticate into protected areas using secure login flows

This is the agent type that most surprises people. It's not scraping HTML, it's actually looking at the screen and clicking things, the same way a human would.

Chaining Agents Into Workflows

The real power comes when you chain agents together. Cosmic Workflows let you build multi-step automations that run in sequence or parallel, on a schedule or triggered by a webhook.

Here's an example workflow for launching an e-commerce site:

Traditional timeline for this: 2 to 3 weeks. With Cosmic Workflows: approximately 20 minutes.

The Technical Architecture

A few implementation details worth knowing:

REST API. All agent interactions with the CMS go through Cosmic's REST API, which returns responses in under 100ms. The TypeScript SDK wraps the API cleanly, and the CLI and MCP Server give agents additional surfaces to work with.

Framework-agnostic. The agents don't care what frontend you're using. They've been tested against Next.js, React, Vue, Nuxt, Astro, Remix, and Svelte.

Scheduling and webhooks. Content Agents and Workflows can be set to run on a cron schedule or triggered via incoming webhook. This means you can wire them into any external event: a new Stripe payment, a GitHub push, a form submission.

Memory modes. Team Agents support both session memory (reset per conversation) and persistent memory (retained across all conversations). Persistent memory is what makes a Team Agent feel like an actual team member over time.

What This Looks Like In Practice

FINN, the car subscription platform, has been using Cosmic to reduce their dependency on developer time for content changes. Their co-founder put it clearly:

"Cosmic is: us never having to ask a developer to change anything on the backend of our website." - Maximilian Wuhr, Co-Founder at FINN

With agents, that same principle extends to code, QA, and content operations, running autonomously around the clock.

Getting Started

Cosmic is free to start, no credit card required.

Free: $0/month - 1 Bucket, 2 team members, 1,000 Objects
Builder: $49/month - 2 Buckets, 3 team members, 5,000 Objects
Team: $299/month - 3 Buckets, 5 team members, 20,000 Objects
Business: $499/month - 5 Buckets, 10 team members, 50,000 Objects

You can explore the agents and workflows at cosmicjs.com/ai. If you want to talk through what this could look like for your specific stack, book a quick call with Tony.

Cosmic Agents vs Sanity Agent Context vs Hygraph AI: A Real Comparison

Tony Spiro — Mon, 27 Apr 2026 18:25:04 +0000

The phrase "AI-powered CMS" has become meaningless. Every headless CMS vendor is using it. The real question is: what does the AI actually do?

Cosmic, Sanity, and Hygraph are three of the most actively developed headless CMS platforms in 2026. All three are investing in AI. But their approaches are categorically different, and the distinction matters for how you build.

This comparison looks at what each platform's AI actually does, where it stops, and which approach fits what kind of team.

What We're Comparing

Cosmic: Four distinct agent types (Team, Content, Code, Computer Use) that operate across your entire stack
Sanity Agent Context: A structured content delivery layer for external AI agents, plus the Content Agent for content operations
Hygraph: AI-assisted content features (generation, translation, enrichment) built into the editorial workflow, with no native agent product

These are not equivalent products doing the same thing at different price points. They represent three distinct philosophies about where AI belongs in a content platform.

Cosmic: Agents That Work Across Your Stack

Cosmic ships four agent types that operate at different layers of your development workflow:

Team Agents

Live in Slack, WhatsApp, and Telegram. They have persistent memory, custom personas, and configurable goals. A Team Agent can be your content lead, a growth assistant, a support agent, or anything else your team needs. They participate in your actual communication channels, receive messages, respond to them, and maintain context across conversations.

Content Agents

Generate and manage CMS content: blog posts, landing pages, AI images, AI video. They run on schedules, respond to webhooks, and chain into multi-step workflows. A Content Agent can publish a weekly roundup, generate product descriptions at scale, or update metadata across hundreds of objects.

Code Agents

Connect directly to GitHub repositories. They create branches, commit code, build features, fix bugs, and open pull requests. A Code Agent can receive a feature request in Slack and deliver a working pull request to your repository. This is not a content tool. It is a software development tool built into a CMS platform.

Computer Use Agents

Control browsers using visual AI. They record demo videos, extract data from web pages, cross-post media, and automate any browser-based workflow.

All four agent types chain together in Workflows. A single workflow can: generate content with a Content Agent, build a feature in GitHub with a Code Agent, and test the result with a Computer Use Agent.

The key distinction: Cosmic agents are not features inside a CMS dashboard. They are autonomous team members that operate across your content, codebase, and communication channels.

Sanity: Agent Context + Content Agent

Sanity's AI story has two distinct parts worth separating.

Agent Context

Agent Context is Sanity's framework for making your CMS content available to external AI agents via MCP. It provides semantic search, GROQ + semantic query combination, editorial access controls, and real-time sync.

Agent Context is infrastructure for other people's agents to use your Sanity content. It is not Sanity building agents that act on your behalf.

Content Agent

Sanity's Content Agent is focused on content operations inside the CMS: bulk edits across thousands of documents, content audits, bulk replace across large document sets, and web search to identify content gaps.

The scope: Sanity's Content Agent stays inside the CMS. It does not write application code, touch your GitHub repository, create branches, open pull requests, or deploy software.

Hygraph: AI Features, Not AI Agents

Hygraph offers AI-assisted content features built into the editorial and content operations workflow. There is no dedicated Hygraph AI agent product.

What Hygraph does with AI:

Content enhancement: AI writing assistance, SEO optimization, metadata generation
Translation and localization: AI-powered translation with integrations like DeepL
Workflow automation: AI enrichment triggered by content changes via Agent Actions
Content auditing: Find stale pages, missing metadata, terminology drift
Federation: Query distributed content sources in real time

What Hygraph does not have:

Native AI agents that act autonomously on your behalf
Code agents that work in GitHub
Team agents that live in Slack or messaging channels
Multi-agent workflows that chain content, code, and browser automation

Side-by-Side: What Each Platform's AI Actually Does

Cosmic

Team agents in Slack, WhatsApp, Telegram: Yes
Content generation and management agents: Yes
Code agents (GitHub branches, PRs, commits): Yes
Computer Use / browser automation agents: Yes
Multi-agent chained Workflows: Yes
MCP Server: Yes (17 tools)
Agent Skills for Cursor, Claude Code, Copilot: Yes (16+ integrations)
Bulk content operations via AI: Yes
AI image generation: Yes
AI video generation: Yes

Sanity

Team agents in messaging channels: Slack only (via Content Agent)
Content generation and management agents: Yes (Content Agent)
Code agents (GitHub branches, PRs, commits): No
Computer Use / browser automation agents: No
Multi-agent chained Workflows: No
MCP Server: Yes
Bulk content operations via AI: Yes (Content Agent's core strength)
AI image generation: Yes (via Content Agent)
AI video generation: No
Structured content delivery for external agents (Agent Context): Yes

Hygraph

Team agents in messaging channels: No
Content generation and management agents: No (AI-assisted features, not agents)
Code agents (GitHub branches, PRs, commits): No
Computer Use / browser automation agents: No
Multi-agent chained Workflows: No
MCP Server: No dedicated product
Bulk content operations via AI: Yes (via Agent Actions, event-driven)
AI translation (field-by-field): Yes
AI content auditing: Yes
Content federation for AI use cases: Yes (a genuine differentiator)

The Practical Question: What Layer Do You Need AI to Operate In?

Choose Cosmic if:

You want AI that operates across your full stack: content, code, browser, and communication channels
Your team needs Code Agents creating branches and opening pull requests automatically
You want AI team members living in Slack, WhatsApp, or Telegram with persistent memory
Multi-agent Workflows that chain content generation, code deployment, and browser testing matter to you
You use Cursor, Claude Code, or GitHub Copilot and want your CMS context built into your IDE's AI assistant

Choose Sanity if:

Your primary AI use case is managing large volumes of existing content through conversation
You need bulk editing, content audits, and gap analysis across thousands of documents
Your team is editorial-first and the bottleneck is content operations, not engineering

Choose Hygraph if:

Your priority is AI-assisted content workflows inside a governed, enterprise content platform
Federation across distributed content sources is a real architectural need
You need field-level AI translation with schema integrity for a global content operation
You prefer AI that stays in an assisted, human-reviewed loop

Pricing Comparison (Verified April 2026)

Cosmic

Free: $0/month, 1 Bucket, 2 Team members, 1,000 Objects, 1 Team agent
Builder: $49/month, 2 Buckets, 3 Team members, 5,000 Objects, 3 Team agents
Team: $299/month, 3 Buckets, 5 Team members, 20,000 Objects, 10 Team agents
Business: $499/month, 5 Buckets, 10 Team members, 50,000 Objects, 25 Team agents
Additional users: $29/user/month
Free plan is genuinely free forever, no credit card required

Sanity

Free: $0/month, up to 20 seats, 10,000 documents
Growth: $15/seat/month, up to 50 seats, 25,000 documents
Enterprise: Custom
Notable: Dedicated support is a $799/month add-on. SSO is $1,399/month.

Hygraph

Free tier available
Scale and Enterprise tiers (contact for pricing)
Federation and advanced AI features are enterprise-tier

The Deeper Distinction: Infrastructure vs. Agents

Sanity's Agent Context takes a real infrastructure play: instead of building agents, they are making Sanity the best content source for whatever agents you or your users are building.

Cosmic's bet is different. The agents are not features on top of the CMS. They are the product. Cosmic's position is that the CMS of 2026 is not a place where humans store content and developers build on top of it. It is an agentic platform where AI team members participate in the full development and content lifecycle.

As FINN co-founder Maximilian Wuhr put it: "Cosmic is: us never having to ask a developer to change anything on the backend of our website."

That is one version of what agents unlock. The ceiling is much higher.

Frequently Asked Questions

Does Hygraph have AI agents?
Not in the autonomous sense. Hygraph offers AI-assisted content features and event-driven AI enrichment via Agent Actions. There is no Hygraph agent that acts independently across your stack.

What is Sanity Agent Context?
Agent Context is Sanity's infrastructure layer that makes your Sanity content available to external AI agents via MCP. It is not Sanity building agents on your behalf.

Can Cosmic agents write code?
Yes. Cosmic Code Agents connect to GitHub repositories, create branches, commit changes, and open pull requests. This is one of the core distinctions from both Sanity's and Hygraph's AI offerings.

Is Cosmic free?
Yes. Cosmic's Free plan is $0/month forever, no credit card required. It includes 1 Bucket, 2 Team members, 1,000 Objects, and 1 Team agent.

Ready to See Cosmic Agents in Action?

Why Headless CMS Is the Wrong Category

Tony Spiro — Sun, 26 Apr 2026 23:17:54 +0000

The term "headless CMS" made sense in 2015. It was a genuine breakthrough: decouple your content from your presentation layer, expose it through an API, and let developers build whatever frontend they wanted. It solved a real problem.

In 2026, calling a platform like Cosmic a "headless CMS" is like calling Vercel a "file host." Technically not wrong. Strategically, completely wrong.

The category has moved. The label hasn't. It's time to name what comes next.

1. The Original Headless CMS Promise (And Why It Was Right for Its Time)

Around 2013 to 2016, the web development world hit a wall. WordPress powered a third of the internet, but it also chained content to PHP templates and a rigid frontend. Enterprise teams were stuck in Sitecore and Adobe Experience Manager, paying six-figure licensing fees for systems that required specialists just to publish a blog post.

Headless CMS changed the contract. Content lived in a structured repository, accessible via API. Developers could build frontends in React, Vue, Angular, or anything else they chose. Content teams could work independently in a clean editor. The decoupling was real and valuable.

Platforms like Contentful (founded 2013) and later Sanity, Storyblok, and Prismic built strong businesses on this premise. The market validated them. According to Grand View Research, the headless CMS market is worth $2 to $4 billion today and is projected to grow to $6 billion or more by 2033.

The problem is not that headless CMS failed. The problem is that it succeeded, and then the world kept moving.

2. What Developer Teams Actually Need in 2026

Talk to any engineering lead at a modern product company and ask them what they need from their content infrastructure. You will not hear "a better API for structured content." You will hear something like this:

We need our marketing team to launch new landing pages without filing a Jira ticket.
We need our AI agents to be able to read and write content programmatically.
We need our content workflows to trigger downstream actions: Slack notifications, data syncs, deployment pipelines.
We need our editors to work in Slack or WhatsApp, not a separate dashboard.
We need our platform to handle the full lifecycle: create, publish, personalize, and retire content.

This is not a content management problem. It is a content infrastructure problem. And content infrastructure in 2026 looks nothing like a headless CMS from 2016.

The broader composable content and modern CMS market is estimated at $10 to $25 billion by MarketsandMarkets. Teams that limit their thinking to "headless CMS" are scoping themselves into a shrinking corner of a much larger map.

3. The Category Convergence Happening Right Now

Something interesting is happening across the developer tools landscape. The clean category lines that existed five years ago are dissolving.

CMS platforms are becoming dev platforms. Contentful launched an app framework. Sanity built a structured content operating system. Storyblok added visual editing.
Dev platforms are becoming content platforms. Vercel launched CMS integrations. Netlify acquired multiple CMS products. Cloudflare Pages added content workflows.
AI tooling is collapsing into both. Large language models need structured content to stay grounded. AI agents need APIs to read and write content programmatically.

The result: every serious platform is building toward the same destination. The companies that still describe themselves primarily by their 2016 category name are telling you something about their product roadmap thinking.

4. Why the Wrong Category Label Is Costing Teams Money and Time

This is not just a semantics debate. Category labels drive buying decisions, and wrong labels create wrong criteria.

When a CTO goes to evaluate a "headless CMS," they bring a headless CMS checklist: API performance, content modeling flexibility, editor experience, pricing per seat. Legitimate criteria. But incomplete for 2026.

They are not asking:

Can AI agents in my team's Slack channel query and update this content without a human in the loop?
Can I build a full internal tool or customer-facing app on this platform, not just a marketing site?
Does this platform have an MCP Server so tools like Claude Code and Cursor can work directly with my content?
Can I extend the platform with Agent Skills, so my editors can trigger complex workflows from a chat interface?

When teams do not ask these questions, they end up buying a headless CMS and then separately buying an AI platform, a workflow tool, an internal tooling framework, and a handful of Zapier integrations to stitch it all together. The category label caused them to under-scope the problem.

5. What the New Category Looks Like

The new category does not have a consensus name yet. Here is what it includes:

Content infrastructure. Structured content models, a fast REST API and TypeScript SDK, global CDN delivery, media management. The table stakes headless CMS established. Still necessary, but no longer sufficient.

AI-native agents. Not AI bolted on top of a content editor. AI agents that are first-class members of your team. They live in Slack, WhatsApp, and Telegram. They can read content, write content, trigger workflows, and respond to natural language requests. They operate on schedules or respond to events.

Workflow automation. Multi-step automated processes that chain content operations, approvals, notifications, and external API calls into coherent pipelines. Native workflow execution, not a third-party integration layer.

Developer-first extensibility. An MCP Server that lets AI coding tools like Claude Code and Cursor interact directly with your content infrastructure. Agent Skills that make content operations available as composable building blocks for any AI assistant.

App platform capabilities. The ability to build not just content-driven websites but full applications on the same infrastructure. Content becomes data. The CMS becomes the backend.

This is not a feature list. It is a different mental model for what a content platform is.

6. Where Cosmic Fits in the New Map

Cosmic (YC W19) started as a headless CMS. It has the API performance, the content modeling, and the editor experience that enterprises require. Companies like FINN, Tripwire Interactive, Parque Explora, and Vuetify chose it and stayed because the fundamentals are solid.

FINN's co-founder Maximilian Wuhr put it directly: "Cosmic is: us never having to ask a developer to change anything on the backend of our website."

That outcome, non-technical teams operating independently, is the original headless CMS promise fulfilled.

But Cosmic has not stopped there. Today, Cosmic is an AI-powered content and app platform:

AI Agents in Slack, WhatsApp, and Telegram. Editors can request content, trigger updates, and get summaries without leaving their messaging app.
Workflows. Multi-step automated pipelines that orchestrate content operations, approvals, and integrations.
MCP Server. AI coding tools like Claude Code and Cursor can interact directly with your content.
Agent Skills for Cursor and Claude Code. Composable content operations available natively to the AI tools your developers already use.
REST API and TypeScript SDK. Battle-tested, fast, and developer-friendly.

The market segment Cosmic competes in is not a $4 billion headless CMS market. It is a $25 billion-plus content infrastructure and AI-powered app platform market.

Calling it a headless CMS is like calling Vercel a file host. Accurate at the edges. Completely wrong about what it is.

The category will be named. We're naming it now.

An Agentic Content Platform is not a headless CMS with AI bolted on. It is a platform where AI agents are first-class participants in every content operation: writing, editing, publishing, coding, deploying, measuring.

The companies that recognize this shift early will stop evaluating "headless CMS vendors" and start asking a different question: which platform lets my team move fastest when humans and agents are working together?

That is the question Cosmic is built to answer.

Ready to see what AI-powered content infrastructure looks like? Start free on Cosmic or book a demo to talk through what your stack could look like.

How to Migrate from Storyblok to Cosmic

Tony Spiro — Sun, 26 Apr 2026 23:11:31 +0000

A step-by-step guide for developers migrating from Storyblok to Cosmic: content model mapping, component-to-metafield conversion, media migration, API migration, and webhooks — with real TypeScript code examples.

Why Developers Are Migrating from Storyblok to Cosmic

Storyblok was a smart choice for teams who wanted a visual editor baked into their CMS. But as applications grow in complexity and AI becomes central to content operations, its limitations become harder to work around. Three pain points keep coming up in migration conversations:

Visual editor lock-in. Storyblok components are built around page presentation, which couples your content model to your frontend. When you need to reuse content across channels, that coupling becomes a bottleneck.

Pricing pressure. Seat fees, delivery limits, and add-on costs compound as teams grow. Budgeting for Storyblok at scale is unpredictable.

No native AI. Adding AI to a Storyblok workflow requires third-party integrations and significant custom engineering. Cosmic has AI Agents built in.

If any of those sound familiar, this guide will walk you through the full migration process: content model mapping, component-to-metafield conversion, media migration, API migration, and webhooks.

Before You Start: Understanding the Key Differences

Storyblok Concept	Cosmic Equivalent
Story	Object
Component/Block	Object Type + Metafields
Component Field	Metafield
Space	Bucket
Asset	Media
Datasource	Object Type (for structured reference data)
Webhook	Webhook (via add-on)

The most important conceptual shift: Storyblok organizes content around components on stories. Cosmic organizes content around Objects of a given Object Type. The result is more flexible — you're not constrained by what a visual editor can preview.

Step 1: Map Your Content Model

Start by auditing your Storyblok components. For each component, you'll create a corresponding Object Type in Cosmic with the right Metafields.

Field type mapping reference:

Storyblok richtext → Cosmic html-textarea or markdown
Storyblok asset → Cosmic file
Storyblok text → Cosmic text
Storyblok textarea → Cosmic textarea
Storyblok single select → Cosmic select
Storyblok multi select → Cosmic multi-select
Storyblok nested blocks → Cosmic relationship field or objects
Storyblok reference → Cosmic relationship field (object)

Step 2: Export Your Content from Storyblok

Use the Storyblok Management API to export your stories. You'll need your Storyblok API token.

const response = await fetch(
  `https://mapi.storyblok.com/v1/spaces/${SPACE_ID}/stories`,
  {
    headers: {
      Authorization: STORYBLOK_MANAGEMENT_TOKEN,
    },
  }
);
const { stories } = await response.json();

Step 3: Migrate Media Assets

Before importing content objects, migrate your media. Storyblok stores assets on their CDN; you'll need to re-upload them to Cosmic's media library.

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG,
  readKey: process.env.COSMIC_READ_KEY,
  writeKey: process.env.COSMIC_WRITE_KEY,
});

async function migrateAsset(storyblokUrl: string, filename: string) {
  const response = await fetch(storyblokUrl);
  const buffer = await response.arrayBuffer();
  const file = new File([buffer], filename);

  const { media } = await cosmic.media.insertOne({ media: file });
  return media.imgix_url;
}

Step 4: Import Content to Cosmic

With your content model mapped and media migrated, import your stories as Cosmic Objects using the JavaScript/TypeScript SDK.

async function importStory(story: StoryblokStory, mediaMap: Record<string, string>) {
  await cosmic.objects.insertOne({
    title: story.name,
    type: 'your-object-type-slug',
    status: story.published ? 'published' : 'draft',
    metadata: {
      content: story.content.body,
      image: mediaMap[story.content.image?.filename] || '',
      // map other fields as needed
    },
  });
}

Step 5: Update Your API Calls

Storyblok and Cosmic have different API patterns. Here's how to update your frontend code.

Before (Storyblok):

import { storyblokInit, apiPlugin } from '@storyblok/react';

storyblokInit({
  accessToken: process.env.STORYBLOK_TOKEN,
  use: [apiPlugin],
});

const { data } = await storyblokApi.get('cdn/stories', {
  version: 'published',
});

After (Cosmic):

import { createBucketClient } from '@cosmicjs/sdk';

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

const { objects } = await cosmic.objects.find({
  type: 'your-object-type-slug',
}).props('id,title,slug,metadata');

Important: Cosmic uses the REST API only. There is no GraphQL endpoint.

Step 6: Migrate Webhooks

If you use Storyblok webhooks to trigger builds or revalidation, you'll need to set up Cosmic webhooks. Cosmic webhooks are available as an add-on ($99/month, or included in the $199/month bundle). Once enabled, configure them in the Cosmic dashboard under Settings > Webhooks.

Migration Checklist

Content Model

[ ] Audit all Storyblok components and fields
[ ] Create corresponding Object Types in Cosmic dashboard
[ ] Map all field types (richtext → markdown, asset → file, etc.)
[ ] Test Object Type schemas with sample content

Media

[ ] Export list of all Storyblok assets
[ ] Run media migration script
[ ] Verify asset URLs in Cosmic media library
[ ] Build asset URL map for content import

Content

[ ] Export all Storyblok stories via Management API
[ ] Run content import script
[ ] Verify published/draft status is correct
[ ] Spot-check content in Cosmic dashboard

API Integration

[ ] Replace Storyblok SDK imports with Cosmic SDK
[ ] Update all API calls to use Cosmic REST API
[ ] Update environment variables
[ ] Test all content queries in development

Webhooks and Automation

[ ] Recreate Storyblok webhooks in Cosmic
[ ] Update webhook endpoints in your applications
[ ] Test build triggers and cache revalidation

Go Live

[ ] Run full content audit comparing Storyblok and Cosmic
[ ] Update DNS / CDN configuration if needed
[ ] Monitor error rates after launch
[ ] Deprecate Storyblok account once migration is confirmed

Supported Frameworks

Cosmic works with all major JavaScript frameworks:

Next.js — Full support including App Router and Pages Router
React — Works with any React setup
Vue — Full compatibility
Nuxt — Server-side rendering and static generation
Astro — Content collections and SSR
Remix — Loader-based data fetching
Svelte / SvelteKit — Full support
Gatsby — Static generation

The Cosmic JavaScript/TypeScript SDK works in any Node.js environment and in modern browsers.

This article was originally published on the Cosmic blog.

Headless CMS for TanStack Start: Build a Blog with Cosmic

Tony Spiro — Sat, 18 Apr 2026 19:08:53 +0000

You want SSR, fast routing, and a CMS your whole team can edit without touching code. Here's how to build that stack in under an hour.

TanStack Start pairs naturally with Cosmic: Start handles full-document SSR, streaming, and type-safe routing via Vite and TanStack Router, while Cosmic gives you a structured, API-first content layer your editors can use without a developer in the room. The result is a modern content stack that's fast to build, easy to maintain, and genuinely pleasant to work with.

This tutorial walks through building a content-driven TanStack Start blog powered by Cosmic. You'll fetch posts from Cosmic using the JavaScript SDK, render them with server functions, and have a working SSR blog in under 30 minutes.

Prerequisites

Node.js 18 or later
A free Cosmic account with a bucket set up
Basic familiarity with React and TypeScript

1. Create a TanStack Start Project

The fastest way to scaffold a new project is with the TanStack CLI:

npx create-tsrouter-app@latest my-cosmic-app --template start-basic
cd my-cosmic-app
npm install

This gives you a working TanStack Start app with file-based routing, SSR enabled, and Vite as the bundler.

2. Install the Cosmic SDK

npm install @cosmicjs/sdk

3. Configure Your Environment Variables

Create a .env file at the root of your project:

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

You can find both values in your Cosmic dashboard under Bucket > Settings > API Keys.

TanStack Start uses Vite under the hood. Server-side environment variables are accessed via process.env inside server functions. For client-side access, prefix with VITE_ — but keep your read key on the server only.

4. Create a Cosmic Client

Add a shared client file at src/lib/cosmic.ts:

import { createBucketClient } from '@cosmicjs/sdk'

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

5. Fetch Posts with a Server Function

TanStack Start's server functions run exclusively on the server, making them the right place to call external APIs and keep keys out of the client bundle.

Create src/server/posts.ts:

import { createServerFn } from '@tanstack/start'
import { cosmic } from '../lib/cosmic'

export type Post = {
  id: string
  title: string
  slug: string
  metadata: {
    teaser: string
    published_date: string
    image?: { imgix_url: string }
  }
}

export const fetchPosts = createServerFn({ method: 'GET' }).handler(
  async () => {
    const { objects } = await cosmic.objects
      .find({ type: 'blog-posts' })
      .props(['id', 'title', 'slug', 'metadata.teaser', 'metadata.published_date', 'metadata.image'])
      .limit(10)

    return objects as Post[]
  }
)

export const fetchPost = createServerFn({ method: 'GET' })
  .validator((slug: string) => slug)
  .handler(async ({ data: slug }) => {
    const { object } = await cosmic.objects
      .findOne({ type: 'blog-posts', slug })
      .props(['id', 'title', 'slug', 'metadata'])
      .depth(1)

    return object
  })

6. Create the Blog Index Route

TanStack Start uses file-based routing. Create src/routes/blog/index.tsx:

import { createFileRoute, Link } from '@tanstack/react-router'
import { fetchPosts } from '../../server/posts'

export const Route = createFileRoute('/blog/')({
  loader: () => fetchPosts(),
  component: BlogIndex,
})

function BlogIndex() {
  const posts = Route.useLoaderData()

  return (
    <main className="max-w-2xl mx-auto py-12 px-4">
      <h1 className="text-3xl font-bold mb-8">Blog</h1>
      <ul className="space-y-6">
        {posts.map((post) => (
          <li key={post.id}>
            <Link
              to="/blog/$slug"
              params={{ slug: post.slug }}
              className="group"
            >
              <h2 className="text-xl font-semibold group-hover:underline">
                {post.title}
              </h2>
              {post.metadata.teaser && (
                <p className="text-gray-600 mt-1">{post.metadata.teaser}</p>
              )}
              {post.metadata.published_date && (
                <time className="text-sm text-gray-400">
                  {new Date(post.metadata.published_date).toLocaleDateString()}
                </time>
              )}
            </Link>
          </li>
        ))}
      </ul>
    </main>
  )
}

7. Create the Post Detail Route

Install react-markdown for safe, component-based markdown rendering:

npm install react-markdown

Create src/routes/blog/$slug.tsx:

import { createFileRoute, notFound } from '@tanstack/react-router'
import ReactMarkdown from 'react-markdown'
import { fetchPost } from '../../server/posts'

export const Route = createFileRoute('/blog/$slug')({
  loader: async ({ params }) => {
    const post = await fetchPost({ data: params.slug })
    if (!post) throw notFound()
    return post
  },
  component: BlogPost,
})

function BlogPost() {
  const post = Route.useLoaderData()

  return (
    <main className="max-w-2xl mx-auto py-12 px-4">
      {post.metadata.image?.imgix_url && (
        <img
          src={`${post.metadata.image.imgix_url}?w=800&auto=format`}
          alt={post.title}
          className="w-full rounded-lg mb-8"
        />
      )}
      <h1 className="text-3xl font-bold mb-4">{post.title}</h1>
      {post.metadata.published_date && (
        <time className="text-sm text-gray-400 block mb-8">
          {new Date(post.metadata.published_date).toLocaleDateString()}
        </time>
      )}
      <div className="prose">
        <ReactMarkdown>{post.metadata.markdown_content || ''}</ReactMarkdown>
      </div>
    </main>
  )
}

8. Run the Dev Server

npm run dev

Open http://localhost:3000/blog and you should see your Cosmic posts rendered server-side via TanStack Start.

Deploy to Vercel

TanStack Start supports Vercel out of the box. From the project root:

npm install -g vercel
vercel

Add your environment variables in the Vercel dashboard under Project > Settings > Environment Variables:

COSMIC_BUCKET_SLUG
COSMIC_READ_KEY

Deploy and you're live.

What to Build Next

Localization: Cosmic's Localization add-on lets you manage content in multiple languages from the same bucket. Add a locale param to your SDK calls and TanStack Router handles the rest.
Webhooks: Trigger a Vercel redeploy automatically when editors publish new content in Cosmic. Set up a webhook in Cosmic pointing to your Vercel deploy hook URL.
Team Agent in Slack: Install a Cosmic Team Agent in your Slack workspace. Editors can publish, update, and query content from Slack without opening the dashboard.
Full-text search: Use the Cosmic REST API with a ?query= parameter to add search to your TanStack Start app without a separate search service.

Cosmic is an AI-powered headless CMS with a REST API, TypeScript SDK, and AI agents that live in Slack, WhatsApp, and Telegram. Start for free.

After years of working with dev and content teams, it was clear that one of the biggest bottlenecks holding businesses back from scaling their content ops and their businesses, is people. Agents change that.

Tony Spiro — Wed, 15 Apr 2026 02:38:12 +0000

Tony Spiro

Apr 14

The CMS is Dead. Long Live the CMS.

#cms #ai #webdev #javascript

Comments

5 min read

The CMS is Dead. Long Live the CMS.

Tony Spiro — Tue, 14 Apr 2026 17:37:40 +0000

I've spent decades working in web development, watching dev teams and content teams try to work together. They both want the same thing: ship faster, break less, keep the business moving. But somewhere between the content editor's request and the developer's deploy, everything slows down. The bottleneck was never really the software. It was people. Not bad people. Just people with competing priorities, full backlogs, and a finite number of hours.

That's the thing I kept coming back to when we were building Cosmic. The tools kept improving. The workflows stayed broken.

The Old World Had Real Problems Worth Solving

Monolithic CMS platforms, WordPress, Drupal, and the rest, were not bad ideas. They solved a genuine problem: let non-technical people publish content to the web without writing code. For the mid-2000s, that was revolutionary. But they came with a price. Content and presentation were coupled together. Templates were tangled up with data. Changing the design meant touching the CMS. Scaling to new channels meant ripping everything apart.

Developers were locked in, and so was everyone else. If you've ever been stuck in a legacy CMS, you know the feeling: every small change feels bigger than it should.

Headless was a real step forward. Decoupling content from presentation was the right call. Serving content over a REST API meant you could publish to a website, a mobile app, a smart display, and a voice interface from a single source of truth. That was genuinely useful.

But here's what headless didn't fix: almost everything still required a developer to do it. New content type? Developer. Schema update? Developer. New integration? Developer. Fix that broken field? Put in a ticket, get in the queue, wait your turn. The bottleneck didn't go away. It just moved upstream.

The Real Constraint Was Always Bandwidth

After years of working with dev and content teams, the pattern became impossible to ignore. The frustration wasn't with the CMS itself. It was with the overhead around it. Content teams would file tickets. Developers would prioritize against a dozen other things. Two weeks would pass. The content would go live, slightly wrong, slightly late. Everyone would shrug and move on.

This is what content teams actually want: they want to work without waiting. They want to change something and see it changed. They want to move at the speed of the idea, not the speed of the sprint.

Maximilian Wuhr, Co-Founder at FINN, put it simply: "Cosmic is: us never having to ask a developer to change anything on the backend of our website."

That sentence is the whole thesis. The goal was never a better editor UI. It was freedom from the queue. But even the best headless CMS, with the cleanest API and the most intuitive dashboard, can only do so much when humans are still doing all the work. Humans have calendars. Humans have meetings. Humans get sick and go on vacation and get pulled onto other projects. The constraint isn't the tool. It's the finite supply of people to operate it.

What AI Agents Actually Change

Here's the shift that I think most people in this industry are still underestimating: agents aren't a feature you add to a CMS. They're a rethink of who does the work.

"After years of working with dev and content teams, it was clear that one of the biggest bottlenecks holding businesses back from scaling their content ops and their businesses, is people. Agents change that, allowing you to leverage an on-demand and highly intelligent workforce to handle content, code, design, analytics, strategy, and much more."

Think about what that actually means in practice. An on-demand workforce doesn't have a backlog. It doesn't have competing priorities. It doesn't need a Jira ticket.

You message an agent in Slack. The draft appears in your CMS. You approve it, it publishes. No meeting. No handoff. No waiting.

You tell an agent to analyze last month's content performance and draft a brief for next quarter. It does it, cites real data, and drops it in your workspace. You review, revise, ship.

You ask an agent to update the schema for a new product launch. It builds the content model, tests it against your existing data, and flags any conflicts before you ever touch production.

This isn't AI as autocomplete. This is AI as a collaborator that operates at infrastructure level, always on, always available, working within the systems your team already uses.

Cosmic's AI agents live in Slack, WhatsApp, and Telegram because that's where your team already communicates. The agent meets you where you are. Need to automate a repeating content process end to end? That's what Cosmic Workflows are built for: chaining agents together so entire pipelines run without anyone babysitting them.

The CMS becomes the infrastructure. The agent becomes the operator.

The Category Didn't Die. It Grew Up.

I want to be precise about what I mean when I say the CMS is dead. I don't mean that content management is going away. I mean that the old model of a CMS, as a UI-first, human-operated, developer-gated tool, is reaching the end of its useful life.

The best CMS in 2026 is not the one with the most polished editor interface. It's not the one with the most integrations in a marketplace. It's the one with the best API, the best agent layer, and the infrastructure to support a workflow where intelligent systems are doing the heavy lifting.

Content infrastructure in 2026 means:

A clean, stable REST API that agents can read and write against without friction
A permissions model sophisticated enough to let agents operate safely
Native agent integrations, not bolted-on chat widgets, but actual AI collaborators embedded in the system
The flexibility to support any frontend, any framework, any channel, without locking you into a rendering layer you didn't choose

The CMS as a category is not dead. But the version of it that required a developer for every change, that made content teams wait in ticket queues, that treated AI as a content generation shortcut rather than a core architectural layer: that version is done.

What replaces it is content infrastructure built for an AI-native world. Infrastructure that treats agents as first-class operators. Infrastructure that gets out of the way and lets your team, human and AI alike, move at the speed the business actually needs.

We built Cosmic for that world. We think it's already here.

Ready to see what AI-native content infrastructure looks like in practice? Start free or book a conversation with Tony directly.

How to Migrate from Drupal to Cosmic

Tony Spiro — Sun, 12 Apr 2026 22:19:23 +0000

Drupal served a generation of content teams well. But between the PHP overhead, major-version upgrade cycles, and the complete absence of native AI capabilities, many teams are now making the move to a modern headless CMS. This guide walks you through migrating from Drupal to Cosmic step by step, with real TypeScript code you can run today.

Why Teams Are Leaving Drupal Now

Drupal 7 reached end-of-life in January 2025. That forced thousands of organizations into a choice: invest heavily in upgrading to Drupal 10, or use the moment as an opportunity to rethink the architecture entirely.

The case for moving on is strong:

Module sprawl and complexity. Most production Drupal sites run dozens of contrib modules. Each one is a maintenance burden and a potential security surface.
Dev-only content changes. Even simple schema changes, like adding a field to a content type, typically require a developer, a code deployment, and a cache flush.
No native AI. Drupal was designed long before LLMs. Every AI integration is a custom module or a fragile third-party connector.
Infrastructure overhead. A production Drupal site needs a server (or managed host), a MySQL/PostgreSQL database, and caching layers like Varnish or Redis.

Cosmic removes all of that. Fully managed cloud, REST API, TypeScript SDK, built-in AI Agents, and a visual schema builder. Let's move your content.

Drupal to Cosmic Concept Mapping

Before writing a single line of code, it helps to understand how Drupal's concepts translate to Cosmic's model:

Content Types = Object Types (defined in Cosmic's schema builder, no code required)
Nodes = Objects (each piece of content is an Object)
Fields = Metafields (text, number, date, file, select, relationship, and more)
Taxonomies = Select/multi-select metafields or related Objects
Media = Cosmic Media (imgix CDN - upload once, serve globally)
Views = REST API queries with filters
Modules = Integrations / Cosmic SDK
Roles & Permissions = Team member roles in Cosmic

Step-by-Step Migration Guide

Step 1: Audit Your Drupal Content Model

Before you export anything, document what you have. In Drupal, navigate to Structure > Content Types and list every content type. For each, note:

All field names, types, and cardinality (single vs. multiple values)
Which fields are required
Any taxonomy references
Any entity references (related content)

Create a spreadsheet mapping each Drupal content type and field to its Cosmic equivalent. This is your migration blueprint.

Step 2: Create Your Cosmic Object Types

Sign up at cosmicjs.com and create a new Bucket. For each Drupal content type, create a matching Object Type in Cosmic using the visual schema builder in the dashboard.

Field type mapping:

text_long / text_with_summary = Markdown or HTML-textarea metafield
integer / decimal = Number metafield
boolean = Switch metafield
datetime = Date metafield
image (with file) = File metafield
entity_reference (single) = Object metafield
entity_reference (multiple) = Objects metafield
list_string / taxonomy term reference = Select or Multi-select metafield

Step 3: Export Your Drupal Content

Enable Drupal's JSON:API module (included in Drupal 8.7+ core) if it isn't already active. Then export your nodes:

// Fetch all nodes of a given content type from Drupal's JSON:API
async function exportDrupalNodes(contentType: string) {
  const baseUrl = process.env.DRUPAL_BASE_URL
  let url = `${baseUrl}/jsonapi/node/${contentType}?page[limit]=50`
  const allNodes = []

  while (url) {
    const res = await fetch(url)
    const json = await res.json()
    allNodes.push(...json.data)
    url = json.links?.next?.href || null
  }

  return allNodes
}

For large datasets, paginate through all records and save them to local JSON files before importing.

Step 4: Import Content to Cosmic via the REST API

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  writeKey: process.env.COSMIC_WRITE_KEY!,
})

async function importNodes(nodes: any[], objectType: string) {
  const results = { success: 0, failed: 0, errors: [] as string[] }

  for (const node of nodes) {
    try {
      await cosmic.objects.insertOne({
        type: objectType,
        title: node.attributes.title,
        metadata: {
          body: node.attributes.body?.processed || '',
          summary: node.attributes.body?.summary || '',
          // Map additional fields here
        },
      })
      results.success++
    } catch (err: any) {
      results.failed++
      results.errors.push(`${node.attributes.title}: ${err.message}`)
    }
  }

  return results
}

Tips:

Run the import in batches of 50-100 objects at a time
Log successes and failures separately so you can re-run failures without duplicating successful imports

Step 5: Migrate Media Files

Drupal stores media files locally or on a CDN. Cosmic uses imgix for global media delivery.

async function migrateMedia(drupalFileUrl: string, fileName: string) {
  const cosmic = createBucketClient({
    bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
    writeKey: process.env.COSMIC_WRITE_KEY!,
  })

  // Fetch file from Drupal
  const fileRes = await fetch(drupalFileUrl)
  const fileBuffer = await fileRes.arrayBuffer()
  const blob = new Blob([fileBuffer])

  // Upload to Cosmic Media
  const { media } = await cosmic.media.insertOne({
    media: { data: blob, name: fileName },
  })

  return media.imgix_url // Ready to use with imgix transformations
}

Once uploaded to Cosmic, every image is automatically served through imgix with on-the-fly resizing, format conversion (WebP, AVIF), and global CDN delivery.

Step 6: Set Up Webhooks and Rebuild Your Frontend

Cosmic's webhook system lets you trigger rebuilds on your frontend whenever content changes. For a Next.js frontend:

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

export async function POST(req: NextRequest) {
  const secret = req.nextUrl.searchParams.get('secret')
  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ error: 'Invalid secret' }, { status: 401 })
  }

  revalidatePath('/', 'layout')
  return NextResponse.json({ revalidated: true })
}

Cosmic works with all major frontend frameworks: Next.js, React, Vue, Nuxt, Astro, Remix, and Svelte.

Step 7: Test, Redirect, and Go Live

Before flipping DNS:

Compare content counts between Drupal and Cosmic to verify completeness
Spot-check 10-20 objects across different content types
Verify all media URLs resolve via imgix
Test your frontend against the Cosmic API in a staging environment
Set up 301 redirects from old Drupal URLs to new paths
Monitor API response times (target: under 100ms)

Migration Checklist

[ ] Audit all Drupal content types and fields
[ ] Map Drupal fields to Cosmic metafield types
[ ] Create all Object Types in Cosmic
[ ] Export all Drupal nodes via JSON:API
[ ] Export all Drupal taxonomy terms
[ ] Export all media files and metadata
[ ] Import content to Cosmic via TypeScript SDK
[ ] Migrate media files to Cosmic Media (imgix)
[ ] Verify object counts match
[ ] Spot-check content for formatting issues
[ ] Build or adapt frontend to use Cosmic REST API
[ ] Set up webhooks for incremental rebuilds
[ ] Configure 301 redirects for all changed URLs
[ ] Test full site in staging
[ ] Flip DNS to new frontend
[ ] Monitor error rates and API latency post-launch
[ ] Decommission or archive Drupal server

What You Get on the Other Side

After migrating to Cosmic, your team gets:

A clean REST API with sub-100ms response times and 99.9% uptime SLA
TypeScript SDK and CLI for fast local development
Built-in AI Agents that live in Slack, WhatsApp, and Telegram
MCP Server for native AI tooling integration
imgix CDN for all media with on-the-fly transformations
A visual schema builder so editors can propose content model changes without involving a developer
No more major version migrations. Ever.

Originally published on cosmicjs.com

Build and deploy a Next.js ecommerce website in 5 steps

Tony Spiro — Thu, 02 May 2024 15:51:08 +0000

In this article, I'm going to show you how to build and deploy an ecommerce website in 5 steps. By leveraging the Cosmic React component library Blocks, we can build a high performance ecommerce website ready to accept product purchases in a matter of minutes. Let's go.

1. Install the Cosmic ecommerce Block

Start by installing a new Next.js app. Run the following command in your terminal application.

bunx create-next-app@latest cosmic-ecommerce && cd cosmic-ecommerce

Make sure to set the options to the following:

Next, log in to Cosmic and create a new empty Project.

Go to Project > Extensions and install the Cosmic Blocks extension. Find the ecommerce Block.

Follow the steps to install the Block content which includes content model and demo content.

Then run the command to install the ecommerce components in your codebase.

bunx @cosmicjs/blocks add ecommerce image-gallery

Create a new .env.local file and add your Cosmic API keys found in the Cosmic dashboard at Project > API keys:

# .env.local
COSMIC_BUCKET_SLUG=your_cosmic_bucket_slug
COSMIC_READ_KEY=your_cosmic_read_key
COSMIC_WRITE_KEY=your_cosmic_write_key

To create a shop page, add a new file located at app/shop/page.tsx with the following:

// app/shop/page.tsx
import { ProductList } from "@/cosmic/blocks/ecommerce/ProductList";
export default async function Shop() {
  return (
    <ProductList
      query={{ type: "products" }}
    />
  );
}

To create single product pages, add a new file located at app/shop/[slug]/page.tsx with the following:

// app/shop/[slug]/page.tsx
import { SingleProduct } from "@/cosmic/blocks/ecommerce/SingleProduct"
export default async function SingleProductPage({
  params,
  searchParams
}: {
    params: { slug: string }
    searchParams: {
      success?: string
    }
  }) {
  return (
    <SingleProduct
      query={{ slug: params.slug, type: "products" }}
      purchased={searchParams.success ? true : false}
    />
  );
}

Run the app to see the progress so far:

bun dev

You should see the store available at http://localhost:3000/shop (but not yet able to checkout with Stripe).

2. Configure Stripe

Next, we will enable checkout and payment processing through Stripe. First, install the Stripe clients with the following command:

bun add stripe @stripe/stripe-js

Add your Stripe API keys to the .env.local file. Find your Stripe API keys in the Stripe dashboard.

// .env.local
...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=change_to_your_stripe_public_key
STRIPE_SECRET_KEY=change_to_your_stripe_secret_key

Next, update your app/layout.tsx file to include the CartProvider to the layout. (Note: this assumes you've already added the Layout Block).

// app/layout.tsx
import "./globals.css";
import { Header } from "@/components/Header";
import { Footer } from "@/components/Footer";
import { CartProvider } from "@/cosmic/blocks/ecommerce/CartProvider";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CartProvider>
          <Header />
          {children}
          <Footer />
        </CartProvider>
      </body>
    </html>
  );
}

Next, let's add the checkout component to components/Header.tsx.

// components/Header.tsx
import Link from "next/link";
import { cosmic } from "@/cosmic/client";
import { NavMenu } from "@/cosmic/blocks/navigation-menu/NavMenu";
import { CheckOut } from "@/cosmic/blocks/ecommerce/CheckOut";

export async function Header() {
  // Header data
  const { object: settings } = await cosmic.objects
    .findOne({
      type: "global-settings",
      slug: "settings",
    })
    .props("metadata")
    .depth(1);

  return (
    <div className="space-x-4 sticky top-0 bg-white/20 dark:bg-black/20 backdrop-blur-lg py-2 w-full z-[9999]">
      <div className="m-auto flex items-center md:container justify-between pl-2 pr-4">
        <Link href="/">
          <img
            src={`${settings.metadata.logo.imgix_url}?w=500&auto=format,compression`}
            alt={settings.metadata.company}
            className="h-10 m-auto dark:hidden"
          />
          <img
            src={`${settings.metadata.dark_logo.imgix_url}?w=500&auto=format,compression`}
            alt={settings.metadata.company}
            className="h-10 m-auto hidden dark:block"
          />
        </Link>
        <NavMenu query={{ type: "navigation-menus", slug: "header" }} />
        <CheckOut className="ml-4" productPath={"/shop"} />
      </div>
    </div>
  );
}

Next, let's add the checkout API route to our Next.js app located at app/api/checkout/route.ts with the following:

// app/api/checkout/route.ts
import { type NextRequest, NextResponse } from "next/server";
const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);

export async function POST(request: NextRequest) {
  const res = await request.json();
  const stripe_product_ids = res.stripe_product_ids;
  try {
    let line_items = [];
    let mode = "payment";
    for (const stripe_product_id of stripe_product_ids) {
      const product = await stripe.products.retrieve(stripe_product_id);
      const price = await stripe.prices.retrieve(product.default_price);
      line_items.push({
        price: price.id,
        quantity: 1,
      });
      // If any items are recurring
      if (price.type === "recurring") mode = "subscription";
    }
    const session = await stripe.checkout.sessions.create({
      line_items,
      mode,
      success_url: `${res.redirect_url}/?success=true`,
      cancel_url: `${res.redirect_url}/?canceled=true`,
    });
    return Response.json({ url: session.url });
  } catch (err) {
    return NextResponse.json(err, { status: 500 });
  }
}

3. Install Stripe extension

Next, go to Project > Extensions in the Cosmic dashboard and install the Stripe Products Extension. This will enable the connection between the products in Cosmic and Stripe. After installing the extension to your Project, follow the steps to add your Stripe secret key to the extension configuration.

4. Add products to Stripe

After installing the Stripe Products Extension, you should now see a button on the Product page to add the product to Stripe.

Click this button to sync your Product data to Stripe including title, image, price, and option for recurring payments (subscription).

Next, go back to your app running locally and see that the checkout is now working on any product that has been connected with Stripe (you may need to refresh the page).

5. Deploy to your website hosting provider

Next, we'll deploy our ecommerce website to Vercel (which is a great choice to host your Next.js website). Other hosting options include Netlify and Render.

First, create a new git repository in GitHub and follow the steps to push your Next.js ecommerce website code.

After you have pushed your code to the repository, go to the Vercel dashboard and add a new project connected to the code repository you just created in GitHub. (Note: This requires you to enable Vercel to access your GitHub repository.)

Then add your environment variables located in your .env.local file. Tip: You can add the full contents of the .env.local file by copy / pasting it into the first field in the Vercel form.

Now deploy your code. 🚀

You should now see a production build of your ecommerce website ready to take payments for your products and services. 💰

Next steps

I hope you enjoyed this quick tutorial on building an ecommerce website with Cosmic Blocks, Stripe, and Vercel. Check out more Blocks to explore to help you build optimized web experiences faster.

If you have any questions, reach out to me on X (fka Twitter) or on the Cosmic Discord server.

Best Practices using React Server Components with a Headless CMS

Tony Spiro — Tue, 05 Dec 2023 15:33:48 +0000

Since React Server Components (RSCs) hit the scene, the concept of server-side rendering React has become a polarizing topic, garnering praise, skepticism as well as becoming the target of many developer jokes.

After exploring RSCs with Next.js (available since Next.js 13), I have to say that it offers quite a significant improvement to developer experience compared to pre-RSC Next.js especially when working with a headless CMS.

In this article, we’re going to cover best practices for using React Server Components along with a headless CMS. We’ll also cover when to use client-side components and how to best structure your websites and apps for efficient data fetching from a headless CMS, in our case Cosmic (learn more about Cosmic here). Alright, let’s get into it:

1. Install the template

First install a new Next.js 14 app (you will need bun installed)

bunx create-next-app cosmic-demo

Yes / No to the following:

✔ Would you like to use TypeScript? … No / Yes (Select Yes)
✔ Would you like to use ESLint? … No / Yes (Select Yes)
✔ Would you like to use Tailwind CSS? … No / Yes (Select Yes)
✔ Would you like to use `src/` directory? … No / Yes (Select No)
✔ Would you like to use App Router? (recommended) … No / Yes (Select Yes)
✔ Would you like to customize the default import alias (@/*)? … No / Yes (Select No)

Get in there and fire up this bad boy:

cd cosmic-demo
bun dev

You should now see the default template running at http://localhost:3000. It should look like this:

2. Copy + paste the Tailwind UI page example

To get up and running quickly, we’ll grab a Tailwind CSS UI demo page located here:

Make sure to select the React option:

Paste it into app/page.tsx. After saving, you’ll notice it throws an error because you cannot use lifecycle events such as useEffect() or state in a React Server Component.

So we'll need to remove the client-side code from this page and move it elsewhere. But before we do that, let's install the missing dependencies:

bun add @headlessui/react @heroicons/react

And let’s comment out the dark style in globals.css

@tailwind base;
@tailwind components;
@tailwind utilities;

/* :root {
  --foreground-rgb: 0, 0, 0;
  --background-start-rgb: 214, 219, 220;
  --background-end-rgb: 255, 255, 255;
}

@media (prefers-color-scheme: dark) {
  :root {
    --foreground-rgb: 255, 255, 255;
    --background-start-rgb: 0, 0, 0;
    --background-end-rgb: 0, 0, 0;
  }
}

body {
  color: rgb(var(--foreground-rgb));
  background: linear-gradient(
      to bottom,
      transparent,
      rgb(var(--background-end-rgb))
    )
    rgb(var(--background-start-rgb));
} */

3. Separate the components

Since we can't use any client-side functionality in RSCs (in our case the onClick event for opening the mobile drawer and useState hook which handles client-side state), we'll need to separate this functionality into client components.

Create a new folder titled components and add a file titled Header.tsx and put everything from the <header> tags into it along with the dependencies and state functions.

In Header.tsx add “use client” to the top of the file. You will see now we have client-side interactions in the nav on mobile:

But there's a problem: we don’t want to render the FULL navigation client-side because that would negatively impact SEO. Since only the mobile functionality needs to render client-side, we can put the mobile drawer into its own component.

Create a new file at components/MobileNav.tsx and move the mobile nav client code which includes the nav button and the <Dialog> component and any dependencies. We'll come back to this after we power up our React Server Components with dynamic content from the Cosmic CMS.

This gives us three component files:

app/page.tsx - RSC
components/Header.tsx - RSC
components/MobileNav.tsx - Client component

4. Add Cosmic power

Now that we have a separation between our server and client code, let’s add the Cosmic magic. In the Cosmic dashboard, create a new Project and new Object type titled Page with the following Metafields:

Headline - Text
Subheadline - Text
Hero - Image

Create a new Page in Cosmic titled Home and add any content you want.

Add the Cosmic JavaScript SDK with:

bun add @cosmicjs/sdk

Next add the a new file lib/cosmic.ts with the following (Go to Bucket > API keys to get your Bucket slug and read key).

// lib/cosmic.ts
import { createBucketClient } from "@cosmicjs/sdk";
export const cosmic = createBucketClient({
  bucketSlug: "YOUR_BUCKET_SLUG",
  readKey: "YOUR_BUCKET_READ_KEY",
});

Then in your app/page.tsx file add the following (note where we add the Cosmic-powered sections).

// app/page.tsx

import { cosmic } from "@/lib/cosmic";

export default async function Home() {
  // fetch Cosmic data
  const { object: page } = await cosmic.objects
    .findOne({
      type: "pages",
      slug: "home",
    })
    .props("metadata")
    .depth(1);

  return (
    <main>
      <div className="relative isolate px-6 pt-14 lg:px-8">
        <div
          className="absolute inset-x-0 -top-40 -z-10 transform-gpu overflow-hidden blur-3xl sm:-top-80"
          aria-hidden="true"
        >
          <div
            className="relative left-[calc(50%-11rem)] aspect-[1155/678] w-[36.125rem] -translate-x-1/2 rotate-[30deg] bg-gradient-to-tr from-[#ff80b5] to-[#9089fc] opacity-30 sm:left-[calc(50%-30rem)] sm:w-[72.1875rem]"
            style={{
              clipPath:
                "polygon(74.1% 44.1%, 100% 61.6%, 97.5% 26.9%, 85.5% 0.1%, 80.7% 2%, 72.5% 32.5%, 60.2% 62.4%, 52.4% 68.1%, 47.5% 58.3%, 45.2% 34.5%, 27.5% 76.7%, 0.1% 64.9%, 17.9% 100%, 27.6% 76.8%, 76.1% 97.7%, 74.1% 44.1%)",
            }}
          />
        </div>
        <div className="mx-auto max-w-2xl sm:py-48">
          <div className="hidden sm:mb-8 sm:flex sm:justify-center">
            <div className="relative rounded-full px-3 py-1 text-sm leading-6 text-gray-600 ring-1 ring-gray-900/10 hover:ring-gray-900/20">
              Announcing our next round of funding.{" "}
              <a href="#" className="font-semibold text-indigo-600">
                <span className="absolute inset-0" aria-hidden="true" />
                Read more <span aria-hidden="true">&rarr;</span>
              </a>
            </div>
          </div>
          <div className="text-center">
            <h1 className="text-4xl font-bold tracking-tight text-gray-900 sm:text-6xl">
              {page.metadata.headline}
            </h1>
            <p className="mt-6 text-lg leading-8 text-gray-600">
              {page.metadata.subheadline}
            </p>
            <div className="mt-10 flex items-center justify-center gap-x-6">
              <a
                href="#"
                className="rounded-md bg-indigo-600 px-3.5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600"
              >
                Get started
              </a>
              <a
                href="#"
                className="text-sm font-semibold leading-6 text-gray-900"
              >
                Learn more <span aria-hidden="true">→</span>
              </a>
            </div>
          </div>
        </div>
        <img src={page.metadata.hero.imgix_url} className="w-full" />
      </div>
    </main>
  );
}

Note here that we are exporting an async function which is unique to React Server Components, enabling us to use await cosmic.objects.findOne() to fetch our page from Cosmic!

The big takeaway: No need messing with getStaticProps, getServerSideProps, or getStaticPaths it Just Works™.

5. Adding the global header

You may now notice an issue: we lost our navigation. So let's add our global header back. Because we’ll want to have the header navigation show up globally on all pages, let’s add it to our app/layout.tsx file:

// app/layout.tsx

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";
import { Header } from "@/components/Header";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Header />
        {children}
      </body>
    </html>
  );
}

Next let’s add dynamic content to our nav elements. In the Cosmic dashboard, create a new Object type titled Nav with the following Metafields:

Items - Repeater
- Text - Text
- Link - Text
- New Tab - Switch (boolean)

Next create a new Object titled Header and add some content.

Then add the following to your components/Header.tsx file:

// components/Header.tsx

import Link from "next/link";
import { cosmic } from "@/lib/cosmic";
import { MobileNav } from "@/components/MobileNav";

export type ItemType = {
  text: string;
  link: string;
  new_tab: boolean;
};

export async function Header() {
  // fetch Cosmic data
  const { object: nav } = await cosmic.objects
    .findOne({
      type: "navs",
      slug: "header",
    })
    .props("metadata")
    .depth(1);

  return (
    <div className="bg-white">
      <header className="absolute inset-x-0 top-0 z-50">
        <nav
          className="flex items-center justify-between p-6 lg:px-8"
          aria-label="Global"
        >
          <div className="flex lg:flex-1">
            <Link href="/" className="-m-1.5 p-1.5">
              <span className="sr-only">Your Company</span>
              <img
                className="h-8 w-auto"
                src="https://tailwindui.com/img/logos/mark.svg?color=indigo&shade=600"
                alt=""
              />
            </Link>
          </div>
          <MobileNav items={nav.metadata.items} />
          <div className="hidden lg:flex lg:gap-x-12">
            {nav.metadata.items.map((item: ItemType) => (
              <Link
                key={item.text}
                href={item.link}
                className="text-sm font-semibold leading-6 text-gray-900"
                target={item.new_tab ? "_blank" : ""}
              >
                {item.text}
              </Link>
            ))}
          </div>
          <div className="hidden lg:flex lg:flex-1 lg:justify-end">
            <a
              href="#"
              className="text-sm font-semibold leading-6 text-gray-900"
            >
              Log in <span aria-hidden="true">&rarr;</span>
            </a>
          </div>
        </nav>
      </header>
    </div>
  );
}

Next add the following to your components/MobileNav.tsx file:

// components/MobileNav.tsx

"use client";

import Link from "next/link";
import { useState } from "react";
import { Dialog } from "@headlessui/react";
import { Bars3Icon, XMarkIcon } from "@heroicons/react/24/outline";
import { ItemType } from "@/components/Header";

export function MobileNav({ items }: { items: Item[] }) {
  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
  return (
    <>
      <div className="flex lg:hidden">
        <button
          type="button"
          className="-m-2.5 inline-flex items-center justify-center rounded-md p-2.5 text-gray-700"
          onClick={() => setMobileMenuOpen(true)}
        >
          <span className="sr-only">Open main menu</span>
          <Bars3Icon className="h-6 w-6" aria-hidden="true" />
        </button>
      </div>
      <Dialog
        as="div"
        className="lg:hidden"
        open={mobileMenuOpen}
        onClose={setMobileMenuOpen}
      >
        <div className="fixed inset-0 z-50" />
        <Dialog.Panel className="fixed inset-y-0 right-0 z-50 w-full overflow-y-auto bg-white px-6 py-6 sm:max-w-sm sm:ring-1 sm:ring-gray-900/10">
          <div className="flex items-center justify-between">
            <Link href="#" className="-m-1.5 p-1.5">
              <span className="sr-only">Your Company</span>
              <img
                className="h-8 w-auto"
                src="https://tailwindui.com/img/logos/mark.svg?color=indigo&shade=600"
                alt=""
              />
            </Link>
            <button
              type="button"
              className="-m-2.5 rounded-md p-2.5 text-gray-700"
              onClick={() => setMobileMenuOpen(false)}
            >
              <span className="sr-only">Close menu</span>
              <XMarkIcon className="h-6 w-6" aria-hidden="true" />
            </button>
          </div>
          <div className="mt-6 flow-root">
            <div className="-my-6 divide-y divide-gray-500/10">
              <div className="space-y-2 py-6">
                {items.map((item: ItemType) => (
                  <Link
                    key={item.text}
                    href={item.link}
                    className="-mx-3 block rounded-lg px-3 py-2 text-base font-semibold leading-7 text-gray-900 hover:bg-gray-50"
                    target={item.new_tab ? "_blank" : ""}
                  >
                    {item.text}
                  </Link>
                ))}
              </div>
              <div className="py-6">
                <Link
                  href="#"
                  className="-mx-3 block rounded-lg px-3 py-2.5 text-base font-semibold leading-7 text-gray-900 hover:bg-gray-50"
                >
                  Log in
                </Link>
              </div>
            </div>
          </div>
        </Dialog.Panel>
      </Dialog>
    </>
  );
}

This is now our only client-side component and receives the Nav items from Cosmic via props.

6. More pages

Now what if you want to create another page? Easy, go into Cosmic and create a new page titled About with whatever content you want:

Then create a new file located in app/about/page.tsx (notice the folder name is the page slug).

// app/about/page.tsx

import { cosmic } from "@/lib/cosmic";

export default async function Home() {
  const { object: page } = await cosmic.objects
    .findOne({
      type: "pages",
      slug: "about",
    })
    .props("metadata")
    .depth(1);
  return (
    <main>
      <div className="relative isolate px-6 pt-14 lg:px-8">
        <div
          className="absolute inset-x-0 -top-40 -z-10 transform-gpu overflow-hidden blur-3xl sm:-top-80"
          aria-hidden="true"
        >
          <div
            className="relative left-[calc(50%-11rem)] aspect-[1155/678] w-[36.125rem] -translate-x-1/2 rotate-[30deg] bg-gradient-to-tr from-[#ff80b5] to-[#9089fc] opacity-30 sm:left-[calc(50%-30rem)] sm:w-[72.1875rem]"
            style={{
              clipPath:
                "polygon(74.1% 44.1%, 100% 61.6%, 97.5% 26.9%, 85.5% 0.1%, 80.7% 2%, 72.5% 32.5%, 60.2% 62.4%, 52.4% 68.1%, 47.5% 58.3%, 45.2% 34.5%, 27.5% 76.7%, 0.1% 64.9%, 17.9% 100%, 27.6% 76.8%, 76.1% 97.7%, 74.1% 44.1%)",
            }}
          />
        </div>
        <div className="mx-auto max-w-2xl sm:py-48">
          <div className="text-center">
            <h1 className="text-4xl font-bold tracking-tight text-gray-900 sm:text-6xl">
              {page.metadata.headline}
            </h1>
            <p className="mt-6 text-lg leading-8 text-gray-600">
              {page.metadata.subheadline}
            </p>
          </div>
        </div>
        <img src={page.metadata.hero.imgix_url} className="w-full" />
      </div>
    </main>
  );
}

Then add a new nav item in the Cosmic Object so you can get to it.

Click on the new nav link and your page is now there!

Notice that our global header is available on all pages because it was added to our layout.tsx file. And because Header is a React Server Component, it can fetch the CMS data directly, without having to do so on the page level which is also quite nice!

Another thing to note is that since the Header component is rendered in the layout and the navigation links use the Next.js <Link> element, it doesn’t refetch the data when you navigate between pages.

Conclusion

I hope you enjoyed this exploration of using React Server Components with a headless CMS. We covered:

When to use React Server Components and when to use client components.
We noted some of the benefits this new component structure offers when fetching data from a headless CMS. Specifically, we indicated that we can simply fetch data with an async function without having to use any pre-RSC methods in Next.js such as getServerSideProps, getStaticPaths, etc.
We also noted how RSCs make it easy to reuse data-powered components since the components themselves can fetch data server-side (for example our Header component).

React Server Components with Next.js makes for a simplified and improved developer experience when using a headless CMS.

4 Steps to Update the Next.js Marketplace Template

Tony Spiro — Thu, 07 Sep 2023 17:52:00 +0000

We recently updated the Next.js Marketplace template to the new Cosmic JavaScript SDK and I have to say, the process was quite quick and simple. The new SDK is much lighter in bundle size (by 93%) and provides a more declarative syntax including TypeScript support, making it the recommended way to connect your JavaScript apps to Cosmic.

The following article shows you the steps that were taken to make the upgrade and what to expect when you upgrade your projects to the new SDK.

Getting started

To get started, install the Next.js Marketplace template and view a live demo here.

The template includes common ecommerce marketplace functionality:

Browse, search, and filter products for sale.
Purchase a product using Stripe.
Create your own product for sale (requires Cosmic login).

Steps to Upgrade

The steps we took to upgrade this template are:

Installed the new Cosmic JavaScript SDK.
Updated the Bucket client configuration.
Added an additional parameter to fetch the products (depth).
Simplified the logic to add products.

You can see the pull request where each of the updates were made. Let's go over each step:

1. Install the Cosmic JavaScript SDK

First, we removed the deprecated Cosmic NPM module:

pnpm remove cosmicjs

Then we installed the new Cosmic JavaScript SDK:

pnpm add @cosmicjs/sdk

See the PR update.

2. Bucket configuration

Next, we updated the Bucket client configuration with the following code:

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.NEXT_PUBLIC_COSMIC_BUCKET_SLUG,
  readKey: process.env.NEXT_PUBLIC_COSMIC_READ_KEY,
  writeKey: process.env.COSMIC_WRITE_KEY,
})

See the PR update.

3. Object fetching

Then we added the depth parameter to the part of the code that handles the product fetching. Note: This is now required when fetching nested Object relationship data.

In this example, to fetch the nested data from categories along with the product data, which is connected to the product model by a Multi-Object relationship Metafield, we set a depth of 1.

const data = await cosmic.objects
  .find({
    type: 'products',
  })
  .props('title,slug,id,metadata.categories')
  .depth(1)

See the PR update. For more information about Metafields, see Metafields in the docs.

4. Adding Objects

And lastly, we updated the way products are created as this has been dramatically simplified in the new API. Instead of a large metafields array, you now have a concise metadata object. (Less code FTW!)

See the PR update.

Next steps

I hope you found this guide instructive. Sign up to get started using Cosmic to power content for your websites and apps.

If you are looking to migrate from the old dashboard, read the upgrade guide and reach out to Cosmic support if you need assistance.

Migrate from WordPress to a headless CMS in 3 easy steps

Tony Spiro — Wed, 16 Aug 2023 17:17:00 +0000

In this article I'm going to show you how to migrate from WordPress to a headless CMS in 3 easy steps. To make this quick and simple, we will be using the Cosmic WordPress Importer extension to import posts using any available WordPress RSS feed.

This article assumes that you already have at least a cursory knowledge of both WordPress and headless CMS. If you don't understand these concepts, I recommend you learn about headless CMS and check out the WordPress vs Headless CMS comparison page.

TL;DR

Install the WordPress extension

View the source code to see how the extension is built

WordPress fanboys need not apply

WordPress powers about 40% of the web. That's a lot of websites that are suffering from the same problems. Some people love WordPress, this article is not for them.

This article is for people who are fed up with the issues that come with one of the world's most popular content management systems and are ready to go headless. If this applies to you, let's get started.

1. Create a new Cosmic project

First create a free Cosmic account then set up a new project.

2. Install the Extension

Go to the Extensions tab then find the Cosmic WordPress Importer extension and install it.

3. Migrate your content

After you install the extension, you will be asked to add a feed URL to import the posts. A feed URL is any publicly available WordPress RSS feed (something like https://github.blog/feed).

Select how may posts you want to install and click "Submit". Automatically, the WordPress posts will populate into Cosmic. Refresh the page to see links to the posts available in Cosmic.

Your posts are now available via a simple API endpoint. The JSON data payload will look something like this:

{
  "objects": [
    {
      "slug": "angels-who-help-you-fly",
      "title": "Angels who help you fly",
      "metadata": {
        "content": "<p>Paddling out at Pacifica Beach on an unusually warm, beautiful day, I noticed a...",
        "snippet": "Paddling out at Pacifica Beach on an unusually warm, beautiful day, I noticed a guy...",
        "author": "Jane Mariechen",
        "categories": "Surfing, California"
      }
    },
    {
      "slug": "trust-yourself",
      "title": "Trust yourself",
      "metadata": {
        "content": "<p>I sat on the sidelines with anxiety as I watched the...",
        "snippet": "I sat on the sidelines with anxiety as I watched the big waves from a distance....",
        "author": "John Marieche",
        "categories": "Surfing, Hawaii"
      }
    }
  ]
}

You can now deliver your content to any website or application. FREEDOM!

Bonus points

Luckily, the Cosmic WordPress Importer extension code is available open source so you can customize the data that it pulls in. You can also learn how to build your own Cosmic extension.

Conclusion

I hope you found this article helpful. Sign up for Cosmic and reach out to Cosmic support if you have any questions or need dedicated migration support.