Astro WordPress Tutorial for the First Static Build

Before any Astro page template exists, the content API has already dictated URL discovery, field shapes, pagination logic, and failure modes during astro build. Changing it later usually means rewriting loaders, not just swapping endpoints.

REST is the easier first build. Core routes exist immediately, debugging starts in the browser, and each endpoint can be inspected as plain JSON. For a first static pass, that simplicity matters: fewer abstractions mean faster isolation of missing posts, bad slugs, or authentication mistakes. A fuller comparison appears in this REST-versus-WPGraphQL breakdown.

WPGraphQL becomes cleaner once content models grow. It offers typed queries, nested selection, and fewer round trips, but adds schema thinking: post types and taxonomies must be exposed to GraphQL, field groups often need GraphQL settings, and query errors can come from schema configuration rather than page code.

• Permalinks affect canonical URLs and slug lookups.
• Public post types decide what Astro can generate.
• Custom field exposure determines whether build data is complete.
• Preview, auth, and CORS rules shape debugging for drafts and protected content.

An Astro + WordPress first build needs only four moving parts: a fresh Astro app, one route that calls the WordPress API, one template that prints the response, and a root .env file. Everything else—image handling, previews, content collections, and theme polish—can wait until one post reliably becomes static HTML.

Environment variables should live in the project root. Public values use the PUBLIC_ prefix; server-only values do not. A minimal setup usually needs:

• WORDPRESS_API_URL for the REST or GraphQL endpoint
• WORDPRESS_SITE_URL only if links or canonical URLs need cleanup

Stable variable names matter more than clever structure, because fetch code, route generation, and later deploy settings often depend on them.

Starters can remove boilerplate, but they also hide routing and data-shaping choices. A starter that matches the current workflow is useful after the first successful build. For those avoiding a shell entirely, a browser-first setup path is also valid; it is simply an accelerator, not a different architecture.

JSON is only raw material

A successful API request proves that WordPress can send data; it does not prove Astro can publish a readable page. Post titles and slugs are usually safe, but body content often arrives as HTML, block markup, embeds, or shortcode output. That is why turning WordPress content into stable Astro pages is usually a rendering problem, not a fetching problem.

Astro should trust fields that are already plain text and structurally predictable: slug, date, excerpt, taxonomy names, and carefully validated custom fields. It should sanitize rich HTML before injection, especially when editors or plugins can add inline scripts, iframes, or unexpected attributes.

What usually breaks

• Blocks may depend on front-end CSS or JavaScript.
• Shortcodes may return nothing through the API unless pre-rendered in WordPress.
• Media often needs reshaping: missing alt text, multiple size URLs, or null featured images.
• Custom fields may be absent on drafts, older posts, or posts created before a plugin was installed.

A durable pipeline reshapes data before templates render it. Good defaults include fallback images, empty-state handling, and explicit rules for unsupported blocks instead of letting one strange post fail the whole build.

Readers rarely notice good URLs, but they notice drift immediately. If a WordPress post lives at /news/example-post/ and Astro ships /posts/example-post/, the mismatch feels like a migration mistake even when the content is correct. Editors lose confidence too, because copied links, previews, and old habits stop mapping cleanly. A careful permalink mapping strategy prevents that quiet erosion of trust.

• Preserve slug logic: use WordPress slug, not derived titles, and respect parent-child paths for hierarchical content.
• Mirror structural prefixes: if the site uses categories, dates, or custom post type bases, reproduce them exactly in route generation.
• Keep references consistent: internal links in rendered HTML, navigation, XML sitemaps, and canonical tags should all point to the same final URL.

The goal is not visual similarity. It is a single, predictable address for every document. When redirects, canonicals, and generated routes disagree, search engines split signals, and editors start second-guessing whether Astro reflects the real site.