Imported from JUVOJustin/astrojs-wp-integration (AGENTS.md). Install upstream with npx skills add JUVOJustin/astrojs-wp-integration. Copyright stays with the author.

Agent Instructions

Project Overview

This repository ships one npm package:

• wp-astrojs-integration (src/) — Astro loaders, Astro actions, auth bridge, catalog virtual modules, and components built on top of the published fluent-wp-client package
• The package also exposes wp-astrojs-integration/integration, an Astro integration that can fetch and cache a WordPress discovery catalog for catalog-aware helpers.

Architecture Priorities

• Treat WordPressClient from fluent-wp-client as the core integration layer. Add or harden client-backed behavior before introducing higher-level loaders, bridges, or actions that depend on it.
• Build loaders, actions, and helpers on top of proven published client primitives.
• The package is aligned to fluent-wp-client ^3.0.1; loader payloads for post/page resources must remain plain serializable objects (no legacy helper methods on entry.data).
• Keep the package aligned with WordPress' extensibility model. Default to generic resource-oriented patterns that work for core entities, custom post types, custom taxonomies, plugin endpoints, and custom auth flows.
• Prefer Standard Schema-compatible validators for client response validation interfaces so consumers can use Zod or any other compliant schema library.
• Validate and require only the minimum data needed for a feature to work.
• Avoid hard-coding assumptions that only fit default posts/pages.

Astro Actions Imports

• All Astro Actions imports must use the public astro:actions virtual module. Never import from internal paths like astro/actions/runtime/server.js or astro/actions/runtime/entrypoints/server.js. The virtual module is resolved for tsc via the type declarations configured in src/env.d.ts.

Testing

Philosophy

• Integration tests only — no unit tests. Every test runs against a real WordPress instance.
• Tests exercise the full stack: TypeScript code -> HTTP -> WordPress REST API -> response validation.
• Prioritize Astro integration behavior (loader contracts, action schema/auth wiring, and error mapping). Avoid extensive re-validation of low-level REST semantics already covered by fluent-wp-client.

Test infrastructure

Seed data

Test content is generated by tests/wp-env/seed-content.php, which runs automatically on every wp-env start via the afterStart lifecycle script in .wp-env.json.

Contents

Native WordPress meta seed data

Native REST meta fields are registered by tests/wp-env/mu-plugins/register-test-meta.php and seeded by tests/wp-env/seed-content.php.

ACF seed data

ACF fields are registered by tests/wp-env/mu-plugins/register-acf-fields.php with show_in_rest => 1.

Plugin requirements

• The test environment installs or activates the free ACF plugin during npm run wp:start.
• The test environment also installs jwt-authentication-for-wp-rest-api during npm run wp:start and sets JWT_AUTH_SECRET_KEY in .wp-env.json.
• WordPress ability integration tests rely on the core wp_register_ability() API when available. Test abilities are registered by tests/wp-env/mu-plugins/register-test-abilities.php.

Running tests

npm run wp:start
npm test                    # All test projects (integration + static-build)
npm run test:integration    # Integration project only (loaders, actions, auth)
npm run test:build          # Static build project only
npm run wp:stop
npm run wp:clean

Astro build integration test

tests/integration/loaders/static-loader-build.test.ts runs a real astro build against the shared fixture project in tests/fixtures/astro-site/. The fixture defines content collections backed by the package's static loaders and an Astro page that renders the fetched data. The test sets ASTRO_TEST_MODE=build so the shared astro.config.mjs switches to static output for build-only validation. This verifies the full Astro pipeline (content config, loader execution, page rendering) works end-to-end.

The build test runs through the static-build project in vitest.config.ts. It loads WP_BASE_URL via tests/setup/env-loader.ts but skips the heavy integration globalSetup (wp-cli password reset, app-password creation) because it only needs the public WordPress REST API.

How to write new tests

1. Always write integration tests.
2. Place Astro-facing integration tests in tests/integration/.
3. Use helpers from tests/helpers/wp-client.ts.
4. Prefer assertions about Astro-facing behavior and package contracts over exhaustive endpoint semantics.
5. Use exact counts and known slugs from the seeded content only when they validate Astro integration behavior.
6. Cover success paths and error paths.
7. Route action integration tests through the shared Astro dev server fixture (tests/fixtures/astro-site/) and real /_actions/* RPC endpoints. Do not execute package action helpers directly inside test workers.
8. Route-caching coverage should build the shared fixture and run the standalone Node adapter entry so Astro cache behavior is exercised in production mode.

Reference suites:

• tests/integration/loaders/static-loader-build.test.ts
• tests/integration/loaders/static-loaders.test.ts
• tests/integration/loaders/live-loaders.test.ts
• tests/integration/loaders/live-loader-runtime.test.ts
• tests/integration/loaders/route-caching-runtime.test.ts
• tests/integration/actions/posts.test.ts
• tests/integration/actions/pages.test.ts
• tests/integration/actions/users.test.ts
• tests/integration/actions/books.test.ts
• tests/integration/actions/terms.test.ts
• tests/integration/actions/meta.test.ts
• tests/integration/actions/acf.test.ts
• tests/integration/actions/abilities.test.ts
• tests/integration/actions/auth-bridge.test.ts

Key gotchas

• wp-env output includes status lines (ℹ/✔). The wpCli() helper in tests/setup/global-setup.ts strips them.
• Vitest globalSetup runs in a separate process, so env vars are bridged through .test-env.json.
• WordPress application passwords require HTTPS by default; tests/wp-env/mu-plugins/enable-app-passwords.php overrides this for HTTP localhost.
• JWT auth relies on tests/wp-env/mu-plugins/enable-jwt-auth-header.php so Authorization headers survive local wp-env rewrites.
• The WP REST API caps per_page at 100.
• Astro route caching is disabled in astro dev; cache behavior must be validated against the standalone server build used by tests/helpers/astro-preview.ts.

Code Style

• After making code changes, run npm run format:check and ensure Biome reports no formatting issues before finalizing.
• Astro loaders are split into src/loaders/static.ts and src/loaders/live.ts.
• Shared runtime helpers for Astro middleware, actions, and auth flows should prefer web-standard APIs so they work on Node and non-Node adapters.
• All public API is re-exported from src/index.ts.
• AI SDK helpers are owned by fluent-wp-client/ai-sdk; this package should not add live-loader-backed AI wrappers because live loaders do not receive Astro request auth context.
• New discovery features (CLI, runtime schema conversion, embed extraction helpers) are re-exported from fluent-wp-client and fluent-wp-client/zod subpackages.
• Actions and loaders use the v3 client API: client.content('posts').list() instead of client.getPosts(), client.users().me() instead of client.getCurrentUser().

npm Package

wp-astrojs-integration publishes dist/ and src/components/.

The repository consumes fluent-wp-client from npm, so local package mirrors should not be reintroduced.

When package structure changes, verify published contents with npm pack --dry-run.