@nonsponsored/storyblok-loader

A content loader for Astro Content Layer that fetches content from Storyblok's API.

Requirements

• Astro 5.2.0 or higher (required for Content Layer API)
• @storyblok/astro 6.0.0 or higher

Important Notes

• Intended to be used for build process, not in development mode or using Storyblok's Live Preview.
• Internationalization support has not been tested. Use with caution and please report any issues you encounter.

Installation

Using npm:

npm install @nonsponsored/storyblok-loader

Using yarn:

yarn add @nonsponsored/storyblok-loader

Usage

1. Set up your environment variables in .env:

• STORYBLOK_API_KEY: Your Storyblok API token
• STORYBLOK_API_VERSION: "draft" or "published"

Note: In production, the loader will always use the "published" version regardless of the STORYBLOK_API_VERSION setting.

2. Configure your content collection in src/content/config.ts:

import { defineCollection } from "astro:content";
import { storyblokLoader } from "@nonsponsored/storyblok-loader";

const storyblokCollection = defineCollection({
    loader: storyblokLoader({
        accessToken: import.meta.env.STORYBLOK_API_KEY,
        version: import.meta.env.MODE === "production" ? "published" : import.meta.env.STORYBLOK_API_VERSION,
        region: "us",
        language: "en",
        contentType: "blog",
        resolve_relations: ["author.posts", "related_posts"],
        resolve_links: "url",
        sort_by: "content.published_date:desc",
        filter_query: {
            "content.category": "technology"
        }
    })
});

export const collections = {
    storyblok: storyblokCollection,
};

Configuration Options

The loader accepts the following options:

Option	Type	Default	Description
accessToken	string	Required	Your Storyblok API token
version	"published" | "draft"	"published"	Content version to fetch
region	"us" | "eu"	"us"	Storyblok API region
language	string	undefined	Language/locale code (e.g., "en", "de")
contentType	string	undefined	Filter by content type
sort_by	string	undefined	Sort entries by field
filter_query	Record<string, any>	undefined	Filter by field values
resolve_relations	string[]	undefined	Resolve relationships
resolve_links	"url" | "story" | "0" | "1" | "2"	undefined	Resolve links to other stories

Returned Data Structure

The loader returns an array of stories with the following structure:

interface Story {
    id: string;
    slug: string;
    content: unknown;
    name: string;
    created_at: string;
    published_at: string;
    editable?: string;
    is_folder?: boolean;
    full_slug: string;
    language?: string;
    translated_slugs?: Array<{
        lang: string;
        name: string;
        path: string;
    }>;
}

Examples

Basic Usage

const storyblokCollection = defineCollection({
    loader: storyblokLoader({
        accessToken: import.meta.env.STORYBLOK_API_KEY,
        version: import.meta.env.MODE === "production" ? "published" : "draft",
        region: "us"
    })
});

export const collections = {
    storyblok: storyblokCollection,
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License