WordPress Astro Integration

Installation

bash

npm install wp-astrojs-integration

Set PUBLIC_WORDPRESS_BASE_URL in .env.

Loader Decision Tree

Choose your data loading strategy:

•Need real-time data or SSR? → Live Collections → Use live.config.ts
•Build static site? → Static Collections → Use content.config.ts
•Runtime API calls? → WordPressClient → See api-reference.md

Core Workflows

1. Configure Collections

Live loader for SSR:

typescript

import { defineLiveCollection } from 'astro:content';
import { wordPressPostLoader, postSchema } from 'wp-astrojs-integration';

const posts = defineLiveCollection({
  loader: wordPressPostLoader({ baseUrl: import.meta.env.PUBLIC_WORDPRESS_BASE_URL }),
  schema: postSchema,
});

Static loader for SSG:

typescript

import { defineCollection } from 'astro:content';
import { wordPressPostStaticLoader, postSchema } from 'wp-astrojs-integration';

const posts = defineCollection({
  loader: wordPressPostStaticLoader({ baseUrl: import.meta.env.PUBLIC_WORDPRESS_BASE_URL }),
  schema: postSchema,
});

2. Render Content

Use WPContent for Gutenberg blocks and WPImage for responsive images:

astro

<WPContent 
  content={post.data.content.rendered}
  baseUrl={import.meta.env.PUBLIC_WORDPRESS_BASE_URL}
/>

<WPImage media={featuredMedia} loading="eager" />

Page templates: post-template.astro, page-template.astro

3. Extend Schemas

Add custom ACF fields or post types using Zod:

typescript

import { postSchema } from 'wp-astrojs-integration';
import { z } from 'astro/zod';

const customSchema = postSchema.extend({
  acf: z.object({
    video_url: z.string().optional(),
    custom_field: z.string().optional(),
  }).optional(),
});

See api-reference.md for complete examples.

4. Runtime API

Use WordPressClient for dynamic data fetching:

typescript

import { WordPressClient } from 'wp-astrojs-integration';

const wp = new WordPressClient({ baseUrl: import.meta.env.PUBLIC_WORDPRESS_BASE_URL });
const posts = await wp.getPosts();
const post = await wp.getPostBySlug('my-post');

Protected routes: auth-middleware.ts

Resources

File	Purpose
api-reference.md	Complete API documentation
wordpress-rest.md	WordPress REST API endpoints
patterns.md	Advanced patterns and best practices

Quick Examples

Live SSR:

typescript

import { wordPressPostLoader } from 'wp-astrojs-integration';
const posts = defineLiveCollection({
  loader: wordPressPostLoader({ baseUrl }),
  schema: postSchema,
});

Static SSG:

typescript

import { wordPressPostStaticLoader } from 'wp-astrojs-integration';
const posts = defineCollection({
  loader: wordPressPostStaticLoader({ baseUrl }),
  schema: postSchema,
});

Custom ACF:

typescript

const customSchema = postSchema.extend({
  acf: z.object({ video_url: z.string().optional() }).optional(),
});

Authentication:

typescript

const wp = new WordPressClient({
  baseUrl,
  auth: { username, password }
});
await wp.isAuthenticated();