Astro for WordPress Developers

Astro is a web framework for building content-focused websites. When using EmDash, Astro replaces your WordPress theme—it handles templating, routing, and rendering.

This guide teaches Astro fundamentals by mapping them to WordPress concepts you already understand.

Key Paradigm Shifts

Project Structure

WordPress themes have a flat structure with magic filenames. Astro uses explicit directories:

A typical Astro project:

src/
├── components/        # Reusable UI (Header, PostCard, etc.)
├── layouts/           # Page shells (Base.astro)
├── pages/             # Routes - files become URLs
│   ├── index.astro    # → /
│   ├── posts/
│   │   ├── index.astro      # → /posts
│   │   └── [slug].astro     # → /posts/hello-world
│   └── [slug].astro   # → /about, /contact, etc.
└── styles/
    └── global.css

Astro Components

.astro files are Astro’s equivalent of PHP templates. Each file has two parts:

1. Frontmatter (between --- fences) — Server-side code, like PHP at the top of a template
2. Template — HTML with expressions, like the rest of a PHP template

---
// Frontmatter: runs on server, never sent to browser
interface Props {
  title: string;
  excerpt: string;
  url: string;
}

const { title, excerpt, url } = Astro.props;
---
<!-- Template: outputs HTML -->
<article class="post-card">
  <h2><a href={url}>{title}</a></h2>
  <p>{excerpt}</p>
</article>

Key differences from PHP:

• Frontmatter is isolated. Variables declared there are available in the template, but the code itself never reaches the browser.
• Imports go in frontmatter. Components, data, utilities—all imported at the top.
• TypeScript works. Define prop types with interface Props for editor autocomplete and validation.

Template Expressions

Astro templates use {curly braces} instead of <?php ?> tags. The syntax is JSX-like but outputs pure HTML.

---
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts");
const showTitle = true;
---
{showTitle && <h1>Latest Posts</h1>}

{posts.length > 0 ? (
  <ul>
    {posts.map(post => (
      <li>
        <a href={`/posts/${post.id}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
) : (
  <p>No posts found.</p>
)}

<?php
$posts = new WP_Query(['post_type' => 'post']);
$show_title = true;
?>

<?php if ($show_title): ?>
  <h1>Latest Posts</h1>
<?php endif; ?>

<?php if ($posts->have_posts()): ?>
  <ul>
    <?php while ($posts->have_posts()): $posts->the_post(); ?>
      <li>
        <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
      </li>
    <?php endwhile; wp_reset_postdata(); ?>
  </ul>
<?php else: ?>
  <p>No posts found.</p>
<?php endif; ?>

Expression Patterns

Props and Slots

Components receive data through props (like function arguments) and slots (like do_action insertion points).

---
interface Props {
  title: string;
  featured?: boolean;
}

const { title, featured = false } = Astro.props;
---
<article class:list={["card", { featured }]}>
  <h2>{title}</h2>
  <slot />
  <slot name="footer" />
</article>

<Card title="Hello" featured>
  <p>This goes in the default slot.</p>
  <footer slot="footer">Footer content</footer>
</Card>

<?php
// Usage: get_template_part('template-parts/card', null, [
//   'title' => 'Hello',
//   'featured' => true
// ]);

$title = $args['title'] ?? '';
$featured = $args['featured'] ?? false;
$class = $featured ? 'card featured' : 'card';
?>
<article class="<?php echo esc_attr($class); ?>">
  <h2><?php echo esc_html($title); ?></h2>
  <?php
  // No direct equivalent to slots.
  // WordPress uses do_action() for similar patterns:
  do_action('card_content');
  do_action('card_footer');
  ?>
</article>

Props vs $args

In WordPress, get_template_part() passes data via the $args array. Astro props are typed and destructured:

---
// Type-safe with defaults
interface Props {
  title: string;
  count?: number;
}
const { title, count = 10 } = Astro.props;
---

Slots vs Hooks

WordPress uses do_action() to create insertion points. Astro uses slots:

The difference: slots receive child elements at the call site, while WordPress hooks require separate add_action() calls elsewhere.

Layouts

Layouts wrap pages with common HTML structure—the <head>, header, footer, and anything shared across pages. This replaces header.php + footer.php.

---
import "../styles/global.css";

interface Props {
  title: string;
  description?: string;
}

const { title, description = "My EmDash Site" } = Astro.props;
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content={description} />
    <title>{title}</title>
  </head>
  <body>
    <header>
      <nav><!-- Navigation --></nav>
    </header>

    <main>
      <slot />
    </main>

    <footer>
      <p>&copy; {new Date().getFullYear()}</p>
    </footer>
  </body>
</html>

Use the layout in a page:

---
import Base from "../layouts/Base.astro";
---
<Base title="Home">
  <h1>Welcome</h1>
  <p>Page content goes in the slot.</p>
</Base>

Styling

Astro offers several styling approaches. The most distinctive is scoped styles.

Scoped Styles

Styles in a <style> tag are automatically scoped to that component:

<article class="card">
  <h2>Title</h2>
</article>

<style>
  /* Only affects .card in THIS component */
  .card {
    padding: 1rem;
    border: 1px solid #ddd;
  }

  h2 {
    color: navy;
  }
</style>

The generated HTML includes unique class names to prevent style leakage. No more specificity wars.

Global Styles

For site-wide styles, create a CSS file and import it in a layout:

---
import "../styles/global.css";
---

Conditional Classes

The class:list directive replaces manual class string building:

---
const { featured, size = "medium" } = Astro.props;
---
<article class:list={[
  "card",
  size,
  { featured, "has-border": true }
]}>

<?php
$classes = ['card', $size];
if ($featured) $classes[] = 'featured';
if (true) $classes[] = 'has-border';
?>
<article class="<?php echo esc_attr(implode(' ', $classes)); ?>">

Client-Side JavaScript

Astro ships zero JavaScript by default. This is the biggest mental shift from WordPress.

Adding Interactivity

For simple interactions, add a <script> tag:

<button id="menu-toggle">Menu</button>
<nav id="mobile-menu" hidden>
  <slot />
</nav>

<script>
  const toggle = document.getElementById("menu-toggle");
  const menu = document.getElementById("mobile-menu");

  toggle?.addEventListener("click", () => {
    menu?.toggleAttribute("hidden");
  });
</script>

Scripts are bundled and deduplicated automatically. If this component appears twice on a page, the script runs once.

Advanced: Interactive Components

For more complex interactivity, Astro can load JavaScript components (React, Vue, Svelte) on demand. This is optional—most sites work fine with just <script> tags.

---
import SearchWidget from "../components/SearchWidget.jsx";
---
<!-- Only load JavaScript when the search box scrolls into view -->
<SearchWidget client:visible />

Routing

Astro uses file-based routing. Files in src/pages/ become URLs:

Dynamic Routes

For CMS content, use bracket syntax for dynamic segments:

---
import { getEmDashCollection, getEmDashEntry } from "emdash";
import Base from "../../layouts/Base.astro";
import { PortableText } from "emdash/ui";

// For static builds, define which pages to generate
export async function getStaticPaths() {
  const { entries: posts } = await getEmDashCollection("posts");
  return posts.map(post => ({
    params: { slug: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
---
<Base title={post.data.title}>
  <article>
    <h1>{post.data.title}</h1>
    <PortableText value={post.data.content} />
  </article>
</Base>

Compared to WordPress

Where WordPress Concepts Live

A reference for finding the Astro/EmDash equivalent of WordPress features:

Templating

Data and Queries

Extensibility

Content Types

Summary

The jump from WordPress to Astro is significant but logical:

1. PHP templates → Astro components — Same idea (server code + HTML), better organization
2. Template tags → Props and imports — Explicit data flow instead of globals
3. Theme files → Pages directory — URLs match file structure
4. Hooks → Slots and middleware — More predictable insertion points
5. jQuery by default → Zero JS by default — Add interactivity intentionally

Start with the Getting Started guide to build your first EmDash site, or explore Working with Content to learn how to query and render CMS data.