astro-strapi-loader

Astro Strapi Loader Integration of Astro with Strapi CMS that enables easy data loading from Strapi Content API

---

📋 Table of Contents

• 📋 Requirements
• 📦 Installation
• 🚀 Features
• 🤖 AI-native support
• 🖥️ Usage
• ⚙️ Configuration
• 🔧 Development
• 🤝 Contributing
• 📄 License

📋 Requirements

• Astro ^6.0.0 || ^7.0.0
• Strapi ^5.0.0
• Node.js >= 22.12.0

📦 Installation

npm install @sensinum/astro-strapi-loader
# or
yarn add @sensinum/astro-strapi-loader

🚀 Features

• Easy integration with Astro and Strapi
• Automatic data loading from Strapi API
• Query, filtering and population capabilities - Strapi 5 Documentation
• Authorization token support
• Astro collections system integration
• TypeScript typing
• 🆕 Custom ID generation - Generate collection IDs from custom fields (e.g., slugs)
• 🆕 Multiple collections - Create multiple collections from same endpoint
• 🆕 i18n support - Built-in locale support for multilingual content

🤖 AI-native support

This repository includes optional, model-agnostic guidance for coding agents and AI-assisted workflows (Strapi REST query objects, populate / dynamic zones, locale, qs serialization, and Astro Collections usage).

Location	Purpose
.ai/AGENTS.md	Short agent instructions—non-negotiables and pointers to the skill.
.ai/astro-strapi-loader/SKILL.md	Full skill (YAML frontmatter + markdown); copy or adapt for your global or project skills directory.
.cursor/rules/astro-strapi-loader.mdc	Cursor rules for files such as content.config.ts (.mdc with optional globs).

You can reuse or fork these files in downstream projects that consume @sensinum/astro-strapi-loader so assistants stay aligned with Strapi 5 REST parameters and this package’s behavior. The published npm package contains only dist/; AI assets live in the GitHub tree alongside the source.

🖥️ Usage

1. Add the integration to your src/content.config.ts:

import { generateCollections } from '@sensinum/astro-strapi-loader';

let strapiCollections: any = {};

try {
  strapiCollections = await generateCollections({
    url: import.meta.env.STRAPI_URL,
    token: import.meta.env.STRAPI_TOKEN,
    headers: {
      // ...
    },
  }, [{ // leave empty [] to fetch all the collections based on default Strapi settings
    name: "homepage",
    query: {
      populate: { seo: true },
    },
  }, {
    name: "layout",
    query: {
      populate: { header: true, footer: true },
    },
  }, 'simple-collection-name']); // Can also pass just strings
} catch (error) {
  console.error(error);
}

export const collections = {
    ...strapiCollections,
};

✅ Backward Compatible: Existing code works without any changes!

2. Use in your Astro component:

---
import { getCollection } from 'astro:content';
import { fetchContent } from '@sensinum/astro-strapi-loader';

// Basic usage with Astro Collections
const myCollection = await getCollection('my-collection');

// Basic usage with direct Strapi Content API fetch
const myCollection = await fetchContent({
  url: import.meta.env.STRAPI_URL,
  token: import.meta.env.STRAPI_TOKEN,
  contentType: 'my-collection',
  queryParams: {
    populate: {
      // ...
    },
    filters: {
      // ...
    },
    sort: ['publishedAt:desc'],
  },
});
---

  { myCollection.map(item => (
    
      {item.title}
      {item.description}
    </article>
  )) }

⚙️ Configuration

Integration Options

Option	Type	Required	Description
url	string	Yes	Strapi API URL
token	string	No	Strapi API access token
collectionName	string	No	Custom collection name (for multiple collections from same endpoint)
idGenerator	function	No	Custom function to generate IDs from item data
locale	string | string[]	No	Single locale or array of locales for i18n support
headers	Record<string, string>	No	Additional headers for API request

⚠️ Note: The token must have read access to both the Content API and the Content-Type Builder API (ONLY to the "Get Content Types" endpoint).

Mixing 1.0.x and 1.1.0+

You can mix old (simple) and new (extended) format in a single generateCollections call:

strapiCollections = await generateCollections({
  url: import.meta.env.STRAPI_URL,
  token: import.meta.env.STRAPI_TOKEN,
}, [
  // ✅ Old format - works as before
  {
    name: "homepage",
    query: { populate: { seo: true } }
  },
  {
    name: "layout",
    query: { populate: { header: true, footer: true } }
  },

  // ✅ 1.1.0+ - with locale support
  {
    name: "pages",
    collectionName: "pagesEN",
    locale: "en",
    query: { sort: ['publishedAt:desc'] }
  },
  {
    name: "pages",  // Same endpoint, different config!
    collectionName: "pagesDE",
    locale: "de",
    query: { sort: ['publishedAt:desc'] }
  },

  // ✅ 1.1.0+ - with custom ID
  {
    name: "blog-posts",
    idGenerator: (data) => data.slug as string,
    query: { filters: { published: true } }
  },

  // ✅ 1.1.0+ - combining all features
  {
    name: "articles",
    collectionName: "articlesMultilang",
    locale: ["en", "de", "fr"],
    idGenerator: (data) => data.slug as string
  }
]);

// Result collections:
// - homepage (old format)
// - layout (old format)
// - pagesEN (1.1.0+)
// - pagesDE (1.1.0+)
// - blog-posts (1.1.0+)
// - articlesMultilang (1.1.0+)

Advanced Usage Examples

Custom ID Generation

Use slugs or custom fields as