Connecting WordPress

PhantomStudio reads your WordPress site through its REST API. You keep writing and managing content in WordPress; your Astro site fetches it when it builds (or on every request, for Dynamic pages).

Opening the WordPress settings

Open Site ▾ › WordPress (in the Content column). You can also open the Data tab in the left bar and click Connect WordPress, or the settings icon next to WordPress once it's connected.

The Site Settings dialog has these tabs:

A dot on a tab means it has unsaved changes.

Connection tab

Connecting your site

1. Enter your site's address in WordPress Site URL (for example https://yoursite.com).
2. Click Fetch.
3. When the site answers, its name, description and address appear below.
4. Click Save Settings.

If the connection fails, check the permalinks first: in WordPress, go to Settings › Permalinks and pick any structure other than "Plain". The REST API needs it.

PhantomWP Connect plugin

The same tab shows whether the PhantomWP Connect plugin is paired: not paired, upgrade available (reading over the public REST API) or full access. Without the plugin, PhantomStudio reads public content. With it, you also get custom post type and field scaffolding, signed disconnect and visitor login for Astro or WooCommerce accounts.

Click Download PhantomWP Connect (.zip) after Fetch: the zip is made for your domain, so PhantomStudio needs the URL first.

Content tab

Once connected, the Content tab shows what your site has: Posts, Pages, Categories, Tags, Authors, each custom post type, and Media. Refresh reads them again from WordPress.

Image handling

When your site has media, choose how images are served:

• Download & optimize locally: images are downloaded, converted to WebP and bundled with the site. With Download images on save (on by default), saving the settings downloads them if none have been downloaded yet. Download now (or Re-download) downloads them at any time. See Image Optimization.
• Keep images on existing CDN: images stay where WordPress serves them. If PhantomStudio recognizes a CDN in your media URLs, it says so here. See CDN Mode.

Using WordPress content on pages

The settings dialog connects the site; you use the content elsewhere:

• Design mode: the Data tab lists Posts, Pages and each custom post type with its count and fields (including ACF fields). Open one and click Add to your page to add a list of cards already bound to each item's fields. See Data Sources.
• Code mode: the file tree's New menu has WordPress Tools, which writes ready-made pages from your WordPress content (below), and WP Query Builder for custom queries.

WordPress Tools

WordPress Tools lists what it can create:

Click Create WordPress Page (or Create Search Page). It also adds any missing supporting files, such as the WordPress client in src/lib/wordpress.ts.

Under Features, Authentication adds login, account and password reset pages. It needs the PhantomWP Connect plugin, with Visitor Authentication turned on in wp-admin › PhantomWP.

Security tab

Every request from your project to WordPress carries the access secret in the X-PhantomWP-Secret header. The project keeps it in .env as WP_ACCESS_SECRET, and only server code reads it.

Expand Access Secret to copy it or Rotate it. You can use the secret to block everyone else from your WordPress site: see WordPress Security.

Rebuild when content changes

To rebuild the site whenever you publish in WordPress, open the Deployment tab and add the ready-made snippet to your theme's functions.php. It calls your project's deploy hook. See Deploy Hooks for how it works and other ways to set it up.

What gets saved

Save Settings writes .env, src/lib/wordpress.ts and the image hosts in astro.config.mjs to your project. It only adds to astro.config.mjs and leaves the rest of the file as it is.

• PhantomStudio keeps the URL and settings, so they follow you to other devices.
• .env gets WP_API_URL (the WordPress API endpoint) and WP_ACCESS_SECRET.
• Your deployment gets the same variables if the project is deployed to Vercel or Cloudflare Workers. Deploy again for them to take effect.
• The dev server restarts, so the change shows in the preview right away.

To disconnect, click Disconnect at the bottom of the dialog.

Prerequisites

Your WordPress site needs:

• WordPress 4.7+ (REST API enabled by default)
• Permalinks set to anything but "Plain"
• Published content (drafts aren't available through the REST API)
• Public REST API access, or the PhantomWP Connect plugin

Troubleshooting

Connection failed

Check that:

1. Your WordPress site is online
2. The URL is correct (include https://)
3. Permalinks aren't set to "Plain"
4. A security plugin isn't blocking the REST API

Test it yourself: open https://yoursite.com/wp-json/wp/v2/posts. You should see JSON.

No content found

Make sure:

1. You have published posts or pages (not drafts)
2. The content isn't private or password-protected
3. Custom post types are registered with show_in_rest

REST API blocked

Some security plugins (Wordfence, Solid Security and others) disable or limit the REST API. Allow REST API access in the plugin's settings, or install PhantomWP Connect.

Next Steps

• Data Sources: show WordPress content on your pages
• Fetching Content: the WordPress client in code
• WordPress Security: secure your WordPress installation