Astro: Solving the error "Cannot find module 'astro:content' or its corresponding type declarations.ts(2307)"

If you are like me, tinkering with Astro and some Typescript, there are chances that you’ve been greeted by this infamous error:

Cannot find module 'astro:content' or its corresponding type declarations.ts(2307)

Can’t catch a break !

You’ve set up your project, you’re ready to build something amazing, but then… there’s that issue. The fix may be simpler than you think: you just need to create some content first.

The Chicken-and-Egg Problem

The astro:content module is a “virtual module.” This means it doesn’t exist as a file in your node_modules. Instead, its type definitions are generated by Astro based on two things:

The actual content files in your src/content/ directory.
The schema you define for your collections in src/content/config.ts.

The problem arises when you try to use astro:content in your code before any content files exist for Astro to analyze. It’s a chicken-and-egg situation: TypeScript needs the types to validate your code, but Astro needs the content to generate the types.

The Solution: A 4-Step Process

Here is the step-by-step process that you can try.

Step 1: Create Your First Content File

Astro needs at least one piece of content to work with.

Create a new directory for your collection, for example: src/content/blog/.

Inside it, create a simple Markdown file.

File: src/content/blog/hello-world.md

---
title: "Great title"
pubDate: 2025-10-18
description: "Awesome description"
layout: "../../layouts/BlogPostLayout.astro"
---

Outstanding post

Just by adding this file, you’ve given Astro the raw material it needs.

Step 2: Configure Your Collection and Schema

For Astro to provide proper type safety, you need to tell it what your blog collection should look like. This is done in a special configuration file.

If it doesn’t exist, create src/content/config.ts:

File: src/content/config.ts

import { defineCollection, z } from "astro:content";

// Define a schema for our blog collection
const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string(),
  }),
});

// Export a single `collections` object to register your collection(s)
export const collections = {
  blog: blogCollection,
};

This schema tells Astro that every document in the blog collection must have a title, pubDate, and description. This is what powers the amazing autocompletion you get with astro:content.

Step 3: Run `astro sync`

Now that Astro has both content and a schema, you can tell it to generate the necessary type definitions.

Open your terminal in the project root and run:

npx astro sync

This command reads your content files and your config.ts file, then generates a .d.ts file (e.g., .astro/content.d.ts) that contains all the type information for your collections.

Step 4: Restart Your TypeScript Language Server

Sometimes, your code editor (like VS Code) might not immediately pick up the newly generated types.

If the error persists, manually restart the TypeScript language server.

In VS Code: Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and run TypeScript: Restart TS Server.

After these steps, the Cannot find module 'astro:content' error should vanish, and you’ll get full autocompletion when you use the Content Collections API.

Quick Usage Example

Now you can use the API in your Astro pages without any errors!

File: src/pages/blog/index.astro

---
import { getCollection } from 'astro:content';

const allPosts = await getCollection('blog');
---

<h1>My Blog</h1>
<ul>
  {allPosts.map((post) => (
    <li>
      <a href={`/blog/${post.slug}/`}>{post.data.title}</a>
    </li>
  ))}
</ul>

Key Takeaway

The types for astro:content are not static; they are dynamically generated from your content and its schema. If you’re facing this error, make sure you have at least one content file and a corresponding collection defined before running astro sync.