astro-graphql

An Astro content loader for GraphQL endpoints. Fetch data from any GraphQL API and use it as Astro content collections.

Installation

npm install astro-graphql
# or
pnpm add astro-graphql

Quick Start

1. Create a collection config

// src/content/collections/posts/config.ts
import { loadGraphQLFile } from 'astro-graphql/loaders';
import { z } from 'astro/zod';

const query = loadGraphQLFile('./query.graphql', import.meta.url);

export const postsConfig = {
  query,
  variables: { host: 'til.dofbi.com', limit: 10 },
  schema: z.object({
    id: z.string(),
    title: z.string(),
    brief: z.string(),
  }),
  rootField: 'publication.posts',
};

2. Create your GraphQL query

# src/content/collections/posts/query.graphql
query GetPosts($host: String!, $limit: Int!) {
  publication(host: $host, ) {
    posts(first: $limit) {
      edges {
        node {
          id
          title
          brief
        }
      }
    }
  }
}

3. Configure content collections

// src/content.config.ts
import { graphqlCollections } from 'astro-graphql/loaders';
import { postsConfig } from './content/collections/posts/config';

const GRAPHQL_URL = import.meta.env.GRAPHQL_URL || 'https://gql.hashnode.com';

const collections = graphqlCollections({
  endpoint: GRAPHQL_URL,
  authToken: import.meta.env.GRAPHQL_TOKEN, // Optional
  collections: {
    posts: postsConfig,
  },
});

export { collections };

4. Use in your pages

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

const posts = await getCollection('posts');
---

{posts.map((post) => (
  <article>
    <h2>{post.data.title}</h2>
    <p>{post.data.brief}</p>
  </article>
))}

API Reference

graphqlCollections(config)

Creates Astro content collections from GraphQL queries.

graphqlCollections({
  endpoint: string,           // GraphQL endpoint URL
  authToken?: string,         // Optional Bearer token
  collections: {
    [name]: CollectionConfig  // Collection configurations
  }
})

CollectionConfig

| Option | Type | Required | Description | |--------|------|----------|-------------| | query | string | Yes | GraphQL query string | | variables | object | No | Query variables | | schema | ZodObject | Yes | Zod schema for validation | | rootField | string | No | Path to data in response (e.g., publication.posts) | | mapper | function | No | Transform raw data before validation | | pagination | object | No | Pagination config ({ strategy: 'cursor' \| 'offset' }) | | errorPolicy | string | No | 'none' (default), 'all', or 'ignore' |

loadGraphQLFile(path, importMetaUrl)

Load a .graphql file and return the query string.

const query = loadGraphQLFile('./query.graphql', import.meta.url);

gql template literal

Write inline GraphQL queries.

import { gql } from 'astro-graphql';

const query = gql`
  query GetPosts {
    posts { id title }
  }
`;

Mapper Example

Transform GraphQL response data before validation:

export const postsMapper = (raw: any) => ({
  id: raw.id,
  title: raw.title,
  // Flatten nested data
  posts: raw.posts?.edges?.map((e: any) => e.node) ?? [],
});

Pagination

Cursor-based

{
  pagination: {
    strategy: 'cursor',
    limit: 10,
    cursorField: 'cursor'
  }
}

Offset-based

{
  pagination: {
    strategy: 'offset',
    limit: 10
  }
}

Environment Variables

| Variable | Description | |----------|-------------| | GRAPHQL_URL | GraphQL endpoint URL | | GRAPHQL_TOKEN | Optional auth token |

License

MIT