Backend handoff from Astro — the clean way

The Astro project is done.

Every component is built, every page is composed, every prop is typed. The frontend developer hands it over to the backend team.

And then nothing happens for two weeks.

Not because the backend developer is slow. Because they’re spending that time reverse-engineering what the frontend means.

What usually goes wrong

A typical handoff package is:

• a zip of the Astro source
• a Loom video walking through the components
• a Notion page with “here are the main components and what they do”

None of that is wrong. But none of it answers the only question that matters for a backend developer:

For each page, which variables do I need to provide, in what shape, at what route?

The Notion doc describes intent. The backend developer needs a contract.

What a clean handoff looks like

A proper Astro-to-backend handoff delivers three things:

1. Templates that match the frontend structure

Not a description of the components. The actual templates — in Twig or plain PHP — with the correct HTML structure, correct class names, and correct variable slots.

{# partials/hero.twig #}
<section class="hero">
  <h1>{{ fm.props.headline }}</h1>
  {% if fm.props.sub %}<p>{{ fm.props.sub }}</p>{% endif %}
</section>

The backend developer doesn’t have to read Astro. They get files they can use directly.

2. A variable manifest

A machine-readable map of what variables each template expects:

{
  "partials": {
    "hero": {
      "headline": { "type": "string", "required": true },
      "sub": { "type": "string", "required": false }
    }
  }
}

This is the contract. The backend developer knows exactly what to inject without reading the frontend source.

3. An integration guide

A human-readable document that explains, per page:

• which templates are composed
• which variables are required
• where the data is expected to come from (CMS field, database column, API response)

## Page: /

Templates: layouts/base.twig → pages/index.twig

Partials:
- hero: { headline, sub?, ctaLabel?, ctaHref? }
- section: { title, text? }

Data source: connect to your CMS or database per field above.

With these three artifacts, the backend developer can start on day one.

The structural insight

An Astro component already contains everything needed to generate this package.

The Props interface is the variable manifest. The JSX structure is the template body. The page composition is the routing and include structure.

---
export interface Props {
  headline: string;  // → {{ fm.props.headline }}
  sub?: string;      // → {% if fm.props.sub %}
}
---
<section class="hero">
  <h1>{headline}</h1>
  {sub && <p>{sub}</p>}
</section>

Nothing has to be reinvented. The structure is already there in the Astro source. It just has to be extracted and translated.

Why this is usually done manually — and shouldn’t be

Most teams do this translation by hand, once, at the end of the project.

The problems start when the frontend changes:

• a new prop is added to a component
• an optional prop becomes required
• a component is split into two
• a page is restructured

Every change requires updating the templates, the manifest, and the integration guide. By hand. With no guarantee of consistency.

The correct approach is to generate the handoff package from the Astro source automatically — at build time, every time.

Frontmatter Solo does exactly this. It reads your Astro project, extracts the Props interfaces, maps them to Twig or PHP templates, and outputs the full package in a single command:

frontmatter solo:build --adapter twig
# or
frontmatter solo:build --adapter php

The output is:

output/
├─ pages/
├─ layouts/
├─ partials/
├─ manifest.json
└─ INTEGRATION.md

Same structure. Same variables. Always in sync with the Astro source.

The rule

A clean handoff is not documentation.

It’s a contract — expressed as templates, manifest, and integration guide — that the backend developer can use without reading the frontend source.

If your backend developer has to open an .astro file to understand what variables to provide, the handoff is not done.

Generate it. Don’t write it.

Frontmatter Solo automates the generation of this contract. It does not replace backend integration or application logic.

Scope

Frontmatter Solo:

• generates templates (Twig or PHP)
• defines a variable contract (manifest + INTEGRATION.md)

It does not:

• integrate with your backend
• fetch data
• configure a CMS
• provide runtime behavior

Integration is explicit and owned by the host application.