Astro per sviluppatori WordPress

Astro è un framework web per la creazione di siti web orientati ai contenuti. Quando si utilizza EmDash, Astro sostituisce il tuo tema WordPress: gestisce il templating, il routing e il rendering.

Questa guida insegna i fondamenti di Astro mappandoli sui concetti WordPress che già comprendi.

Cambiamenti di paradigma chiave

Struttura del progetto

I temi WordPress hanno una struttura piatta con nomi di file magici. Astro utilizza directory esplicite:

L’albero seguente mostra un layout tipico di progetto Astro:

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

Componenti Astro

I file .astro sono l’equivalente Astro dei template PHP. Ogni file ha due parti:

1. Frontmatter (tra i delimitatori ---) — Codice lato server, come PHP all’inizio di un template
2. Template — HTML con espressioni, come il resto di un template PHP

Il seguente componente dichiara props tipizzate nel frontmatter e le renderizza nel 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>

Differenze chiave da PHP:

• Il frontmatter è isolato. Le variabili dichiarate lì sono disponibili nel template, ma il codice stesso non raggiunge mai il browser.
• Gli import vanno nel frontmatter. Componenti, dati, utility: tutto viene importato in alto.
• TypeScript funziona. Definisci i tipi di props con interface Props per l’autocompletamento dell’editor e la validazione.

Espressioni di template

I template Astro usano {parentesi graffe} invece dei tag <?php ?>. La sintassi è simile a JSX ma genera HTML puro.

---
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; ?>

Pattern di espressione

Props e Slots

I componenti ricevono dati tramite props (come argomenti di funzione) e slots (come punti di inserimento do_action).

---
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() passa i dati tramite l’array $args. Le props Astro sono tipizzate e destrutturate:

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

Slots vs Hooks

WordPress utilizza do_action() per creare punti di inserimento. Astro utilizza gli slot:

La differenza: gli slot ricevono elementi figli nel sito di chiamata, mentre gli hook di WordPress richiedono chiamate add_action() separate altrove.

Layout

I layout avvolgono le pagine con una struttura HTML comune: il <head>, header, footer e tutto ciò che è condiviso tra le pagine. Questo sostituisce header.php + footer.php. Il seguente layout definisce quella shell condivisa ed espone uno slot per il contenuto della pagina:

---
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>

Utilizza il layout in una pagina:

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

Stili

Astro offre diversi approcci di stilizzazione. Il più distintivo sono gli stili con ambito.

Stili con ambito

Gli stili in un tag <style> sono automaticamente limitati a quel componente:

<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>

L’HTML generato include nomi di classe univoci per prevenire la fuoriuscita di stili, in modo che gli stili dei componenti rimangano contenuti senza aumentare la specificità del selettore.

Stili globali

Per stili a livello di sito, crea un file CSS e importalo in un layout:

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

Classi condizionali

La direttiva class:list sostituisce la costruzione manuale di stringhe di classe:

---
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)); ?>">

JavaScript lato client

Astro invia zero JavaScript per impostazione predefinita. Questo è il più grande cambiamento mentale da WordPress.

Aggiungere interattività

Per interazioni semplici, aggiungi un tag <script>:

<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>

Gli script vengono automaticamente raggruppati e deduplicati. Se questo componente appare due volte su una pagina, lo script viene eseguito una volta.

Componenti interattivi avanzati

Per un’interattività più complessa, Astro può caricare componenti JavaScript (React, Vue, Svelte) su richiesta. Questo è opzionale: la maggior parte dei siti funziona bene con solo tag <script>. La seguente pagina carica un componente solo quando scorre nella vista:

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

Routing

Astro utilizza il routing basato su file. I file in src/pages/ diventano URL:

Route dinamiche

Per contenuti CMS, utilizza la sintassi con parentesi per segmenti dinamici:

---
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>

Confronto con WordPress

Dove vivono i concetti WordPress

Un riferimento per trovare l’equivalente Astro/EmDash delle funzionalità WordPress:

Templating

Dati e query

Estensibilità

Tipi di contenuto

Mappatura dei concetti

I principali cambiamenti da WordPress ad Astro trattati in questa guida:

• I template PHP diventano componenti Astro: codice server più HTML, con organizzazione file esplicita.
• I tag di template diventano props e import: i dati fluiscono attraverso argomenti invece di globali.
• I file del tema diventano una directory di pagine: gli URL corrispondono alla struttura dei file.
• Gli hook diventano slot e middleware: i punti di inserimento sono definiti dove viene passato il contenuto.
• jQuery si carica per impostazione predefinita in WordPress; Astro non invia JavaScript finché non lo aggiungi.

Inizia con la guida Getting Started per creare il tuo primo sito EmDash, o esplora Working with Content per imparare a interrogare e renderizzare dati CMS.