Cosmic Headless CMS for Astro: Complete Tutorial with TypeScript SDK

Astro is the fastest-growing web framework for content-driven websites. Its islands architecture delivers near-zero JavaScript by default, making it ideal for blogs, docs sites, marketing pages, and anything where performance directly impacts SEO.

Cosmic is a headless CMS built around the same philosophy: content that works with any frontend, delivered fast from the edge. In this tutorial, you will connect Cosmic to an Astro v6 project from scratch, fetch content with the TypeScript SDK, set up dynamic routing, and understand the REST API patterns that make it all work.

What you will build: A blog with Cosmic as the content backend, Astro as the frontend, dynamic routing per post, and TypeScript throughout.

Prerequisites:

• Node.js 18+
• A Cosmic account (free at cosmicjs.com)
• Basic familiarity with TypeScript and Astro

---

Step 1: Create a Cosmic Bucket

Sign up for Cosmic at app.cosmicjs.com/signup. No credit card required. On the free plan you get 1 Bucket, 1,000 Objects, and 3 AI agents.

Once signed in:

1. Click Create New Bucket
2. Name it (or anything you like)
3. Go to Object Types and create a new type called
4. Add these metafields:
   • (Text) — the post headline
   • (Markdown) — the post body
   • (Textarea) — short summary
   • (File, image only) — featured image
   • (Date)
5. Create a few test blog posts with real content

Then, from your bucket dashboard:

• Go to Settings > API Access
• Copy your Bucket Slug and Read Key

---

Step 2: Scaffold an Astro Project

Select the following options when prompted:

• Template: Blog (or Empty)
• TypeScript: Strict
• Install dependencies: Yes

Then install the Cosmic TypeScript SDK:

---

Step 3: Configure Environment Variables

Create a file in your project root:

For production deployments (Vercel, Netlify, etc.), add these as environment variables in your hosting dashboard.

Never commit your Read Key to a public repository.

---

Step 4: Create a Cosmic Client

Create a utility file at :

This creates a typed client you can import anywhere in your Astro project. The client handles authentication, error handling, and TypeScript inference automatically.

---

Step 5: Define TypeScript Types

Create to type your content:

This interface maps directly to the object shape returned by Cosmic's REST API and TypeScript SDK.

---

Step 6: Fetch Blog Posts on the Index Page

Update :

Key points:

• takes a query object. filters by object type.
• limits which fields are returned, reducing response size and improving performance.
• returns newest posts first. Prefix with for descending.
• caps the result set.

---

Step 7: Dynamic Routing with

Create for individual post pages:

What's happening here:

is Astro's static generation API. It runs at build time, fetches all posts from Cosmic, and generates a static HTML page for each. Your deployed site will have one pre-rendered HTML file per post. Zero server-side rendering overhead. Maximum performance.

The on Cosmic media objects gives you access to Imgix image transformations: append to serve WebP automatically at the right size.

---

Step 8: Server-Side Rendering (Optional)

If you want dynamic content (pages that update without rebuilding), enable SSR in your Astro config:

With SSR enabled, your page components run on every request. The Cosmic API call happens server-side, and you always get fresh content without a rebuild:

fetches a single object by its properties. Combine with Astro's dynamic route and you have on-demand rendering with Cosmic as the backend.

---

Step 9: Filtering and Querying with MongoDB-Style Operators

Cosmic's REST API supports MongoDB-style query operators for flexible filtering. These work identically in the TypeScript SDK:

Supported operators: , , , , , , , . These match MongoDB query syntax, so any developer familiar with MongoDB or Mongoose already knows the pattern.

---

Step 10: Image Optimization with Imgix

Every file uploaded to Cosmic is served through Imgix. The property on media objects gives you access to Imgix's transformation API:

Common Imgix parameters for Astro projects:

• / : width and height in pixels
• : crops to the exact dimensions
• : serves WebP to browsers that support it, JPEG/PNG as fallback
• : applies lossy compression automatically
• : quality from 1-100 (85 is a good default)

---

Step 11: REST API Direct Usage

For cases where you prefer direct HTTP calls over the SDK (e.g., edge functions, Deno environments), Cosmic's REST API is simple:

The REST API base URL is . All responses are standard JSON. No special client required.

---

Step 12: Deploy to Vercel or Netlify

For static sites (the default Astro behavior):

For Vercel with SSR:

Add to :

Then push to GitHub and connect to Vercel. Set your environment variables (, ) in the Vercel dashboard under Project Settings > Environment Variables.

For Netlify:

---

Performance Tips for Cosmic + Astro

Use always. Only request the fields you need. A blog index page doesn't need the full markdown body of every post. Fetching only cuts response size significantly.

Cache API responses at the edge. Astro's directive (or ) builds static HTML at deploy time. For dynamic SSR pages, use headers or Astro's for fine-grained caching.

Use Imgix transforms. Never serve raw uploaded images. Always append at minimum to your values. This alone can reduce image payload by 40-60%.

Limit your result set. Add to every query. Unbounded queries on large buckets increase latency.

---

Common Patterns

Blog with Categories

Related Posts

Search by Title

---

What to Build Next

Now that your Astro site is fetching content from Cosmic:

1. Add a newsletter signup form that stores leads as Objects in Cosmic via the Write API
2. Set up a Cosmic Content Agent to draft blog posts on a schedule and publish them automatically
3. Use the Cosmic MCP Server to manage your content model from Cursor or Claude
4. Add Cosmic's AI image generation to auto-generate cover images for new posts

---

Summary

Cosmic's REST API and TypeScript SDK are designed to stay out of your way. No proprietary query language. No lock-in. Just fast, typed, edge-delivered content for your Astro site.

Ready to build?

• Create a free Cosmic account
• Read the full REST API docs
• Browse Astro + Cosmic templates
• Book a demo with Tony