Docs/Connecting WordPress

Connecting WordPress

Connect your WordPress site to import content and generate Astro pages.

Connecting WordPress

PhantomWP connects to your WordPress site via the REST API to import content and generate Astro pages. You continue using WordPress for content management while serving a fast static site.

Opening the WordPress Modal

Click the WordPress icon in the IDE header bar to open the WordPress settings modal.

WordPress icon

Content Tab

The Content tab is where you connect to WordPress and configure what to import.

Connecting Your Site

  1. Enter your WordPress site URL (e.g., https://yoursite.com)
  2. Click Fetch to test the connection
  3. PhantomWP detects the REST API endpoint automatically

WordPress URL input

💡

The REST API endpoint (/wp-json) is detected automatically. Just enter your site's base URL.

Site Info

After connecting, you'll see your site's information:

  • Site name
  • Site description
  • Link to visit the WordPress site

WordPress site info

Content Types

Once connected, PhantomWP shows a grid of all available content with counts:

Content types

Content TypeDescription
PostsBlog posts with categories, tags, and authors
PagesWordPress pages
MediaImages and files (display only, see Media Download)
CategoriesPost categories
TagsPost tags
AuthorsUser profiles
Custom Post TypesAny custom post types registered in WordPress

Click a content type to select/deselect it. Selected types will have Astro pages generated for them.

Search Index

Enable the Search Index option to generate FuseJS search indexes for client-side search:

  1. Toggle Search Index on
  2. Select which content types to include (Posts, Pages)
  3. Search components are generated when you click Generate Pages

Search index settings

Media Download

Download WordPress media files to your Astro project for better performance:

  1. Click Download Media
  2. Images are saved to src/media/cms/
  3. Astro automatically optimizes these images at build time

Media download

Benefits of downloading media:

  • Faster page loads (served from your domain)
  • Astro image optimization (WebP, responsive sizes)
  • No dependency on WordPress being online

Generate Pages

After selecting your content types, click Generate Pages to create the Astro templates.

Generate pages

This creates:

Selected TypeGenerated Files
Postssrc/pages/blog/[slug].astro, src/pages/blog/index.astro
Pagessrc/pages/[slug].astro
Categoriessrc/pages/category/[slug].astro, src/pages/category/index.astro
Tagssrc/pages/tag/[slug].astro, src/pages/tag/index.astro
Authorssrc/pages/author/[slug].astro, src/pages/author/index.astro
Custom Post Typessrc/pages/{type}/[slug].astro, src/pages/{type}/index.astro

It also creates supporting files:

  • src/lib/wordpress.ts - WordPress API client
  • src/components/FeaturedImage.astro - Featured image component
  • astro.config.mjs - Updated with WordPress image domains
⚠️

If files already exist, you'll be asked to confirm before overwriting.

Advanced Tab

The Advanced tab contains security and automation settings.

Take WordPress Offline (Optional)

If you want to completely hide your WordPress site from the public, PhantomWP can help you set up access restrictions:

  1. Expand the Take WordPress Offline section
  2. Copy your Secret Key (auto-generated)
  3. Configure your server to only allow requests with this key

Security settings

PhantomWP sends the secret as the X-PhantomWP-Secret header with every request. Server configuration examples are provided for:

  • Cloudflare Worker
  • Nginx
  • Apache

See WordPress Security for detailed setup instructions.

Webhooks

Set up automatic rebuilds when WordPress content changes:

  1. Expand the Webhooks section
  2. Click Generate Webhook Secret
  3. Copy the webhook URL
  4. Add it to your WordPress site (using a webhook plugin)

Webhook settings

When you publish or update content in WordPress, it triggers a rebuild of your Astro site.

What Gets Saved

When you save your WordPress configuration:

  1. Database - URL and settings persist across devices
  2. Environment file - .env is created in your Codespace with:
    • WP_API_URL - WordPress API endpoint
    • WP_ACCESS_SECRET - Secret key for secure access
  3. Dev server restarts - Changes take effect immediately

Prerequisites

Your WordPress site needs:

  • WordPress 4.7+ (REST API enabled by default)
  • Published content (drafts aren't accessible via API)
  • Public REST API access (or configured authentication)

Troubleshooting

Connection Failed

Check that:

  1. Your WordPress site is online
  2. The URL is correct (include https://)
  3. REST API isn't blocked by a security plugin

Test manually: visit https://yoursite.com/wp-json/wp/v2/posts

No Content Found

Make sure:

  1. You have published posts/pages (not drafts)
  2. Content isn't password-protected
  3. Posts are visible to the REST API

REST API Blocked

Some security plugins disable the REST API:

  1. Check plugin settings (Wordfence, iThemes Security, etc.)
  2. Whitelist PhantomWP's access
  3. Or use the Advanced tab's security method instead

Next Steps

Previous
Claude Code CLI
Next
Browsing Data