wordpress-astro

name

wordpress-astro

description

Comprehensive WordPress integration with Astro.js using wp-astrojs-integration. Use when working with WordPress REST API in Astro projects, including: (1) Configuring live/static loaders with content collections, (2) Rendering WordPress content with WPContent and WPImage components, (3) Extending schemas with custom ACF fields, post types, or taxonomies, (4) Implementing WordPress runtime API access and authentication.

WordPress Astro Integration

Installation

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:

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:

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:

<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:

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:

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:

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

Static SSG:

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

Custom ACF:

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

Authentication:

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