How to Use Prismic with Astro: Complete Guide

Prismic is a headless page builder and CMS built around "slices," which are reusable content components that editors can mix and match to build pages. If you have worked with other headless CMS platforms and found the content modeling too rigid, Prismic's slice-based approach will feel refreshing. Paired with Astro, you get a fast static site with content that non-technical editors can manage through a clean visual interface.

The integration works by fetching content from Prismic's API at build time, letting Astro generate static pages from your CMS data. No official Astro integration exists, but Prismic's JavaScript client makes the connection simple.

Prerequisites

• Node.js 18+
• An Astro project (npm create astro@latest)
• A Prismic account with a repository created (free tier available, paid plans start at $100/mo)

Installation

Install the Prismic client library and the helpers package:

npm install @prismicio/client @prismicio/helpers

If you plan to render Prismic's rich text fields as HTML:

npm install @prismicio/helpers

Configuration

Create a Prismic client file that you can import anywhere in your project:

// src/lib/prismic.ts
import * as prismic from "@prismicio/client";

const repositoryName = import.meta.env.PRISMIC_REPOSITORY;

export const client = prismic.createClient(repositoryName, {
  accessToken: import.meta.env.PRISMIC_ACCESS_TOKEN,
});

Add your credentials to .env:

PRISMIC_REPOSITORY=your-repo-name
PRISMIC_ACCESS_TOKEN=your-access-token

You can find the repository name in your Prismic dashboard URL (e.g., your-repo-name.prismic.io). The access token is generated under Settings > API & Security.

Set up your custom types in the Prismic dashboard. For a blog, create a "Blog Post" repeatable type with fields like title (Key Text), content (Rich Text), excerpt (Key Text), and featured_image (Image).

Basic Usage

Fetch all blog posts and render them on an index page:

---
// src/pages/blog/index.astro
import { client } from "../../lib/prismic";
import * as prismicH from "@prismicio/helpers";
import BaseLayout from "../../layouts/BaseLayout.astro";

const posts = await client.getAllByType("blog_post", {
  orderings: [{ field: "document.first_publication_date", direction: "desc" }],
});
---

<BaseLayout title="Blog">
  <h1>Blog</h1>
  {posts.map((post) => (
    <article>
      <a href={`/blog/${post.uid}`}>
        <h2>{prismicH.asText(post.data.title)}</h2>
        <p>{post.data.excerpt}</p>
      </a>
    </article>
  ))}
</BaseLayout>

For individual post pages, use dynamic routing with getStaticPaths:

---
// src/pages/blog/[slug].astro
import { client } from "../../lib/prismic";
import * as prismicH from "@prismicio/helpers";
import BaseLayout from "../../layouts/BaseLayout.astro";

export async function getStaticPaths() {
  const posts = await client.getAllByType("blog_post");
  return posts.map((post) => ({
    params: { slug: post.uid },
    props: { post },
  }));
}

const { post } = Astro.props;
const htmlContent = prismicH.asHTML(post.data.content);
---

<BaseLayout title={prismicH.asText(post.data.title)}>
  <article>
    <h1>{prismicH.asText(post.data.title)}</h1>
    {post.data.featured_image?.url && (
      <img src={post.data.featured_image.url} alt={post.data.featured_image.alt || ""} />
    )}
    <div set:html={htmlContent} />
  </article>
</BaseLayout>

Working with slices is where Prismic really shines. Each slice maps to a component:

---
// src/components/SliceZone.astro
import TextBlock from "./slices/TextBlock.astro";
import ImageGallery from "./slices/ImageGallery.astro";
import CallToAction from "./slices/CallToAction.astro";

const { slices } = Astro.props;

const components = {
  text_block: TextBlock,
  image_gallery: ImageGallery,
  call_to_action: CallToAction,
};
---

{slices.map((slice) => {
  const Component = components[slice.slice_type];
  return Component ? <Component slice={slice} /> : null;
})}

Production Tips

1. Use Prismic's image optimization. Prismic serves images through Imgix, so you can append query parameters for resizing, format conversion, and quality adjustments. Add ?w=800&fm=webp to image URLs for automatic WebP conversion at the right size.

2. Implement preview mode. Prismic supports content previews so editors can see unpublished changes. Set up an API route in Astro that handles the preview token and redirects to the right page with draft content.

3. Cache API responses during builds. If you have hundreds of documents, each getStaticPaths call hits Prismic's API. Use the fetchLinks option to grab related content in a single query instead of making separate requests for linked documents.

4. Set up webhooks for automatic rebuilds. In Prismic's settings, add a webhook URL pointing to your hosting platform's build trigger (Vercel, Netlify, etc.). Every time content is published, the site rebuilds automatically.

5. Use TypeScript types for your custom types. Run npx @prismicio/types-generator to auto-generate TypeScript interfaces from your Prismic custom types. This catches field name typos at compile time instead of runtime.

Alternatives to Consider

• Contentful if you need a more mature ecosystem with more third-party integrations and a larger community.
• Storyblok if you want a similar visual editing experience with an official Astro integration.
• TinaCMS if you prefer a Git-backed CMS that stores content directly in your repository.

Wrapping Up

Prismic's slice-based content model and Astro's component-driven architecture are a natural fit. Editors get a visual page builder without touching code, and developers get clean APIs with predictable data structures. The free tier is generous enough for personal projects and small businesses, and the setup is straightforward once you have the client configured. If your project needs a CMS where non-developers can build flexible page layouts, Prismic is a strong choice.