astro-wordpress

Astro adapter for WordPress theme development

This adapter enables you to build WordPress themes using Astro.
It allows you to create WordPress template files using .php.astro components under the pages/ directory.

Features

- Write WordPress themes using Astro's component syntax
- Hot-reload via proxying your local WordPress server during development
- Use .php.astro files to generate WordPress template files

Installation

$3

- A working local WordPress site (e.g., running at http://localhost:8001)

$3

1. Create a new Astro project

``bash
npm create astro@latest
`

2. Add the astro-wordpress adapter

`bash
npx astro add astro-wordpress
`

3. Update your astro.config.mjs

`js
// @ts-check
import { defineConfig, passthroughImageService } from "astro/config";
import wordpress from "astro-wordpress";

// https://astro.build/config
export default defineConfig({
adapter: wordpress({
devProxyTarget: "http://localhost:8001", // Your local WordPress URL
outDir: "../wp-path/wp-content/themes/my-theme", // Output theme directory
}),
image: {
service: passthroughImageService(),
},
});
`

4. Add a style.css file to your public/ directory, This is required by WordPress to recognize the theme

`css
/*!
Theme Name: My Theme
Version: 0.0.1
*/
`

5. Create a php layout (e.g., src/layouts/Layout.astro)

`astro

lang=""
dir=""
>

} />


} />




} />


`

6. Add a index template src/pages/index.php.astro

`astro
---
import Layout from "../layouts/Layout.astro";
---


}>
} />



} />

set:html={ if (have_posts()) :
while (have_posts()) : the_post(); ?>

the_content();
wp_link_pages();

endwhile;

if (get_next_posts_link()) {
next_posts_link();
}

if (get_previous_posts_link()) {
previous_posts_link();
};

else : ?>

No posts found. :(

}
/>

`

7. Start the dev server

`bash
npm run dev
`

8. Activate the theme in the WordPress admin panel

Build for Production

To generate your theme for production:

`bash
npm run build
`

The output will be generated in the directory you configured in outDir. You can zip the contents and upload them as a theme in WordPress.

Importing PHP Files

You can import raw .php files into Astro components.

$3

`astro
---
import myPhpCode from "../php-codes/my-code.php";
---

My php code result:


{myPhpCode}
`

Custom Page Template

Due performance considerations, it's not currently possible to define custom page templates using the traditional / Template Name: ... / comment inside .php.astro files.

To define a custom page template in your Astro project, prefix the route filename with page-template-. for example:

`
src/pages/page-template-my-custom-template.php.astro
`

the Template Name comment will be automatically injected, allowing WordPress to recognize it as a valid custom page template.

Resulting WordPress Template Name:

`php
/ Template Name: My Custom Template /
``