Core Package

The @astracms/core package provides the foundation for all AstraCMS integrations. It includes a TypeScript API client, Zod schemas for validation, and type definitions.

Installation

npm install @astracms/core

pnpm add @astracms/core

yarn add @astracms/core

bun add @astracms/core

Quick Start

index.ts

import { createAstraCMSClient } from '@astracms/core'

const client = createAstraCMSClient({
  apiKey: process.env.ASTRACMS_API_KEY,
})

// Fetch all published posts
const posts = await client.getPosts()

// Fetch a single post
const post = await client.getPost('hello-world')

Environment Variables

Create a .env file in your project:

.env

ASTRACMS_API_KEY=your_api_key_here

Configuration

API Key Authentication (Recommended)

Uses the v2 API by default:

const client = createAstraCMSClient({
  apiKey: 'your-api-key',
})

Workspace ID Authentication (Legacy v1 API)

For v1 API, you must specify apiVersion: 'v1':

const client = createAstraCMSClient({
  apiVersion: 'v1',
  workspaceId: 'your-workspace-id',
})

API key authentication is recommended as it's more secure and doesn't expose your workspace ID.

Client Methods

getPosts(options?)

Fetch all published posts with optional filtering.

const posts = await client.getPosts({
  limit: 10,
  page: 1,
  categories: ['technology'],
  tags: ['javascript', 'react'],
  excludeCategories: ['internal'],
  excludeTags: ['draft'],
  query: 'search term',
})

Options:

Option	Type	Description
`limit`	`number`	Max posts to return (default: all)
`page`	`number`	Page number for pagination
`categories`	`string[]`	Filter by category slugs
`tags`	`string[]`	Filter by tag slugs
`excludeCategories`	`string[]`	Exclude category slugs
`excludeTags`	`string[]`	Exclude tag slugs
`query`	`string`	Search query

getPost(slug, options?)

Fetch a single post by its slug.

const post = await client.getPost('my-post', {
  format: 'markdown', // or 'html'
})

Returns: Post | null

getCategories(options?)

Fetch all categories.

const categories = await client.getCategories({
  query: 'search',
})

getTags(options?)

Fetch all tags.

const tags = await client.getTags({
  query: 'search',
})

getAuthors(options?)

Fetch all authors.

const authors = await client.getAuthors({
  query: 'search',
})

Types

All types are exported from the package:

import type {
  AstraCMSConfig,
  Post,
  Category,
  Tag,
  Author,
  AuthorSocial,
  GetPostsOptions,
  Pagination,
} from '@astracms/core'

Post

interface Post {
  id: string
  title: string
  description: string
  slug: string
  content: string
  coverImage: string | null
  featured: boolean
  publishedAt: string
  updatedAt: string
  category: Category
  tags: Tag[]
  authors: Author[]
  attribution: string | null
}

Tag

interface Tag {
  id: string
  name: string
  slug: string
  description: string | null
}

Author

interface Author {
  id: string
  name: string
  slug: string
  bio: string | null
  image: string | null
  role: string | null
  socials: AuthorSocial[]
}

interface AuthorSocial {
  platform: string
  url: string
}

Zod Schemas

For runtime validation, all schemas are exported:

import {
  postSchema,
  categorySchema,
  tagSchema,
  authorSchema,
  authorSocialSchema,
  paginationSchema,
  postsResponseSchema,
  categoriesResponseSchema,
  tagsResponseSchema,
  authorsResponseSchema,
} from '@astracms/core'

// Validate API response
const result = postsResponseSchema.parse(apiResponse)

Next Steps

React

Use React hooks for data fetching

Next.js

Server components with caching

Vue

Vue 3 composables

React

Next.js

Vue

On this page